MCP fixes and known issues in Claude
If you are running into MCP problems with Claude, this page documents the known issues and the releases that fixed them.
Known issues
Tool names exceeding 64 characters break the Claude session, from 2026-07-28. Claude enforces a 64-character limit on tool names, which does not comply with the 128-character maximum the MCP specification defines. When any connected MCP server exposes a tool whose name exceeds 64 characters, Claude rejects the server connection and the entire Claude environment stops working. Servers with tools generated from an API schema using qualified namespaces are most likely to be affected.
Use tool name customization to alias affected names to 64 characters or fewer.
Aggregate tool list capped at 256 across connectors, from 2026-07-08. On claude.ai and Claude Desktop, custom remote MCP connectors intermittently lose their tools or collapse to exactly 256 tools total across all connected connectors, keeping the alphabetically-first 256 and truncating the namespace that straddles the boundary. With two connectors configured, refreshing one evicts the other's tools. "Refresh Tools" restores the full set for minutes to hours before it collapses again. A second failure mode drops a connector's tools entirely even when its catalog is well under 256. It reproduces on web and desktop, and on both organization and personal accounts. Tracked in anthropics/claude-code#77704, opened 2026-07-15.
Split a large catalog across several connectors so that neither one connector nor the combined set approaches the ceiling.
OAuth discovery and callback handling
2.1.85 introduced RFC 9728 Protected Resource Metadata discovery, and 2.1.81 introduced Client ID Metadata Document identity for servers without dynamic client registration. MintMCP publishes static client credentials alongside supporting dynamic client registration, so earlier builds can still authenticate.
| Release | Change |
|---|---|
| 2.1.191 2026-06-24 | Discovery and token requests retry once after transient network errors, and headless environments skip the browser popup for the paste-the-URL prompt |
| 2.1.186 2026-06-22 | Added claude mcp login <name> and claude mcp logout <name>, with --no-browser stdin redirect for completing over SSH |
| 2.1.121 2026-04-27 | SDK mcp_authenticate accepts redirectUri for custom-scheme completion, and Microsoft 365 OAuth no longer fails on a duplicate or unsupported prompt parameter |
| 2.1.119 2026-04-23 | Fixed "Invalid OAuth error response" when servers return non-JSON bodies for discovery, and a --client-secret not being sent during token exchange for servers requiring client_secret_post |
| 2.1.98 2026-04-09 | Fixed oauth.authServerMetadataUrl not being honored on token refresh after restart, which broke ADFS and similar IdPs (also 2.1.97) |
Earlier OAuth discovery fixes (June 2025 to March 2026)
| Release | Change |
|---|---|
| 2.1.85 2026-03-26 | MCP OAuth follows RFC 9728 Protected Resource Metadata discovery to find the authorization server |
| 2.1.81 2026-03-20 | Added Client ID Metadata Document (CIMD / SEP-991) support for servers without dynamic client registration |
| 2.1.74 2026-03-11 | Fixed authentication hanging when the callback port is already in use |
| 2.1.69 2026-03-04 | Added the oauth.authServerMetadataUrl per-server config option for when standard discovery fails |
| 2.1.63 2026-02-28 | Added manual URL paste fallback when the automatic localhost redirect doesn't work |
| 2.1.30 2026-02-03 | Added pre-configured OAuth client credentials via --client-id and --client-secret on claude mcp add |
| 1.0.35 2025-06-25 | Added MCP OAuth authorization server discovery |
| 1.0.27 2025-06-17 | Remote MCP servers (SSE and HTTP) support OAuth |
Token lifecycle and credential storage
If users re-authenticate daily, or get asked to run /login with no credential failure on your side, check the Claude Code version first. Concurrent refreshes and macOS keychain writes raced each other on older builds.
2.1.136 fixed refresh tokens being lost when several servers refresh at once. Require it if your server rotates refresh tokens on every use, since earlier builds can drop a rotated token mid-write and push the user back through the browser flow.
| Release | Change |
|---|---|
| 2.1.216 2026-07-20 | Fixed re-authenticate revoking working credentials before the new sign-in succeeds |
| 2.1.206 2026-07-09 | Fixed OAuth servers requiring manual re-authentication after a single failed token refresh |
| 2.1.193 2026-06-25 | headersHelper re-runs and reconnects automatically when a tool call returns 401 or 403 |
| 2.1.136 2026-05-08 | Fixed refresh tokens being lost when multiple servers refresh concurrently, which had left users with several remote servers re-authenticating daily |
| 2.1.119 2026-04-23 | Fixed ${ENV_VAR} placeholders in headers not being substituted before requests |
Earlier token lifecycle fixes (September 2025 to April 2026)
| Release | Change |
|---|---|
| 2.1.118 2026-04-22 | Fixed a macOS keychain race where a concurrent refresh could overwrite a freshly-refreshed token |
| 2.1.118 2026-04-22 | Fixed refresh proceeding without its cross-process lock under contention |
| 2.1.118 2026-04-22 | Fixed servers whose token response omits expires_in requiring re-authentication every hour |
| 2.1.118 2026-04-22 | Fixed refresh failing when the server revokes a token before its local expiry time |
| 2.1.118 2026-04-22 | Fixed HTTP/SSE servers with custom headers stuck in "needs authentication" after a transient 401 |
| 2.1.118 2026-04-22 | Fixed an unhandled promise rejection when the OAuth flow times out or is cancelled |
| 2.1.101 2026-04-10 | /mcp offers Reconnect instead of OAuth actions for headersHelper servers, so the helper script re-runs |
| 2.1.74 2026-03-11 | Fixed refresh never prompting for re-auth after the refresh token expires, for servers that return errors with HTTP 200 (for example Slack) |
| 2.1.69 2026-03-04 | Fixed macOS keychain corruption with multiple OAuth servers: large metadata blobs overflowed the security -i stdin buffer, leaving stale credentials and repeated /login prompts |
| 2.1.63 2026-02-28 | Fixed a listener leak in OAuth flow cleanup |
| 2.1.59 2026-02-25 | Fixed a refresh race when multiple Claude Code instances run simultaneously |
| 2.1.49 2026-02-19 | Added step-up auth support and discovery caching |
| 2.1.0 2026-01-07 | Fixed refresh not triggering when the server reports the token expired but the local expiry check disagrees |
| 2.0.34 2025-11-05 | Fixed an infinite token refresh loop that caused OAuth servers (for example Slack) to hang during connection |
| 1.0.110 2025-09-09 | OAuth tokens proactively refresh before expiration |
Scope, resource, and audience binding
A wrong scope set fails at the authorize step, before the user reaches a consent screen. Publish a minimal default scope set rather than relying on the client to pick from scopes_supported, and return 403 insufficient_scope naming the specific scope you need so step-up works.
Keep one canonical URL for your MCP endpoint and use it identically in the MCP URL, the protected resource metadata resource field, the authorize request, and the token audience. Clients compare these by exact string.
| Release | Change |
|---|---|
| 2.1.196 2026-06-29 | Fixed MCP OAuth requesting the authorization server's full scopes_supported catalog when no scope is specified, which caused invalid_scope failures on GitLab self-hosted and other enterprise IdPs |
| 2.1.129 2026-05-05 | Fixed managed settings policy not applying for enterprise and team users whose stored credentials lacked the user:inference scope |
| 2.1.118 2026-04-22 | Fixed step-up authorization silently refreshing instead of prompting for re-consent when a 403 insufficient_scope names a scope the current token already has |
| 2.1.85 2026-03-26 | Fixed step-up authorization failing when a refresh token exists, so servers requesting elevated scopes via 403 insufficient_scope correctly trigger re-authorization |
Transport and connection reliability
Claude Code speaks stdio, HTTP, SSE, and WebSocket. 2.1.141 kept tool calls flowing over POST when the optional server-to-client event stream fails to reconnect, so do not let a successful call depend on that stream.
2.1.133 extended proxy and mTLS handling to the whole OAuth flow, including discovery, dynamic client registration, token exchange, and refresh. 2.1.206 made a per-server request_timeout_ms take effect in a fresh session, which matters if your tools run long.
| Release | Change |
|---|---|
| 2.1.217 2026-07-21 | Fixed corporate mTLS, TLS-verify, OAuth scope, and proxy settings being ignored in Claude Desktop sessions |
| 2.1.212 2026-07-16 | Tool calls running longer than 2 minutes move to the background automatically, configurable with CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS |
| 2.1.211 2026-07-15 | Fixed plugin servers not reconnecting after an idle web session woke, leaving calls failing until the next message |
| 2.1.206 2026-07-09 | Fixed servers configured via --mcp-config or .mcp.json ignoring a per-server request_timeout_ms |
| 2.1.199 2026-07-02 | Fixed SSL certificate errors burning retries before showing actionable guidance |
| 2.1.187 2026-06-23 | Remote tool calls that hang with no response for 5 minutes abort with an error instead of blocking indefinitely, overridable with CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT |
Earlier transport and network fixes (March 2026 to June 2026)
| Release | Change |
|---|---|
| 2.1.162 2026-06-03 | Fixed per-server timeout values below 1000 ms being floored to a 1-second watchdog that aborted every call |
| 2.1.153 2026-05-27 | Fixed stateful servers without the optional GET SSE stream reconnect-looping on tools/list (regression in 2.1.147) |
| 2.1.152 2026-05-26 | Fixed remote servers failing to connect in Claude Code Remote sessions when the egress proxy is enabled |
| 2.1.142 2026-05-14 | Fixed MCP_TOOL_TIMEOUT not raising the per-request fetch timeout for remote HTTP and SSE servers, which capped calls at 60 seconds |
| 2.1.141 2026-05-13 | Fixed HTTP/SSE servers returning 403 on connect showing as "failed" instead of "needs auth", and remote servers disconnecting when the optional server-events stream failed to reconnect; tool calls continue over POST |
| 2.1.139 2026-05-11 | Reconnect retry on transient failures enabled for all users, /mcp Reconnect picks up .mcp.json edits without a restart, and response bodies are capped at 16 MB per SSE frame |
| 2.1.133 2026-05-07 | Fixed HTTP(S)_PROXY, NO_PROXY, and mTLS not being respected for the full OAuth flow including discovery, dynamic client registration, token exchange, and refresh |
| 2.1.121 2026-04-27 | Servers that hit a transient error during startup auto-retry up to 3 times instead of staying disconnected |
| 2.1.110 2026-04-15 | Fixed tool calls hanging indefinitely when the connection drops mid-response on SSE or HTTP transports |
| 2.1.97 2026-04-08 | Fixed HTTP/SSE connections accumulating around 50 MB per hour of unreleased buffers when servers reconnect |
| 2.1.83 2026-03-24 | Fixed tool calls hanging indefinitely when an SSE connection drops mid-call and exhausts its reconnection attempts |
| 2.1.73 2026-03-11 | Added actionable guidance when OAuth login or connectivity checks fail due to SSL certificate errors from corporate proxies or NODE_EXTRA_CA_CERTS |
Tool discovery and tool catalogs
2.1.144 introduced full pagination for tools/list, and 2.1.147 extended it to resources, templates, and prompts. Earlier builds return only the first page and drop the rest with no error.
2.1.7 turned on deferred tool definitions by default once they exceed 10% of the context window, so "connected" does not mean every tool is in context. Keep tool names short and ASCII, keep descriptions under the 2 KB cap, and keep ordering and pagination cursors deterministic.
| Release | Change |
|---|---|
| 2.1.219 2026-07-24 | Added HTTP status and error text to claude mcp list and /mcp when a server fails to connect |
| 2.1.203 2026-07-07 | Added the session's additional working directories to roots/list, with notifications/roots/list_changed when the set changes |
| 2.1.191 2026-06-24 | Capability discovery (tools/list, prompts/list, resources/list) retries transient network errors with short backoff |
| 2.1.181 2026-06-17 | Fixed claude mcp get and list showing "Connected" when tools/list fails; they now show "Connected, tools fetch failed" with the error |
| 2.1.162 2026-06-03 | Fixed API 400 no low surrogate in string errors for server descriptions containing emoji near a truncation boundary |
Earlier tool discovery fixes (January 2026 to May 2026)
| Release | Change |
|---|---|
| 2.1.154 2026-05-28 | Fixed /mcp rendering when servers have long or multi-line tool names or long descriptions |
| 2.1.147 2026-05-21 | Fixed pagination dropping resources, templates, and prompts past page 1 |
| 2.1.144 2026-05-18 | Fixed servers with paginated tools/list responses only returning the first page, silently dropping tools |
| 2.1.132 2026-05-06 | Fixed servers that connect but fail tools/list silently showing 0 tools; they now retry once and show "connected, tools fetch failed" |
| 2.1.128 2026-05-04 | /mcp shows the tool count for connected servers and flags servers that connected with 0 tools |
| 2.1.122 2026-04-28 | Fixed tool search missing tools from servers that connected after session start in nonblocking mode |
| 2.1.84 2026-03-25 | Tool descriptions and server instructions capped at 2 KB, to stop OpenAPI-generated servers from bloating context |
| 2.1.9 2026-01-15 | Added auto:N syntax to configure the tool search auto-enable threshold as a context window percentage |
| 2.1.7 2026-01-13 | MCP tool search auto mode on by default: when tool descriptions exceed 10% of the context window, definitions are deferred and discovered through a search tool |
| 2.1.0 2026-01-07 | Added support for list_changed notifications, so servers can update tools, prompts, and resources without a reconnect |
Approvals, policy, and governance
2.1.169 closed several bypasses in managed allow and deny lists, including on reconnect, on IDE-typed configs, and through --mcp-config.
| Release | Change |
|---|---|
| 2.1.219 2026-07-24 | Managed allowlist and denylist ${VAR} entries resolve from the startup environment and managed-settings env |
| 2.1.196 2026-06-29 | claude mcp list and get no longer spawn .mcp.json servers that a repo self-approved via a committed .claude/settings.json |
| 2.1.178 2026-06-15 | Fixed server-level specs (mcp__server, mcp__server__*, mcp__*) in subagent disallowedTools being silently ignored |
| 2.1.169 2026-06-08 | Fixed managed policies not being enforced on reconnect, on IDE-typed configs, on --mcp-config servers during the first session after install, or before remote settings loaded |
| 2.1.153 2026-05-27 | Fixed subagent frontmatter servers ignoring --strict-mcp-config, enterprise managed config, and managed-settings allow and deny policies |
Earlier policy fixes (October 2025 to May 2026)
| Release | Change |
|---|---|
| 2.1.149 2026-05-22 | Added the allowAllClaudeAiMcps managed setting to load claude.ai cloud connectors alongside managed-mcp.json |
| 2.1.85 2026-03-26 | Fixed deniedMcpServers not blocking claude.ai MCP servers |
| 2.1.83 2026-03-24 | Fixed --mcp-config bypassing allowedMcpServers and deniedMcpServers managed policy |
| 2.1.78 2026-03-17 | Fixed deny: ["mcp__servername"] rules not removing that server's tools before sending them to the model, so the model could see and attempt blocked tools |
| 2.1.69 2026-03-04 | Fixed the trust dialog silently enabling all .mcp.json servers on first run |
| 2.0.70 2025-12-15 | Added mcp__server__* wildcard syntax for MCP tool permissions |
| 2.0.22 2025-10-17 | Added support for enterprise managed MCP allowlist and denylist |
Protocol features
| Release | Change |
|---|---|
| 2.1.191 2026-06-24 | HTTP 404 error messages show the URL and point to your MCP config |
| 2.1.144 2026-05-18 | Fixed images with unsupported MIME types (for example SVG) breaking the conversation; they are saved to disk and referenced in the result |
| 2.1.128 2026-05-04 | Fixed tool results dropping images when the server returns both structured content and content blocks |
| 2.1.117 2026-04-21 | Fixed elicitation/create requests auto-cancelling in print and SDK mode when the server finishes connecting mid-turn |
| 2.1.91 2026-04-02 | Added the _meta["anthropic/maxResultSizeChars"] annotation to raise the result persistence limit up to 500 K |
Earlier protocol feature support (October 2025 to March 2026)
| Release | Change |
|---|---|
| 2.1.89 2026-03-31 | Fixed tool errors truncating to only the first content block when the server returns multi-element error content |
| 2.1.76 2026-03-14 | Added elicitation support, so servers can request structured input mid-task through an interactive dialog |
| 2.1.69 2026-03-04 | Binary content handling: PDFs, Office documents, and audio are saved to disk with the correct extension instead of dumped as base64 into context |
| 2.0.50 2025-11-21 | Fixed calling tools that have nested references in their input schemas |
| 2.0.21 2025-10-16 | Added support for the structuredContent field in tool responses |