Troubleshoot MCP connections

Symptom	Check
Cannot connect	Hosted app /mcp URL, HTTPS and HTTP/Streamable HTTP type
GET returns 405	Server supports POST JSON, not a persistent GET stream
Unauthorized	Manual header forwarding, token expiry/revocation or OAuth completion
OAuth unavailable	Hosted OAuth availability and client browser support; use a manual grant if appropriate
Unexpected account	Bound grant/approved account; browser account switching alone does not rebind a connection
Missing tools	Effective primary scopes and current role; reload discovery after changes
Discovered write fails forbidden	Nested assignment scopes or private-custom-dashboard restriction
REST rejects OAuth token	OAuth access is MCP-audience-bound; REST needs a manual grant
Quota error	No completed write; inspect capabilities and returned billing guidance
Rate limited	Shared automation limits; wait for Retry-After
Desktop bridge fails to launch	Absolute npx path, Node PATH, private env value and correct Desktop Chat config

A raw browser GET is not a successful MCP connection test. Use the client’s connection status/tool discovery, then perform a capabilities read.

For Copilot manual setup, if interactive testing omits the configured Authorization header, use the private user file and restart the client. For Claude, distinguish Desktop Chat, Desktop Code and CLI hosts before editing configuration.

Do not fall back to legacy SSE, disable TLS checks, make tokens non-expiring or broaden permissions just to hide an error. Preserve other client settings when merging entries.

Retain nonsensitive error code, client/version and request context for support. Redact bearer headers, heartbeat URLs, private config and customer data.