MCP troubleshooting

Start with Test my key under Account, Connect your agent. It runs the same discover and tools/list calls a client makes, with your key, and tells you what failed.

401 and "not valid" or "Missing API key"

The header did not reach the server, or the variable is empty. Print it (echo $HARNESSLAB_API_KEY), then open a new terminal: a variable set a moment ago is not in terminals that were already open. Paste the key into Test my key to see whether it is valid.

401 and "expired"

The key reached its expiry. Rotate it in the app (Account, Connect your agent) or make a new key, update the variable and restart the client.

401 and "revoked"

Someone, perhaps you, revoked the key. Make a new one.

429 "Rate limit"

More than the key's calls a minute. Wait the seconds in the message; clients that call tools/list on every message can cache the list (the server says it may be cached for five minutes).

429 "Monthly limit" or "Daily output budget"

The key used its month or day. The message says when it resets (00:00 UTC). Test my key shows what it used.

The server does not appear in my client

Restart the client. In Claude Code type /mcp. In Cursor and Windsurf check the file path, and for Windsurf press refresh. In VS Code the file needs the top-level key servers and "type": "http".

The server shows but has no tools

The key may have been refused after the connection. Run the curl check in the quickstart, or Test my key.

ask says "This key may only use the free tools"

Make a key with the scope free+ask and use that one for ask.

Gemini CLI answers 401 with the settings.json form

Its documentation does not say that headers expand environment variables. Use the gemini mcp add command, which writes the value.

Cursor does not see the variable

Cursor read the environment it was started from. Start it from a terminal that has the variable, or set the variable for your whole account and restart Cursor.

Claude Desktop has no place for a header

Add the server as a custom connector (Customize, Connectors, Add custom connector), choose No sign in, and add the request header there. A configuration file cannot hold a remote server.

A browser page gets 403

The server refuses requests that come from web pages (an Origin header). Call it from a program, a CLI or an IDE.

Behind a company proxy

The client must reach https://app.harnesslab.co/mcp over HTTPS and may not strip the Authorization header. Ask your network team to allow it.

Check from the command line

If curl works and your client does not, the problem is in the client’s configuration. The commands are in the quickstart and on the clients page.