---
title: "MCP error reference"
description: "Look up the error your MCP client printed, and fix it."
canonicalUrl: "https://zuplo.com/learn/mcp/errors"
sourceUrl: "https://zuplo.com/learn/mcp/errors"
pageType: "other"
generatedAt: "2026-10-23"
---

# MCP error reference

> Look up the error your client printed, and fix it.

## Find your error

Paste the string your client printed. Search also matches other wordings clients use for the same cause. 13 documented errors are listed below. Clients rewrite these strings often, so try a shorter fragment or a bare status code such as `401`. If you're still choosing a method rather than fixing one that broke, start from the [authentication guides](/learn/mcp/authentication).

## Errors

### [[mcp-sdk] excluding tool '<name>' from tools/list: invalid x-mcp-header declaration](/learn/mcp/errors/excluded-tool-invalid-x-mcp-header)

One parameter in that tool's `inputSchema` carries an `x-mcp-header` annotation that breaks a 2026-07-28 constraint, so a conforming Streamable HTTP client drops the whole tool from `tools/list` and logs a warning instead of raising an error.

- Question: Which side of the tool list can you change?
- Documented platforms: MCP TypeScript SDK, MCP Python SDK, A server you don't control
- Other strings clients print:
  - `[mcp-sdk] excluding tool '<name>' from tools/list: invalid x-mcp-header declaration — <reason>`
  - `[mcp-sdk] tool '<name>' carries an invalid x-mcp-header declaration and will be excluded by conforming Streamable HTTP clients: <reason>`
  - `dropping tool '<name>': invalid x-mcp-header (<reason>)`
  - `<path>: x-mcp-header is only permitted on primitive-typed properties (string, integer, boolean); got <type>`
  - `<path>: x-mcp-header is only permitted on properties statically reachable via a chain of 'properties' keys (not under items, additionalProperties, oneOf/anyOf/allOf/not, if/then/else, or $ref)`

### [Authorization with the MCP server failed](/learn/mcp/errors/oauth-completes-but-no-token-sent)

The client says it is connected, but no usable credential reaches your server: either it doesn't attach the token, or the token carries an audience your server is right to reject.

- Question: Where is the token being lost?
- Documented platforms: Claude custom connectors, ChatGPT connectors, Microsoft Entra ID, VS Code, Cursor, MCP SDKs (server side)
- Other strings clients print:
  - `Authorization with the MCP server failed. You can check your credentials and permissions. If this persists, share this reference with support: "ofid_..."`
  - `UnauthorizedError: Unauthorized`
  - `{"error":"invalid_token","error_description":"Authentication required"}`
  - `Missing Authorization header`
  - `AADSTS9010010`
  - `invalid_target`

### [Couldn't reach the MCP server](/learn/mcp/errors/mcp-server-works-in-claude-code-but-not-claude-ai)

One toast covers four different failures: a claude.ai connector reaches your server from Anthropic's infrastructure over the public internet rather than from your machine, so the request dies at whichever hop exists only on that path — DNS, your edge, a redirect, or OAuth discovery.

- Question: Where does the request die?
- Documented platforms: Claude custom connectors, Kubernetes, Cloudflare Access, AWS Load Balancer, Vercel, Microsoft Entra ID, Zuplo MCP Gateway
- Other strings clients print:
  - `Authorization with the MCP server failed`
  - `Works in Claude Code or curl but not claude.ai`
  - `works in MCP Inspector or Claude Code CLI but not claude.ai`
  - `Custom connector "Couldn't reach the MCP server" — zero inbound traffic at edge, server verified reachable`
  - `AADSTS9010010 (sometimes surfaced as invalid_target)`

### [Dynamic Client Registration not supported](/learn/mcp/errors/dynamic-client-registration-not-supported)

The MCP client reached your authorization server's metadata and found no way to obtain a client ID — no registration endpoint, no Client ID Metadata Document support, and none configured in the client — so it stopped before the OAuth flow began.

- Question: Which authorization server issues your tokens?
- Documented platforms: Microsoft Entra ID, Okta, Auth0, Keycloak, Amazon Cognito, Zuplo MCP Gateway
- Other strings clients print:
  - `Incompatible auth server: does not support dynamic client registration`
  - `The authorization server '<url>' does not support automatic client registration. Do you want to proceed by manually providing a client registration (client ID)?`
  - `Automatic client registration isn't supported by <connector>. Edit the connector and add an OAuth Client ID.`
  - `Couldn't register with <connector>'s sign-in service. You can try again, or add an OAuth Client ID in the connector settings.`
  - `Dynamic client registration failed: HTTP 422`
  - `{"error":"invalid_client_metadata","error_description":"Dynamic registration is not available for this client."}`

