Skip to content
Hoursmith Docs
Troubleshooting

MCP won't connect

The Hoursmith MCP server needs HOURSMITH_API_TOKEN (starting hsk_) and a Studio or Agency plan, Node 18+, and a restart after editing config.

If your MCP client can't reach Hoursmith, it's nearly always the API token, the Node version, or where the config lives. Work through the checks below.

Most likely cause

The MCP server needs a HOURSMITH_API_TOKEN (it must start with hsk_) and a Studio Studio or Agency Agency plan. It runs via npx -y @hoursmith/mcp-server over stdio, with an optional HOURSMITH_API_URL. 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 in the wrong place, or simply not restarting the MCP client after editing config.

How to check

  • Token set and valid? Confirm HOURSMITH_API_TOKEN is set and begins with hsk_.
  • 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.
  • Restarted? Config changes only take effect after you restart the MCP client.

How to fix

Set a valid token

Set HOURSMITH_API_TOKEN to a token that starts with hsk_. 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+ and the server launches with npx -y @hoursmith/mcp-server over stdio.

Fix the config location, then restart

Put the config in the right file for your MCP client, then restart the client — edits don't apply until it reloads.

After any config change, restart 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 is in the right place after a restart, email hi@hoursmith.app. See Install MCP and MCP troubleshooting.

Was this page helpful?

My webhook is failing

Webhook endpoint marked "failing"? It must return 2xx within ~10s and pass signature verification. Webhooks need the Agency plan.

On this page

Most likely causeHow to checkHow to fixSet a valid tokenUse a Studio or Agency workspaceUpdate Node and the run commandFix the config location, then restartStill stuck?