Troubleshooting

Common issues when connecting or calling tools, and what causes each one.

"Authentication required" on connect

The server requires a Bearer access token on every request — a plain GET to the server URL (e.g. opening it in a browser) always returns this; it isn't an error with your setup.

{
  "error": "Authentication required. POST with Authorization: Bearer <token>."
}

Requests that worked before suddenly fail

Access tokens expire after 1 hour. A working client refreshes automatically using its refresh token — if yours doesn't, reconnect it.

A previously-working client stopped working entirely

Someone in your agency may have revoked that client's connection from Settings → Developer → MCP Connections. Reconnect it to get a fresh grant.

"Tool not found" or a similarly-named tool is missing

Tool names are exact and case-sensitive — check this reference for the precise name. If you're using a client in "compact" or "code mode", only the discovery tools (search_os_tools, call_os_tool, ...) are listed directly; use those to find and call the rest by name.

A tool call is rejected for missing access

The connection only has mcp:read (read-only) — reconnect and approve write access if the tool you're calling needs it.

Rate limits

There is currently no rate limit specific to MCP tool calls — unlike the REST API's per-agency, plan-based limit.