Troubleshooting
Fix common Hoursmith MCP problems — missing or wrong token, 402 plan errors, old Node, the wrong config path, and forgetting to restart.
When the Hoursmith MCP server won't start or every call fails, it's almost always one of five things: the token, the plan, the Node version, the config path, or a missing restart. Work through these in order.
1. Token missing or not starting with hsk_
The server requires HOURSMITH_API_TOKEN, and the value must start with hsk_. If it's
absent or malformed, the server can't authenticate.
Fix: Open your client's config and confirm HOURSMITH_API_TOKEN is set to a token that begins
with hsk_. Create one in Settings → API if needed — tokens are
shown only once.
2. 402 plan error
A 402 means the token's workspace is on the Free plan, which doesn't include API access. Every call fails until you upgrade.
Fix: Move the workspace to Studio Studio or Agency Agency in Billing & plans, then try again.
3. Node too old
The server needs Node.js 18+. On older versions, npx -y @hoursmith/mcp-server may fail to launch.
Fix: Check your version and update if it's below 18:
node --version4. Wrong config file path
Each client reads its MCP config from a specific file. If you edit the wrong one, the server never loads.
Fix: Double-check the path for your client:
- Claude Desktop (macOS):
~/Library/Application Support/Claude/claude_desktop_config.json - Claude Desktop (Windows):
%APPDATA%\Claude\claude_desktop_config.json - Cursor:
~/.cursor/mcp.json - Zed:
~/.config/zed/settings.json
See the per-client guides: Claude Desktop, Cursor, and other clients.
5. Didn't restart the client
Config changes only take effect after the MCP client reloads.
Fix: Restart the client after editing config. For Claude Desktop, fully quit and reopen — closing the window isn't enough.
A large share of "won't connect" reports are just a client that hasn't reloaded. When in doubt, restart and try again.
Read the client's MCP logs
If you've ruled out all five, check your MCP client's own logs — they usually surface the real
error (a bad token, a network failure, or a non-zero exit from npx). The server logs to stderr,
which most clients capture in their MCP log view.
Self-hosted or staging
If you're pointing at a self-hosted or staging Hoursmith and calls go to the wrong place, set
HOURSMITH_API_URL. You only need this for non-default instances — leave it unset for
https://hoursmith.app.
Still stuck?
If your token starts with hsk_, the workspace is Studio or Agency, Node is 18+, the config is in the
right file, and you've restarted, email hi@hoursmith.app.
Security
How the Hoursmith MCP server handles your token and permissions — it adds nothing beyond the REST API, never stores or prints your token, and uses HTTPS.
Webhooks overview
Webhooks push workspace events to your own HTTPS endpoint in near real time. Available on the Agency plan for Owners and Admins.