---
title: "MCP error reference"
description:
  "Errors MCP clients report: what each string means, why it happens, and the fix, per platform. Search a distinctive fragment of what your client printed."
canonicalUrl: "https://zuplo.com/learn/mcp/errors"
sourceUrl: "https://zuplo.com/learn/mcp/errors"
pageType: "other"
generatedAt: "2026-11-20"
---

# 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.

### [[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.

- Page asks: Which side of the tool list can you change?
- Documented platforms: MCP TypeScript SDK, MCP Python SDK, A server you don't control

### [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.

- Page asks: Where is the token being lost?
- Documented platforms: Claude custom connectors, ChatGPT connectors, Microsoft Entra ID, VS Code, Cursor, MCP SDKs (server side)

### [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.

- Page asks: Where does the request die?
- Documented platforms: Claude custom connectors, Kubernetes, Cloudflare Access, AWS Load Balancer, Vercel, Microsoft Entra ID, Zuplo MCP Gateway

### [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.

- Page asks: Which authorization server issues your tokens?
- Documented platforms: Microsoft Entra ID, Okta, Auth0, Keycloak, Amazon Cognito, Zuplo MCP Gateway

### [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.

- Page asks: Which side of the discovery are you fixing?
- Documented platforms: VS Code, MCP TypeScript SDK, MCP Python SDK, FastMCP, Keycloak, Zuplo MCP Gateway

### [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.

- Page asks: Where are you fixing this?
- Documented platforms: Cursor, VS Code, Claude Code, Claude custom connectors, MCP Python SDK, MCP TypeScript SDK

### [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.

- Page asks: Which credential path is this server on?
- Documented platforms: Managed Agents vault, mcp_oauth credential, static_bearer credential, Anthropic MCP tunnel, Zuplo MCP Gateway

### [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.

- Page asks: Are you pinning or migrating?
- Documented platforms: Pin to mcp 1.x, MCP Python SDK (migrate to 2.x), FastMCP (the standalone package)

### [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.

- Page asks: 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

### [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.

- Page asks: Where is the 401 coming from?
- Documented platforms: MCP Python SDK, MCP TypeScript SDK, FastMCP, AWS API Gateway (REST), ingress-nginx, Azure Container Apps

### [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.

- Page asks: 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

### [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.

- Page asks: Which side decides the audience?
- Documented platforms: Microsoft Entra ID, Auth0, Keycloak, Amazon Cognito, FastMCP, Zuplo MCP Gateway

### [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.

- Page asks: What is in front of your server?
- Documented platforms: Vercel, Azure App Service, AWS Load Balancer, oauth2-proxy, Netlify

Search shows this when nothing matches: "No documented error matches that text." 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 guides instead.

- [Authentication methods](/learn/mcp/authentication)
- [Ask us about it](/support)

## Set up authentication correctly

- [How an Anthropic-managed agent authenticates to your MCP server](/learn/mcp/authentication/anthropic-managed-agents) — Reaching your MCP server from an agent that runs on Anthropic's infrastructure
- [API key authentication for MCP servers](/learn/mcp/authentication/api-key) — Service-to-service calls where you control both the agent and the MCP server
- [Authenticate an MCP server with AWS IAM (SigV4)](/learn/mcp/authentication/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

- [Book a meeting with our team](/meeting)
- [Read the Docs](https://zuplo.com/docs/mcp-gateway/code-config/overview)
- [Back to Learn MCP](/learn/mcp)
