Troubleshooting

Common MCP failure modes and how to diagnose them. When a buyer reports the integration "isn't working", the first stop is the Activity tab on the server card — it shows the last 100 tool calls with their status, latency, and error summary.

"MCP server attached", but the list stays empty

Fixed in 2.2.0. Before it, an agent's MCP page listed only servers that already had a tool enabled for that agent. Attaching discovers the server's tools but enables none of them, so a working server dropped out of the list straight away and its Manage tools button could not be reached. Every server of the workspace now shows on every agent's MCP page, with "N of M tools enabled" for that agent.

Server is in "degraded" state

Means the last discovery refresh failed. Click the server card → the error is shown inline. Common causes: server returned 5xx, the endpoint is unreachable, SSL certificate problem, the API key was revoked. Re-run "Test connection" once the underlying issue is fixed; the next successful call returns the status to "active".

Tool grants flipped off after a refresh

A schema-drift detection. The tool's input_schema changed since the last refresh. Open the tool's row in Manage tools, inspect the new schema, re-enable if appropriate.

"Workspace MCP rate limit reached"

More than 60 MCP calls in a minute across the workspace. Either the agent is looping on the same tool (check the audit log for repeats — the runtime dedupes by tool name per turn, but multiple turns can still pile up) or there's genuine high traffic. Per-plan limits can be raised in config/mcp.php if you need higher throughput.

"External integration is temporarily unavailable"

Circuit breaker is open. The server failed 5 times in 60 seconds. Pitchbar waits 60 seconds before retrying. Check the Activity view for the underlying error pattern.

Visitor messages get no MCP-powered answers

Walk the layers from the top:

1. Is the server's status active on the server card?
2. Are any tools enabled for the agent (Manage tools)?
3. Does the visitor's question include a clear intent the LLM can map to a tool? The LLM is biased toward calling a tool only when description and schema match the visitor's request. Improve the server's tool descriptions if the LLM is guessing wrong.
4. Run the Test connection button on the server card — if Test fails, no tool will ever fire.

OAuth token expired

The server's status flips to pending_auth on the next call that returns 401. Reconnect from the admin UI (Phase 3 follow-up). Until then, tool calls for that server return "External integration unavailable" to the LLM and the visitor gets a normal answer based on RAG only.