Skip to content
Toado Docs

Troubleshooting MCP

If the MCP integration is not working, walk this list top to bottom. The most common causes are env-var issues and stale config.

”MCP server failed to start” / “Cannot connect”

The hosted endpoint is https://mcp.toado.dev/mcp. If your client cannot connect:

  • Check the URL. Typos and a trailing slash are the two most common bugs. The correct URL has no trailing slash.
  • Check your network. From a terminal, curl -I https://mcp.toado.dev/mcp should return an HTTP response (not a connection error). If it fails, you have a corporate proxy, VPN, or firewall in the way.
  • Check the config syntax. A trailing comma or unbalanced brace silently breaks Claude Desktop, Cursor, and Codex config loading. Paste your config into a JSON or TOML validator if unsure.
  • Restart the host app. Claude Desktop, Cursor, and Codex all load MCP config at process start. After editing config, fully quit (not just close the window) and relaunch.

”401 unauthorized” on every call

Your token is wrong, expired, or revoked.

  • Open Toado web app, Settings › API tokens, and confirm the token still appears in the list. If not, it was revoked: create a new one.
  • Confirm TOADO_API_TOKEN is set in the environment block of your MCP config. A common mistake is to put the token in the wrong key (e.g., args instead of env).
  • Check for whitespace. Pasting from a confirmation toast sometimes picks up a trailing newline. Re-copy carefully.

”403 forbidden” on a specific tool

The token’s scopes do not include the scope this tool requires.

  • Check the scope matrix. For example, add_comment needs comments; move_ticket needs tickets:write.
  • If the token is project- or company-restricted, the resource may be outside its scope. Cross-company moves always return 403.

Re-issue the token with broader scopes (or restrict your operations to the scopes the token already has).

“429 rate limited”

You hit the per-token write or read budget.

  • Default reads: 600 / minute / token.
  • Default writes: 60 / minute / token.

The response includes a retry_after header in seconds. Wait that long and retry. For long bulk operations, prefer bulk_move_tickets and bulk_assign_tickets, which call sequentially server-side and stay inside the budget.

If you hit the limit during normal interactive use, the token is probably being shared between an active session and a background job. Issue separate tokens.

Tools list is empty in the client

Claude can connect to the server but reports no tools.

  • The server is up but mis-configured. Check the server’s stderr (Claude Code logs MCP server stderr in the agent inspector; Claude Desktop logs to a file).
  • The token may be missing from the env. The server starts even without a token, but the tool listing depends on a successful /me call.

Hosted endpoint issues

For the hosted endpoint at https://mcp.toado.dev/mcp:

  • If you are using the OAuth flow, the consent tab closes automatically after approval. If it hangs open with a “redirect” error, your client most likely registered a stale callback URL; remove and re-add the server in your client.
  • If you are using a token, the auth header must be Authorization: Bearer tok_.... A wrong scheme (Token, Basic) is rejected at the edge.
  • Corporate proxies sometimes strip the Authorization header. The browser-based OAuth flow is more resilient than direct token auth in those environments because tokens are never sent through the proxy.
  • The /mcp endpoint speaks HTTP transport. If your client is hard-coded to expect SSE, update it; modern MCP clients all support HTTP transport.

”ticket not found”

  • Check the id is right. Toado ticket ids are t- followed by 6 to 12 alphanumerics.
  • Confirm the token can see the ticket’s project. A token restricted to co_a cannot see tickets in co_b.
  • The ticket may be archived. Use list_tickets(status='archived') to confirm, then restore_ticket if you want to bring it back.

”I changed scopes but it still says forbidden”

Scopes are baked into the token at creation. To change scopes, create a new token with the new scope set, swap your config, and revoke the old one. There is no in-place edit.

Captured data looks empty

get_ticket returns the capture, but console, network, errors come back empty.

  • This is expected on certain pages: CSP-locked sites can block the in-page injection that captures console; the screenshot still works. The capture metadata flags this.
  • The page may have loaded before the extension was active. Capture history starts from extension load, not page load.
  • See Capture edge cases for the full list.

Where to ask for help

If none of the above resolves it:

  • Browse GitHub Discussions (your question may already be answered).
  • Contact us with: client name and version, MCP config snippet (with the token redacted), and any stderr output you can capture.