--- title: "MCP Error Reference" description: "Errors MCP clients report when authentication fails: what each string means, why it happens, and the fix. Search by the text your client printed." canonicalUrl: "https://zuplo.com/learn/mcp/errors" sourceUrl: "https://zuplo.com/learn/mcp/errors" pageType: "other" generatedAt: "2026-07-30" inputsHash: "0d68e19923a85420" --- # MCP Error Reference > Look up the error your client printed, and fix it. This is a searchable > library of the strings MCP clients (Claude, Cursor, VS Code, ChatGPT > connectors, and others) print when authentication to an MCP server fails — > what each one means, how to confirm it's your problem, and the > platform-specific fix. 11 documented errors as of this writing. Each entry links to a full page with a confirmation check, per-platform fix steps, and a diagram of why the failure happens. ## Errors - **[`Authorization with the MCP server failed`](/learn/mcp/errors/oauth-completes-but-no-token-sent)** — A token was issued and the client says it's connected, but the credential never reaches your server intact: either the client doesn't attach it, or it carries an audience your server is right to reject. Documented for: Claude custom connectors, ChatGPT connectors, Microsoft Entra ID, VS Code, Cursor, MCP Python SDK. - **[`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. Claude Code and `curl` reach your server from your machine; a claude.ai connector reaches it from Anthropic's infrastructure over the public internet, so the request dies at whichever hop only exists on that path — DNS, your edge, a redirect, or OAuth discovery. Documented for: 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. Documented for: 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 it's supposed to use, but none of the well-known URLs it's required to try returned a metadata document — so it never learns where `/authorize` and `/token` are, and the flow stops one step short of a login. Documented for: 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)** — The credential is sitting in your client config and never reaches the wire: the client found OAuth discovery metadata on your server first, and switched to the OAuth flow instead of sending the header you set. Documented for: 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. Documented for: Claude managed agents, MCP OAuth credential paths, static bearer credentials, Anthropic MCP tunnels, Zuplo MCP Gateway. - **[`resource indicator is missing, or unknown`](/learn/mcp/errors/resource-indicator-missing-or-unknown)** — The client reached your authorization server and asked for a token bound to your MCP server, and the authorization server refused the binding: the `resource` value it was handed names something it doesn't recognise, or the client sent no `resource` at all and this server requires one. Documented for: Microsoft Entra ID, Auth0, Keycloak, MCP TypeScript SDK, MCP Python SDK, 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 has nothing to discover the authorization server with, and the OAuth flow never starts. Documented for: MCP Python SDK, MCP TypeScript SDK, FastMCP, AWS API Gateway, 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. Documented for: MCP Python SDK, MCP TypeScript SDK, Claude Code, AWS API Gateway, AWS Load Balancer. - **[`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, and does. Documented for: 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)** — Something in front of your MCP server is enforcing authentication built for humans in browsers. Instead of the 401 an MCP client needs, it returns a login page, a redirect to one, or a bare 403 — so the client never learns how to authenticate. Documented for: Vercel, Azure App Service, AWS Load Balancer, oauth2-proxy, Netlify. If your client's exact wording isn't above, it's likely one of the aliases each detail page lists — clients rephrase the same underlying cause. Try a shorter fragment or a bare status code (e.g. `401`) when searching the live page. ## Set authentication up correctly Guides for preventing these errors in the first place, ranked by how many documented errors point back to them: - **[API Key Authentication for MCP Servers](/learn/mcp/authentication/api-key)** — Best for service-to-service calls where you control both the agent and the MCP server. - **[OAuth 2.1 Authentication for MCP Servers](/learn/mcp/authentication/oauth-2-1)** — Best for servers that must be reachable by MCP clients you don't control, or listed in a connector directory. - **[How an Anthropic-managed agent authenticates to your MCP server](/learn/mcp/authentication/anthropic-managed-agents)** — Best for reaching your MCP server from an agent that runs on Anthropic's infrastructure. See [all authentication methods](/learn/mcp/authentication). ## Next steps - Start a free account: https://portal.zuplo.com/signup - Read the docs: https://zuplo.com/docs/mcp-gateway/code-config/overview - A gateway in front of your MCP servers handles discovery, audience binding, and token validation once — for every server and every client — which is why several fixes above list "Zuplo MCP Gateway" as a platform-neutral option.