### [Failed to fetch authorization server metadata from all attempted URLs](/learn/mcp/errors/failed-to-fetch-authorization-server-metadata)

The client knows which authorization server to use, but none of the well-known URLs it probes returned a metadata document, so it never learns where `/authorize` and `/token` are and the flow stops short of a login.

- Question: Which side of the discovery are you fixing?
- Documented platforms: VS Code, MCP TypeScript SDK, MCP Python SDK, FastMCP, Keycloak, Zuplo MCP Gateway
- Other strings clients print:
  - `Error populating auth server metadata for <issuer>: AggregateError: Failed to fetch authorization server metadata from all attempted URLs`
  - `Failed to fetch authorization server metadata from <url>: <status> <body>`
  - `Failed to authenticate with MCP server '<name>': Failed to fetch authorization server metadata for client registration (attempted issuers: <urls>)`
  - `HTTP <status> trying to load OpenID provider metadata from <url>`
  - `failed to fetch authorization server metadata: failed to fetch metadata from any authorization server`

### [MCP headers config ignored when server has OAuth discovery](/learn/mcp/errors/configured-headers-ignored-when-oauth-discovery-present)

Your credential never reaches the wire: the client found OAuth discovery metadata on the server first and started the OAuth flow instead of sending the header you configured.

- Question: Where are you fixing this?
- Documented platforms: Cursor, VS Code, Claude Code, Claude custom connectors, MCP Python SDK, MCP TypeScript SDK
- Other strings clients print:
  - `[Bug] MCP Server Authorization Header Not Recognized, Falls Back to OAuth`
  - `it refuses to obey an Authorization header now and tries to use oauth`
  - `.mcp.json ignores headers field for HTTP MCP servers`
  - `MCP server with basic auth headers works in user mcp.json but triggers OAuth flow when configured via extension .mcp.json`
  - `Error: HTTP 403: Invalid OAuth error response: SyntaxError: JSON Parse error: Unrecognized token '<'.`

### [mcp_authentication_failed_error](/learn/mcp/errors/mcp-authentication-failed-error-managed-agents)

A managed agent's connection to your MCP server failed on authentication: the server rejected the credential from the attached vault, required authentication when no matching credential was configured, or an `mcp_oauth` token refresh failed.

- Question: Which credential path is this server on?
- Documented platforms: Managed Agents vault, mcp_oauth credential, static_bearer credential, Anthropic MCP tunnel, Zuplo MCP Gateway
- Other strings clients print:
  - `Authentication with the MCP server failed: the server rejected the credential from the attached vault, required authentication when no matching credential was configured, or an OAuth token refresh failed.`
  - `vault_credential.refresh_failed`
  - `{"error":"invalid_token"}`

### [ModuleNotFoundError: No module named 'mcp.server.fastmcp'](/learn/mcp/errors/no-module-named-mcp-server-fastmcp)

Your server code imports `mcp.server.fastmcp`, but the installed `mcp` package is 2.x, where that module no longer exists — so the process dies at import, before it speaks any MCP.

- Question: Are you pinning or migrating?
- Documented platforms: Pin to mcp 1.x, MCP Python SDK (migrate to 2.x), FastMCP (the standalone package)
- Other strings clients print:
  - `MCP error -32000: Connection closed`
  - `Failed to reconnect to plugin:<plugin>:<server>: -32000`
  - `AttributeError: 'Server' object has no attribute 'list_tools'`

### [resource indicator is missing, or unknown](/learn/mcp/errors/resource-indicator-missing-or-unknown)

Your authorization server refused to bind a token to your MCP server — the `resource` value it was handed names something it does not recognize, or the client sent none and this server requires one — so no token is minted and nothing ever reaches your MCP server.

- Question: Which component decides the resource value?
- Documented platforms: Microsoft Entra ID, Auth0, Keycloak, MCP TypeScript SDK (client), MCP Python SDK (client), Claude Code, Zuplo MCP Gateway
- Other strings clients print:
  - `Authorization error: InvalidTargetError: resource indicator is missing, or unknown`
  - `AADSTS9010010: The resource parameter provided in the request doesn't match with the requested scopes.`
  - `AADSTS901002: The 'resource' request parameter is not supported.`
  - `{"error":"invalid_target","error_description":"apps scopes require a valid MCP resource"}`
  - `Error getting token from server metadata: ServerError: invalid_target`
  - `Missing or invalid grant_type, code, redirect_uri, client_id, PKCE (code_verifier), or resource required`

