Skip to content
PipMCP

Troubleshooting

What common MCP, authentication, network and usage errors mean and how to fix them.

Start with Executions in the dashboard: every tool call that reached the policy engine is logged with its error code, message and trace ID. Protocol-level errors (bad headers, invalid tokens) happen before that and are only visible to the client.

401 Unauthorized

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://pipmcp.com/.well-known/oauth-protected-resource/mcp/<workspace>/<endpoint>", scope="tools:list tools:call"

The request had no valid endpoint access token. Check that:

  • the header is exactly Authorization: Bearer pmcp_… (no quotes, no extra spaces);
  • the token belongs to this endpoint: tokens are bound to one endpoint;
  • the token has not been revoked or expired (see the endpoint page);
  • you copied the whole token when it was shown. If in doubt, create a new one.

Some clients read the WWW-Authenticate header and try to start an OAuth sign-in. PipMCP endpoints use bearer tokens, so configure the token as a header instead.

For the management API, a 401 with UNAUTHENTICATED means the pmk_ token is missing or invalid.

403 Forbidden

  • The access token cannot call tools.: the token has only the tools:list scope. Create a token with tools:call.
  • This MCP endpoint is not active.: the endpoint is disabled or the workspace is suspended.
  • Origin not allowed.: a browser-based client sent an Origin that is not on the allowed list.

-32020 Header mismatch

{"error": {"code": -32020, "message": "Header mismatch: Mcp-Method does not match the request body"}}

MCP 2026-07-28 requires headers that mirror the body. For every request, MCP-Protocol-Version must equal params._meta["io.modelcontextprotocol/protocolVersion"] and Mcp-Method must equal method. For tools/call, Mcp-Name must equal params.name. Update the headers, or update your MCP client library.

-32022 Unsupported protocol version

{"error": {"code": -32022, "message": "Unsupported protocol version: 2024-11-05", "data": {"supported": ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26"], "requested": "2024-11-05"}}}

The client asked for a version PipMCP does not speak. error.data.supported lists the ones it does. Upgrade the client. 2025-era clients must start with initialize and then send the negotiated version in MCP-Protocol-Version.

-32602 Missing client capabilities

Missing required _meta field: io.modelcontextprotocol/clientCapabilities: in 2026-07-28 every request needs params._meta["io.modelcontextprotocol/clientCapabilities"], even if it is {}.

404 MCP endpoint not found

The workspace or endpoint slug in the URL is wrong, or the endpoint was deleted. Copy the URL from the endpoint page. The format is https://mcp.pipmcp.com/<workspace>/<endpoint>.

405 Method not allowed

The client sent a GET (often to open an event stream) or a DELETE. PipMCP answers every request with a single JSON response over POST and has no sessions; configure the client for Streamable HTTP without SSE, or update it.

No tools are listed

  • The integration has no published version yet: publish it.
  • The endpoint's connection for that integration is missing or disabled.
  • The tools are disabled, or the endpoint uses Selected tools and none are ticked.

BLOCKED_DESTINATION

The upstream request would go to an address PipMCP does not call: localhost, a private range such as 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16, a link-local or cloud metadata address, a non-standard port, or a host not on the connection's allowed-host list. Redirects are checked the same way.

PipMCP only reaches APIs on the public internet. If your API is internal, expose it through a public, authenticated gateway. A private network gateway is planned for Enterprise; contact us if you need it.

TOKEN_EXPIRED

The OAuth access token for the connection expired and could not be refreshed (the refresh token was revoked, expired or rejected). Open the connection and choose Reconnect to sign in again. Calls work again as soon as the connection has a fresh token.

AUTH_FAILED

The upstream API rejected the credentials (HTTP 401). Check the secret on the connection, the header or query parameter name, and whether the key has been rotated. Enter a new value and use Test connection.

CONFIRMATION_REQUIRED

The action is protected by your endpoint's preset or a policy and was not executed. If the error includes an approval_id, approve it under Executions, then repeat the identical call (same tool, arguments and token) within 24 hours. See Permissions and risk.

POLICY_DENIED

A deny policy or the endpoint preset blocks this action; the message names which. Change the policy or preset if the action should be allowed, or use a different endpoint.

USAGE_LIMIT_REACHED

The workspace has used its agent actions for this month and the plan has no overage. Tool calls resume at the start of the next month, or immediately after upgrading under Billing. Discovery requests such as tools/list keep working.

RATE_LIMITED and HTTP 429

  • HTTP 429 from PipMCP (JSON-RPC code 42900): too many MCP requests per minute for the token, endpoint or workspace. Wait for the Retry-After seconds.
  • RATE_LIMITED tool error: the upstream API returned 429. The error is retryable and includes retry_after_seconds when the API sent it.

UPSTREAM_TIMEOUT / UPSTREAM_UNAVAILABLE

Your API did not answer in time or returned a server error. Tool calls through MCP wait at most 25 seconds. Check your API's health; for slow operations, reduce the amount of data the tool requests.

Still stuck?

Open a request under Help & support in the dashboard (or contact us if you can't log in) and include the trace ID from the execution. It lets us find the exact request without you sending any data.