Skip to main content

MCP

MCP troubleshooting

Tools not showing up, auth errors, transport mismatches, rate-limit confusion — the usual MCP fixes.

Last updated

The usual MCP fixes, in roughly the order you'll encounter them.

Tools don't show up in the agent

Three causes, in order of frequency:

  • Malformed config. Most clients fail silently on invalid JSON / YAML. Validate the file. In Claude Desktop, look for a red dot in Settings → Developer next to the server name.
  • Client wasn't restarted. Most clients load MCP config at startup, not on save. Quit completely and reopen.
  • Wrong command path. npxisn't always on the PATH the desktop app inherits — especially on macOS where GUI apps don't source your shell's rc files. Try the absolute path: /usr/local/bin/npx or wherever which npx reports.

401 / authentication errors when tools fire

  • Token revoked or expired.Tokens don't expire by default but can be revoked from the dashboard. Mint a new one.
  • Token lacks the required scope. The error code is INSUFFICIENT_SCOPE rather than 401. Mint a token with the scope the tool needs (see tools reference).
  • Wrong env var name. The MCP binary reads JOBBYDEV_API_TOKEN exactly. Typos like JOBBY_API_TOKEN get a token-missing error.

Tool calls feel slow

Two reasons:

  • HTTP transport latency.If you're using the hosted endpoint at jobby.dev/api/mcp, every call is a round-trip to our infrastructure. For latency- sensitive workflows, switch to stdio.
  • Cold-start of the stdio binary.Some clients re-spawn the binary per call rather than keeping it alive. Not much you can do about this; it's a 200-400ms penalty.

Rate-limit confusion

Each MCP tool maps 1:1 to a REST endpoint, and rate limits apply per-token at the REST layer. If your agent calls jobbydev_queue_statusin a tight loop, it'll hit the 60/min read limit. The 429 surfaces back to the agent as a tool error; most agents (Claude, ChatGPT) will back off automatically, but Cursor and Continue may surface the error to you as-is. See rate limits.

Mismatch between tool docs and behavior

If a tool seems to take parameters the agent doesn't pass, or returns fields not documented, check that you're running the latest @jobbydev/mcp binary:

npx @jobbydev/mcp --version

And reinstall if older than the latest:

npx -y @jobbydev/mcp@latest --version

Transport mismatch

Some clients (Cursor, Zed, Continue) accept both stdio and HTTP configs but treat them differently. If you've switched between them, double-check the config — leftover stdio config with an HTTP URL field can leave the client in a confused state.

The agent says it called a tool that doesn't exist

LLMs occasionally hallucinate tool names. If the agent reports calling a tool that's not in the official tools reference, verify against the canonical list at tools reference. We don't silently rename or remove tools.

Still stuck?

Contact support with the client name + version, the binary version (above), and the exact error message.