### [Resource server does not implement OAuth 2.0 Protected Resource Metadata.](/learn/mcp/errors/401-without-www-authenticate)

Your server answers `401` correctly, but the response carries no pointer to protected resource metadata, so the client cannot discover the authorization server and the OAuth flow never starts.

- Question: Where is the 401 coming from?
- Documented platforms: MCP Python SDK, MCP TypeScript SDK, FastMCP, AWS API Gateway (REST), ingress-nginx, Azure Container Apps
- Other strings clients print:
  - `Could not fetch resource metadata`
  - `No authorization_servers found in resource metadata <url> - Is this resource metadata configured correctly?`
  - `Protected resource <advertised> does not match expected <dialed>`
  - `Failed to start OAuth flow for <server>: SDK auth failed: Protected resource <advertised> does not match expected <dialed> (or origin)`

### [The request signature we calculated does not match the signature you provided](/learn/mcp/errors/aws-signaturedoesnotmatch)

AWS recomputed the signature over the request it actually received, got a different value from the one you sent, and answered `403` before your MCP server ran — so nothing about your tools, your handler, or your IAM policy is implicated yet.

- Question: Where is the signature going wrong?
- Documented platforms: MCP Python SDK (botocore signer), MCP TypeScript SDK (SigV4 transport), Claude Code, AWS API Gateway (IAM auth), A load balancer or proxy in the path
- Other strings clients print:
  - `SignatureDoesNotMatch`
  - `Credential should be scoped to correct service: '<service>'`
  - `Credential should be scoped to a valid Region, not <region-code>`
  - `Signature expired: <date> is now earlier than <date>`
  - `Signature not yet current: <date> is still later than <date>`
  - `Date in Credential scope does not match YYYYMMDD from ISO-8601 version of date from HTTP`
  - `The signature contains an invalid key=value pair (missing equal-sign) in Authorization header`

### [Token audience validation failed](/learn/mcp/errors/token-audience-validation-failed)

The token is real — right issuer, good signature, not expired — but the `aud` claim names something other than this MCP server, so the server is required to reject it.

- Question: Which side decides the audience?
- Documented platforms: Microsoft Entra ID, Auth0, Keycloak, Amazon Cognito, FastMCP, Zuplo MCP Gateway
- Other strings clients print:
  - `invalid audience`
  - `Token audience validation failed - no matching audiences`
  - `Token resource validation failed. Expected: <resource>`
  - `The aud claim is not valid`

### [Your MCP server returns a login page or 403 instead of 401](/learn/mcp/errors/302-redirect-instead-of-401)

A gate in front of your MCP server is enforcing login built for humans in browsers, so an unauthenticated client gets a login page, a redirect, or a bare `403` instead of the `401` that would tell it where to authenticate.

- Question: What is in front of your server?
- Documented platforms: Vercel, Azure App Service, AWS Load Balancer, oauth2-proxy, Netlify
- Other strings clients print:
  - `MCP client gets HTML instead of JSON`
  - `Unexpected token '<', "<!DOCTYPE "... is not valid JSON`
  - `MCP server connection failed, received 403 Forbidden`

## Prevent: set up authentication correctly

- [Anthropic-hosted agents](/learn/mcp/authentication/anthropic-managed-agents) — How an Anthropic-managed agent authenticates to your MCP server. Reaching your MCP server from an agent that runs on Anthropic's infrastructure.
- [API key](/learn/mcp/authentication/api-key) — API key authentication for MCP servers. Service-to-service calls where you control both the agent and the MCP server.
- [AWS IAM (SigV4)](/learn/mcp/authentication/aws-iam-sigv4) — Authenticate an MCP server with AWS IAM (SigV4). Agents you write that run in AWS, calling a server behind Lambda, API Gateway, or AgentCore.
- [All authentication methods](/learn/mcp/authentication)

## Stop debugging auth on every MCP server

A gateway in front of your MCP servers handles discovery, audience binding, and token validation once — for every server and every client.

## Next steps

- [Start for Free](https://portal.zuplo.com/signup)
- [Read the Docs](https://zuplo.com/docs/mcp-gateway/code-config/overview)
- [Ask us about it](/support)
- [Back to Learn MCP](/learn/mcp)