Troubleshooting

When the Hoursmith MCP server won't start or every call fails, it's usually the token, the plan, the Node version, the config path, an HTTP header/URL mismatch, or a missing restart. Work through these in order.

1. Token missing or not starting with hsk_

For stdio clients, 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.

For HTTP clients, put the token in a request header instead: Authorization: Bearer hsk_..., x-api-key, api-key, or x-hoursmith-api-key.

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 --version

4. 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
• HTTP clients: use the local URL from your running server, usually http://localhost:8000/mcp/

See the per-client guides: Claude Desktop, Cursor, other clients, and Odin / HTTP 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.

6. HTTP endpoint is running, but requests get 401 or 404

HTTP mode is opt-in:

HOURSMITH_MCP_TRANSPORT=http npx -y @hoursmith/mcp-server

The default endpoint is http://127.0.0.1:8000/mcp/. A 401 usually means the client did not send one of the accepted token headers. A 404 usually means the path is wrong — use /mcp/, or match the value you set in HOURSMITH_MCP_PATH.

Read the client's MCP logs

If you've ruled out all six, 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://my.hoursmith.app.

Still stuck?

If your token starts with hsk_, the workspace is Studio or Agency, Node is 18+, the config or HTTP URL is right, and you've restarted or reconnected, email hi@hoursmith.app.