Troubleshooting

Fix common problems with the Catio MCP.

Troubleshooting

If Archie or the inventory tools are not responding from your coding assistant, start here.

Authentication loop / browser doesn't redirect back

If the browser completes the login but the client doesn't pick up the token, copy the full callback URL from the browser's address bar and paste it into the prompt that appears in your client.

"unauthorized" errors after connecting

Your session may have expired. Re-authenticate: clear the existing auth in your client.

Client shows server as "failed" or "disconnected"

Verify that https://mcp.catio.tech/mcp is reachable. If you're behind a corporate proxy or VPN, ensure mcp.catio.tech is not blocked.

Tool not appearing in your client

Some clients require a restart after adding a new MCP server. Restart your client and confirm the Catio server shows as connected before retrying.

OAuth not supported by your client

If your client does not support the MCP OAuth flow, create an API key in the Catio console under Settings → API keys and configure it as a static bearer token. See MCP Setup.

"unauthorized" errors with an API key

The key is invalid, expired, or revoked. Revoking a key and suspending its owner take effect within about a minute, so if you just revoked or rotated, wait a moment and retry.

"forbidden" errors with an API key

The key works, but it does not carry the permission the tool needs. Edit the key's permissions under Settings → API keys.

Key errors mention workspace_id

Every tool call must name the workspace it works in through workspace_id, except list_workspaces. Call list_workspaces first to see the workspaces the key can reach.


Did this page help you?