MCP won't connect
The Hoursmith MCP server needs a valid hsk_ token in env or HTTP headers, a Studio or Agency plan, Node 18+, and a client restart or reconnect.
If your MCP client can't reach Hoursmith, it's nearly always the API token, the Node version, where the config lives, or the HTTP URL/header setup. Work through the checks below.
Most likely cause
The MCP server needs a token that starts with hsk_ and a Studio
Studio or Agency Agency plan. Stdio clients provide it
as HOURSMITH_API_TOKEN; HTTP clients provide it as a request header. The most common failures
are a token that's missing, wrong, or from a Free workspace (which returns 402), Node too
old, the config file or HTTP URL in the wrong place, or simply not restarting or reconnecting
the MCP client after editing config.
How to check
- Token set and valid? For stdio, confirm
HOURSMITH_API_TOKENbegins withhsk_. For HTTP, confirm the client sendsAuthorization,x-api-key,api-key, orx-hoursmith-api-key. - Workspace plan. A token from a Free workspace yields 402 — you need Studio or Agency.
- Node version. The server needs Node 18+.
- Config location. Make sure the MCP config is in the correct file for your client.
- HTTP URL. For HTTP clients, use the local endpoint, usually
http://localhost:8000/mcp/. - Restarted? Config changes only take effect after you restart or reconnect the MCP client.
How to fix
Set a valid token
For stdio clients, set HOURSMITH_API_TOKEN to a token that starts with hsk_. For HTTP
clients, send the token as Authorization: Bearer hsk_..., x-api-key, api-key, or
x-hoursmith-api-key. If it's missing or wrong, the server can't authenticate. (Optionally set
HOURSMITH_API_URL.)
Use a Studio or Agency workspace
If you get 402, the token is from a Free workspace. Use a token from a Studio or Agency workspace instead.
Update Node and the run command
Make sure you're on Node 18+. Stdio clients launch with npx -y @hoursmith/mcp-server.
HTTP clients run the same package with HOURSMITH_MCP_TRANSPORT=http and connect to
http://localhost:8000/mcp/.
Fix the config location, then restart
Put the config in the right file for your MCP client, or the right URL/header fields for an HTTP client, then restart or reconnect — edits don't apply until it reloads.
After any config change, restart or reconnect your MCP client. A surprising number of "won't connect" reports are just a client that hasn't reloaded the new settings.
Still stuck?
If your token starts with hsk_, the workspace is Studio or Agency, Node is 18+, and the config or
HTTP URL is in the right place after a restart, email hi@hoursmith.app.
See Install MCP and MCP troubleshooting.