Platform MCP Docs

MCP Troubleshooting

Resolve common initialization, authentication, origin, media type, session, discovery, and argument errors.

Version MCP 2025-11-25 Current Streamable HTTP contract with compatibility versions Reviewed Jul 26, 2026 Next review Oct 26, 2026

Start Reading Report documentation issue Try in a Free Developer Workspace

The free Developer workspace is for non-production building and learning under published limits. External API or MCP client credentials use a separate scoped request and approval process.

Owner: Batoi Developer Experience Reviewed by: Batoi Platform Security Source revision: upgrade-jul-26-2026

On this page

MCP Troubleshooting

Initialization fails

Confirm the URL contains the approved workspace UID or slug.
Send HTTPS POST, JSON-RPC 2.0, and Content-Type: application/json.
For the current protocol, accept both JSON and event stream media types.
Verify the requested protocol version is supported.

Authentication fails

Confirm the host and integration are active.
Confirm the stored credential belongs to this workspace host.
Confirm policy state is approved or explicitly approval-required.
Rotate the credential if expiry or exposure is possible.

Browser request is rejected

The request origin must equal the configured site origin or appear in the server allowlist. Do not work around this control with a public proxy.

A tool is missing

Tool discovery is capability-filtered. A read-only host will not see proposal or approval-gated tools. Request a reviewed capability change instead of guessing a tool name.

Session fails

Reinitialize, retain the newly returned MCP-Session-Id, and send it with the negotiated protocol header. Do not reuse a session across workspaces or credentials.