Claude Code MCP errors explained

Find your error

Search this page for a few words of the message you saw. Claude Code changes its wording between releases, so each section shows the current message and, where people still paste them, the older ones.

• MCP server failed to connect
• No MCP servers configured
• MCP config can't be read or saved, or the server will not start
• Connection timed out at startup
• MCP server disconnected mid-session
• MCP server needs you to sign in again
• The credential you configured was rejected
• Couldn't read the stored credentials for MCP server
• The sign-in can't start
• Refusing to send credentials to non-https token endpoint
• Issuer mismatch in authorization response
• The server connects but no tools appear
• MCP tool name over 128 characters
• Tool input schema is invalid
• No such tool available
• The connection closed before the tool call was answered
• MCP tool output is too large
• Blocked by managed policy, or a reserved name

How we tested these

Every message on this page was taken from Anthropic's own documentation on October 23, 2026, or captured from a run we made ourselves that same day, and each is quoted exactly as it appears. The pages used are listed at the end. Where a message can be raised without a model call, we raised it: on October 23, 2026 we ran Claude Code 2.1.309 on Linux x64 against a throwaway home directory and a throwaway project holding eight MCP servers broken on purpose. One command does not exist, one process exits as soon as it starts, one never answers, one answers the handshake and exposes no tools, one carries a URL with a stray leading space, one names an environment variable nobody set, one points at a port with nothing behind it, and one sits unapproved in the project's own .mcp.json. That run produced the captures below, and each opens with the command we ran.

Four of the eighteen sections carry a capture. The rest need a state a test machine cannot arrange, such as a subscription sign-in that has expired mid-session, an administrator's policy, a remote server that refuses a credential or drops mid-call, or a machine whose clock jumps during a connection attempt. Each of those sections says so in its own words and names the reason.

Three characters are left out of the captures and each place says so: Claude Code prints a check mark before Connected, a pause symbol before Pending approval, and a warning sign after MCP config diagnostics. Nothing is retyped from memory and no string is invented.

MCP server failed to connect

✘ Failed to connect

✘ Connection error

MCP endpoint not found at <origin>. Check the URL in your MCP config.

What it means. Claude Code could not start that server or reach its URL. It is the server's failure, not the list command's. claude mcp list prints the first line beside that server with the failure detail after it. The third line is what /mcp shows when an HTTP server answers 404, and it names the URL's origin without its path.

What causes it

• A command that is not on your PATH, or one you typed without the -- separator, so the server and its arguments were both read as part of the command.
• A server process that exits the moment it starts.
• A URL with the wrong host or path, or one that is not reachable from this machine.
• A rejected token, an unreachable proxy, or a DNS failure.

How to fix it

1. Run claude mcp get <name> and read its Issue: line. It carries the status or error code and any text the server sent back.
2. Read the same detail under claude mcp list, where it usually names the cause outright: ENOENT: Executable not found in $PATH: "<command>", CONNECTION_CLOSED: Connection closed, or ENOTFOUND: getaddrinfo ENOTFOUND <host>.
3. For an HTTP server, confirm the URL from the same machine: curl -I https://mcp.sentry.dev/mcp. In PowerShell use curl.exe. A 404 or 405 means the server is up, since many MCP endpoints answer POST only. A 401 or 403 means the server is up and you need to authenticate. No response at all means the URL or your network.
4. If /mcp names the origin in a 404, run claude mcp get <name> to see the full URL you configured, compare its path with the server's documented MCP endpoint path, then remove the server and add it again with the right URL.
5. Read the warnings under the list output. Claude Code flags configuration values carrying hidden leading or trailing whitespace, which is what a token pasted with a newline leaves behind, and names unset ${VAR} references.
6. Inside a session, open /mcp, select the server and choose Reconnect.

What not to do

Do not read the failure as the list command breaking: every other server on that list may be fine. Do not re-add the server or retype the token before you have read the Issue: line, because a missing binary and a rejected token need opposite fixes, and only that line tells you which you have.

Reproduced

One listing, every state a single broken server can be in. Eight servers, all broken or unapproved on purpose, and the block under the list is the warning report Claude Code appends when it finds faults in the configuration itself:

$ claude mcp list
Checking MCP server health…

demo-missing: definitely-not-a-real-binary-xyz  - ✘ Failed to connect — ENOENT: Executable not found in $PATH: "definitely-not-a-real-binary-xyz"
demo-quits: node /tmp/mcpdemo2/quits.mjs - ✘ Failed to connect — CONNECTION_CLOSED: Connection closed
demo-emptytools: node /tmp/mcpdemo2/emptytools.mjs - Connected
demo-hang: node /tmp/mcpdemo2/hang.mjs - ✘ Failed to connect — MCP server "demo-hang" connection timed out after 30000ms
demo-ws: http (HTTP) - ✘ Failed to connect — ENOTFOUND: getaddrinfo ENOTFOUND http
demo-missingvar: https://mcp.example.com/mcp (HTTP) - ✘ Failed to connect — ENOTFOUND: getaddrinfo ENOTFOUND mcp.example.com
demo-unreachable: http://127.0.0.1:8733/mcp (HTTP) - ✘ Failed to connect — ECONNREFUSED: ECONNREFUSED: Unable to connect. Is the computer able to access the url?
demo-pending: definitely-not-a-real-binary-xyz  - Pending approval (run `claude` to approve)

MCP config diagnostics

For help configuring MCP servers, see: https://code.claude.com/docs/en/mcp

[Contains warnings] User config (available in all your projects)
Location: /tmp/mcpdemo2/home/.claude.json
 ├ [Warning] [demo-ws] mcpServers.demo-ws: Leading or trailing whitespace in: url
 └ [Warning] [demo-missingvar] mcpServers.demo-missingvar: Missing environment variables: MCP_DEMO_UNSET_VAR

The check mark before Connected on the fourth line and the pause symbol before Pending approval on the last are left off, and one more: Claude Code prints a warning sign after MCP config diagnostics. The rest is as printed. Claude Code 2.1.309 on Linux x64, October 23, 2026.

Ask one failed server what went wrong and you get the detail step 1 sends you to:

$ claude mcp get demo-quits
demo-quits:
  Scope: User config (available in all your projects)
  Status: ✘ Failed to connect
  Issue: CONNECTION_CLOSED: Connection closed
  Type: stdio
  Command: node
  Args: /tmp/mcpdemo2/quits.mjs
  Environment:

To remove this server, run: claude mcp remove demo-quits -s user

A server that is merely unreachable answers with the transport's own words. Nothing is appended to a Connection error status on any version, but a Failed to connect status carries whatever the failure had to say, as here:

$ claude mcp get demo-unreachable
demo-unreachable:
  Scope: User config (available in all your projects)
  Status: ✘ Failed to connect
  Issue: ECONNREFUSED: ECONNREFUSED: Unable to connect. Is the computer able to access the url?
  Type: http
  URL: http://127.0.0.1:8733/mcp

To remove this server, run: claude mcp remove demo-unreachable -s user

Read the two warnings in that first capture against their own servers. demo-ws carries a URL with a leading space, which is why its host reads as http and resolves nowhere; Claude Code reports the whitespace without quoting the value. demo-missingvar references a variable nobody set, and Claude Code names the variable rather than its value. Both servers still load, and both then fail to connect. Sources: Anthropic's MCP server status and MCP quickstart troubleshooting.

No MCP servers configured

No MCP servers configured

What it means. This is the wording /mcp uses as a symptom heading when Claude Code found no servers for the directory you are in. That directory decides which servers exist, so a server added somewhere else is not missing, it belongs to another directory.

What causes it

• You ran claude mcp add from a different project. A local-scope server is tied to the project where you added it: the repository root, or the exact directory if you were not in a git repository.
• You edited a configuration file at a path Claude Code does not read. The paths it reads are ~/.claude.json and <project>/.mcp.json. It does not read ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json or %APPDATA%\Claude\mcp.json.
• A malformed entry in .mcp.json. Claude Code skips that entry and still loads the others, so the file looks active while one server is left out.

How to fix it

1. Run claude mcp list in the directory you are actually working in. If your server appears there, the configuration was never the problem.
2. For a server you want everywhere, add it at user scope: claude mcp add --scope user. That writes to the mcpServers key in ~/.claude.json and is not tied to a project.
3. For a server you want just here, edit .mcp.json at the project root, not in the .claude folder.
4. Look for the parse warning that names the offending field, and fix that entry.

What not to do

Do not conclude the server is broken. Nothing here has tried to start it. And do not hand-write a config at a path Claude Code does not read, because a file it never opens looks exactly like a server that fails.

Not reproduced

The message is Anthropic's own wording for this symptom in its quickstart rather than a line the CLI prints, so there is nothing to paste. The causes and steps rest on Anthropic's MCP quickstart, read on October 23, 2026.

MCP config can't be read or saved, or the server will not start

Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.

MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.

What it means. The first line comes from a command that reads the project's .mcp.json, such as claude mcp add or claude mcp remove with project scope. The file in your current directory is not a regular file, or it is larger than 2 MiB, so the command stopped rather than read it. The second line means a user-scope or local-scope change was written to ~/.claude.json and was not there when Claude Code read it back. After a remove, the same message reads was not removed from.

What causes it

• Something other than a file sits at .mcp.json: a symlink to a device, a named pipe, or a directory.
• A .mcp.json grown past 2 MiB, usually by a pasted blob.
• ~/.claude.json made read-only, or protected by a sandbox that refuses the write.
• A stdio server whose command was written without the -- separator or without an absolute path, so it starts from one directory and fails from another.

How to fix it

1. Check what sits at .mcp.json and replace it with an ordinary JSON file in the project-scope format, or delete it, then run the command again.
2. For a stdio server, run the configured command yourself in your terminal to see the server's own error. What comes back tells you where the problem is.
3. If the command starts and waits for input, the server itself works. Run claude mcp get <name> and compare the command shown there with what you typed. When they differ, you likely left out the -- separator, so remove the server and add it again with -- in place.
4. Make the file the message names writable, or run the command outside the sandbox, then run the same add or remove again.
5. Give local scripts in command or args as absolute paths, which is why a server can start from one directory and fail from another.

What not to do

Do not trust an Added ... line on an older build as proof the change landed. Before 2.1.283, claude mcp add, claude mcp add-json and claude mcp remove reported success even when the change never reached the file, which is the reason these messages exist.

Not reproduced

Both messages come from commands we would have to run against a protected or malformed file, and the setup we captured from was neither. They are quoted from Anthropic's error reference, read on October 23, 2026.

Connection timed out at startup

MCP server "<name>" connection timed out after <N>ms

MCP server "<name>" connection timed out. Your computer went to sleep or its clock changed while connecting.

What it means. The server took longer than the startup timeout to answer. The limit is 30 seconds, set by the MCP_TIMEOUT environment variable in milliseconds. The second line is what Claude Code prints when it also finds your system clock jumped forward during the attempt; it cannot tell a sleep from a forward clock change, so it names both.

What causes it

• A stdio server on its first run, while npx downloads the package.
• A server that is slow to answer its first request.
• A laptop that went to sleep during the attempt, or a clock that moved.

How to fix it

1. Raise the limit for the run: MCP_TIMEOUT=60000 claude. In PowerShell, set the variable before the command on the same line: $env:MCP_TIMEOUT = "60000"; claude.
2. Connect to the server again and keep the computer awake until the attempt finishes.
3. Inside a session, open /mcp, select the server and choose Reconnect. From your shell, run the command again.
4. If the server then fails with a message starting Skipping connection (recent failure cached, wait 15 minutes and run the command again, or edit the plugin's configuration to retry now.
5. Update Claude Code. Before 2.1.299, some connections to HTTP servers that were up timed out at startup whatever MCP_TIMEOUT said.

What not to do

Do not leave the default in place for a first npx run and conclude the server is broken. Equally, do not raise the timeout and leave it raised to live with a server that hangs: the message that says your computer slept is about the attempt, but a server that never answers at all needs fixing rather than a longer wait.

Reproduced

$ MCP_TIMEOUT=2000 claude mcp list
Checking MCP server health…

demo-hang: node /tmp/mcpdemo2/hang.mjs - ✘ Failed to connect — MCP server "demo-hang" connection timed out after 2000ms

The server in that line starts and never answers. Anthropic's page covers the sleep and clock-change form and records the after <N>ms wording as the one older versions printed. On 2.1.309 we still got the after <N>ms form for a server that never replied at all, because no clock had jumped: the sentence about sleeping and clock changes belongs to that case, not to every startup timeout. Claude Code 2.1.309 on Linux x64, October 23, 2026.

Not reproduced

The sleep and clock-change sentence needs a machine whose clock moves forward mid-attempt, which is not a state a test machine can be put into on request. Its wording is quoted from Anthropic's error reference, and the timeout setting from Anthropic's environment variables page, both read on October 23, 2026.

MCP server disconnected mid-session

MCP server "<name>" disconnected · open /mcp to reconnect

What it means. A remote server dropped while the session was running and the automatic reconnection gave up. Claude Code first tries five times with exponential backoff, starting at a one-second delay and doubling it each time, and /mcp shows the server as pending while those attempts run. After five failures it marks the server as failed and shows this notification.

What causes it

• A network drop between this machine and a remote server.
• The server restarting, or a proxy closing the connection.
• A server that needs authorizing again, in which case retries stop rather than continue.
• A WebSocket server that sent one message over 16 MiB, which makes Claude Code close the connection itself.

How to fix it

1. Inside a session, open /mcp, select the server and choose Reconnect.
2. To retry every server that failed or needs authentication at once, run /mcp reconnect all. In the interactive terminal this needs 2.1.284 or later; earlier versions answer MCP server "all" not found.
3. If the first failure was transient, such as a 5xx response, a refused connection or a timeout, Claude Code keeps retrying an HTTP or SSE server in the background for about half an hour, and the server's tools become available again when one attempt connects.
4. If the server needs a sign-in, retries stop. Sign in with claude mcp login <name> in your shell, then start the run again.

What not to do

Do not restart the session for every drop. The reconnect path does not need it. And do not assume you will see the retries: in a claude -p run and an Agent SDK session there is no /mcp panel, so a run carries on without that server's tools.

Not reproduced

Reaching this needs a live session whose remote server drops, and the notification is shown in the session rather than printed by a command. The wording and the retry count come from Anthropic's MCP page, read on October 23, 2026.

MCP server needs you to sign in again

MCP server "<name>" needs you to sign in again (run /mcp to re-authenticate)

MCP server "<name>" needs additional permissions (scope: "<scope>") — run /mcp to re-authenticate

MCP server "<name>" requires re-authorization (token expired)

What it means. A remote server rejected the credential on a tool call mid-session, usually because a sign-in or token expired, or because the token lacks a permission the tool needs. The tool call fails and /mcp marks the server as needing authentication. The third line is the older wording, which every one of these cases used before 2.1.273.

What causes it

• A sign-in or token that expired, or one revoked by an administrator.
• A token that lacks a permission a particular tool needs.
• A server asking for a scope your configuration pinned a different list for.

How to fix it

1. Run /mcp, select the server and sign in again from its menu. From your shell, claude mcp login <name> does the same thing.
2. If the message names a scope and you pinned oauth.scopes for that server, add the missing scope to that list before you authenticate again.
3. When the configuration sets neither oauth.scopes nor authServerMetadataUrl, Claude Code requests the scope the server named, so signing in again is usually all that is needed.
4. If the same server asks again on every launch, the sign-in is not persisting. Check the credential store problem in the next section along from this one.

What not to do

Do not sign in again and again when the message names a scope and you have pinned oauth.scopes. The same sign-in returns the same token and the same refusal, because the scope list is what decides the request. Change the list, then authenticate.

Not reproduced

Producing this needs a subscription or OAuth sign-in to expire or be revoked mid-session, which a test machine cannot arrange on request. The messages and the steps come from Anthropic's error reference, read on October 23, 2026, including the older form and its version note.

The credential you configured was rejected

MCP server "<name>" rejected the credential from its headersHelper (check the helper and run /mcp to reconnect, or to authenticate if the server also uses OAuth)

MCP server "<name>" rejected the Authorization header in its config (update it, then run /mcp to reconnect)

Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.

What it means. The server refused a credential your own configuration supplied, rather than one from a sign-in. The first two lines arrive on a tool call; the third is the connection-level report, which says the connection failed with an HTTP status such as 401 or 403.

What causes it

• A headersHelper script returning a credential the endpoint does not accept.
• An Authorization value in the server's configuration that was rotated, or pasted with a trailing newline.
• A helper that reads a variable Claude Code removes for a server from a project .mcp.json, a plugin or a project agent file.

How to fix it

1. Run the headersHelper command yourself, from the directory Claude Code runs it in and with the environment variables Claude Code sets for it, and confirm it prints an Authorization value the endpoint accepts.
2. Update the Authorization value under headers where the server is configured, then reconnect from /mcp.
3. Reconnect rather than re-authenticate. Claude Code re-runs the helper on each connection attempt, so a retry after a credential rotation race can succeed with a fresh credential.
4. Check the config warnings under claude mcp list for hidden whitespace in the headers values, which is a common cause of a rejected token.

What not to do

Do not go looking for an OAuth sign-in when the helper supplies the Authorization header. There is no OAuth fallback for that server, so the sign-in you are hunting for does not exist. Fix the helper or the header.

Not reproduced

Producing these needs a remote server that refuses a credential we control, and the messages are shown in /mcp or on a tool call rather than printed by a command. They are quoted from Anthropic's error reference and the headersHelper section of the same page, read on October 23, 2026.

Couldn't read the stored credentials for MCP server

Couldn't read the stored credentials for MCP server "<name>", so the request didn't run. Try again.

A request to MCP server "<name>" was sent without your stored credentials, so the server rejected it. The credentials are available now. Try again.

What it means. Claude Code keeps your sign-ins for OAuth MCP servers in a credential store, and it could not read that store, so a request to the server did not run. Your stored sign-ins are unchanged, which is why the fix is to make the store readable rather than to sign in again. On a Mac the same first line can carry one more sentence, pointing at a locked login keychain as the cause.

What causes it

• A locked login keychain on macOS.
• A credential store a sandbox or a security product will not let the process read.
• On macOS, a claude -p run or an Agent SDK run whose keychain became readable only after the request had already gone out. That request fails with the second line above: it went out before the keychain could be read, and by the time you see the message the credentials are available.

How to fix it

1. Run claude doctor in the shell session you run Claude Code from, and read its report for a keychain warning.
2. If the report lists a warning starting macOS Keychain is not writable, or your shell has no claude command, run the keychain command in Anthropic's steps for this message in exactly that shell session, against ~/Library/Keychains/login.keychain-db. If the report lists no keychain warning, skip that command.
3. Try again where you saw the message. For claude -p, run the command again. In a session, reconnect the server from /mcp if it shows as failed there, then ask Claude to try again. In an Agent SDK application that keeps running, call reconnectMcpServer() in TypeScript or ClaudeSDKClient.reconnect_mcp_server() in Python, or start a new session.
4. If the server then reports that it needs authentication, Claude Code found no sign-in it can use for that server. Sign in with /mcp in a session, or claude mcp login <name> in your shell.

What not to do

Do not sign in again before the store is readable. The message says your sign-ins are unchanged, and a fresh sign-in writes to the same store, so it fails the same way while adding one more thing to clean up.

Not reproduced

This needs a locked or unreadable credential store on a machine with a stored MCP sign-in, which the capture setup had none of. The messages and the steps come from Anthropic's error reference, read on October 23, 2026, including the note on versions before 2.1.307.

The sign-in can't start

Couldn't complete authentication for "<name>": This server's URL is missing or not a valid URL, so sign-in can't start. Fix the URL in its MCP config (or set the environment variable it uses) and try again.

OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.

No available ports for OAuth redirect

What it means. Three ways the local half of an OAuth sign-in fails. The first means the server's configured url does not parse as a URL, so Claude Code refused to start the sign-in and printed the refusal after Couldn't complete authentication for "<name>":. The second means the callback port the sign-in needs is held by another process. The third means Claude Code could not bind a local port at all.

What causes it

• An empty url, a typo in it, or a ${VAR} reference whose variable is not set.
• A fixed callback port, set with MCP_OAUTH_CALLBACK_PORT or --callback-port, that another program already holds.
• Security software or a sandbox policy that denies processes a listener on 127.0.0.1. Before v2.1.268, Claude Code did not fall back to an operating-system-assigned port, so on Windows hosts where Hyper-V reserves ranges covering the ports Claude Code picks from, this message could appear for that reason too.

How to fix it

1. Set the entry's url to the server's real endpoint, or set the environment variable its ${VAR} reference names, then start the sign-in again.
2. Run the command in the port message to find the process holding the port and stop it, or wait for it to finish. On Windows the command is netstat -ano | findstr :<port>.
3. If another program needs that port permanently, register a different redirect URI with the server and set its port with MCP_OAUTH_CALLBACK_PORT or --callback-port, whichever you use.
4. For no available port, allow Claude Code to bind a local port, then start the sign-in again from /mcp.

What not to do

Do not keep pressing Authenticate when a fixed callback port is held by another process, and do not drop the fixed port to get past it. A server that registered that exact redirect URI will refuse the one Claude Code picks instead.

Not reproduced

All three need a remote OAuth server and, for the port cases, a program holding the port on purpose, which the capture setup had neither of. The messages and the steps come from Anthropic's error reference and its MCP page, read on October 27, 2026.

Refusing to send credentials to non-https token endpoint

Refusing to send credentials to non-https token endpoint 'http://192.168.1.50:8123/oauth/token'. OAuth token requests MUST use TLS (localhost / 127.0.0.1 / ::1 are exempt).

What it means. On the v2 runtime, Claude Code sends an MCP OAuth token request only to a token endpoint served over HTTPS or at localhost, 127.0.0.1 or ::1. The server's endpoint is none of those, so Claude Code stopped before sending the request. This happens after the browser step, so the browser sign-in succeeds first, and again on every token refresh.

What causes it

• A self-hosted MCP server whose OAuth endpoints are plain http:// at an address other than the three that are exempt.
• A server behind a reverse proxy that terminates TLS but still advertises its own http:// address in its OAuth metadata.

How to fix it

1. Serve that token endpoint over HTTPS, for example by putting the server behind a reverse proxy or tunnel that terminates TLS, and configure the server to advertise the https:// address.
2. To connect without changing the server, start Claude Code with MCP_SDK_GENERATION=v1, whose runtime does not apply the rule and sends the token request over plain HTTP. That choice lasts until you exit and applies to every server.
3. If the server URL carries a query string or a long random segment, Claude Code redacts the SDK's message and shows a short name instead. A redacted message can be this error only when the token endpoint is plain HTTP at an address outside the exempt three.

What not to do

Do not leave the v1 runtime switched on as the standing fix. It also skips the issuer check described in the next section, so one environment variable turns off both protections for every server on the machine.

Not reproduced

This needs a remote OAuth server with a plain-HTTP token endpoint, which the capture setup had none of. The message and the steps come from Anthropic's error reference, read on October 23, 2026.

Issuer mismatch in authorization response

Issuer mismatch in authorization response (RFC 9207): expected "https://auth.example.com", received "https://other.example.com"

What it means. During an MCP OAuth sign-in the authorization server redirected back with an iss parameter that does not name the issuer Claude Code expected from the server's OAuth metadata. A wrong issuer at this step is how an authorization server mix-up attack looks, so Claude Code fails the sign-in rather than exchanging the authorization code. expected is the issuer from the metadata and received is the value the redirect carried.

What causes it

• An authorization server whose metadata and redirects disagree about which issuer it is.
• A server whose metadata sets authorization_response_iss_parameter_supported, in which case a redirect that carries no iss at all also fails the check.

How to fix it

1. Try the sign-in again from /mcp.
2. If the error repeats, report it to the server operator. The fix is server-side: the authorization server has to return the same issuer in its iss parameter that it advertises in its metadata.
3. To connect while the server is being fixed, start Claude Code with MCP_SDK_GENERATION=v1, whose runtime does not run this check.

What not to do

Do not treat this as a cosmetic failure and switch the check off as your normal setup. It is the protection against an authorization server mix-up, and the durable fix is on the server, not in your environment.

Not reproduced

Reaching this needs a remote authorization server that returns a mismatched issuer, which we cannot arrange from a test machine. The message and the steps come from Anthropic's error reference, read on October 23, 2026.

The server connects but no tools appear

! Connected · tools fetch failed

What it means. The server connected but could not list its tools, so the session has none of them. It is a status rather than an error message: /mcp and claude mcp list show it beside that server, and claude mcp get <name> carries the server's own words on its Issue: line. A server that connects and answers with an empty tool list is a different state, and that one shows as plain Connected.

What causes it

• The server started without a required environment variable, an API key most often, so it registered nothing.
• A server that advertises the tools capability and returns an empty list on a discovery request.
• A server that advertises the tools capability and then fails on the discovery request that lists them.
• Claude Code older than 2.1.302, for one cause only: a server on protocol revision 2026-07-28 that left resultType, ttlMs or cacheScope out of its replies. That release fixed that cause.

How to fix it

1. Run /mcp, select the server and read its tool list. An empty list is the server's own report that it started without what it needs.
2. Pass the missing variable with --env KEY=value on claude mcp add, or in the env field of the server's .mcp.json entry. The server's own documentation lists the variables it needs.
3. Read the Issue: line. It carries the server's own error, which usually names what failed inside it.
4. If the server is on protocol revision 2026-07-28 and you are on a build before 2.1.302, update Claude Code.
5. Run claude mcp list and read the warnings under it for a missing environment variable, which names the variable rather than the value.

What not to do

Do not reinstall the server before you have looked at env. A connected server with no tools has already told you what is wrong: it is running, and it is running without something it needed at startup.

Reproduced

Two local servers, both added at user scope. One fails the request that lists its tools; the other connects with no trouble:

$ claude mcp list
Checking MCP server health…

bigout: node /tmp/mcpout/big.mjs - Connected
badtools: node /tmp/mcpout/badtools.mjs - ! Connected · tools fetch failed — Internal error: tool registry failed to load

Ask the failing one for the detail step 3 sends you to, and you get the server's own words on the Issue: line. The text after Issue: is what our test server was written to return, not wording from Anthropic:

$ claude mcp get badtools
badtools:
  Scope: User config (available in all your projects)
  Status: ! Connected · tools fetch failed
  Issue: Internal error: tool registry failed to load
  Type: stdio
  Command: node
  Args: /tmp/mcpout/badtools.mjs
  Environment:

To remove this server, run: claude mcp remove badtools -s user

The check mark before Connected on the first line of the listing is left off, and the rest is as printed. Claude Code 2.1.309 on Linux x64, October 23, 2026.

$ claude mcp get demo-emptytools
demo-emptytools:
  Scope: User config (available in all your projects)
  Status: Connected
  Type: stdio
  Command: node
  Args: /tmp/mcpdemo2/emptytools.mjs
  Environment:

To remove this server, run: claude mcp remove demo-emptytools -s user

That server answers the initialize handshake, advertises the tools capability, and lists no tools. Claude Code reports it as connected, which is the point: the connection succeeded and the server exposed nothing. The check mark before Connected is left off this line and the others on this page. Claude Code 2.1.309 on Linux x64, October 23, 2026.

Sources: Anthropic's MCP quickstart, for the status table and the missing-variable fix, and Anthropic's MCP page, for what /mcp shows beside a connected server. Both read October 23, 2026.

MCP tool name over 128 characters

Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 128

API Error: 400 ... tools.N.custom.name: String should have at most 128 characters

What it means. A server lists a tool whose full name, in the form mcp__<server>__<tool>, is longer than the 128 characters the API accepts. Claude Code leaves that tool out of the tools it sends to Claude, and the server's other tools keep working. The first line goes to the debug log rather than the screen, so you see it only in a session started with claude --debug. The second line is what the API answered instead, before 2.1.292.

What causes it

• A long server name, a long tool name, or both, adding up past the cap.
• A plugin bundling the server, since the tool's full name then includes the plugin name as well.

How to fix it

1. Start a session with claude --debug and read the log at ~/.claude/debug/<session-id>.txt, which names the tool that was left out and its length.
2. If the server is in your own configuration, give it a shorter name there, for example db in place of analytics-database.
3. Then update everything that referred to the server or its tools by the old name, which means your permission rules and your hook matchers.
4. If a plugin bundles the server, ask the plugin's maintainer to shorten the server or tool name.

What not to do

Do not rename the server in your configuration and stop there. A permission rule written against mcp__analytics-database__query stops matching the moment the server is called db, and the tool that was silently hidden becomes a tool that loudly asks for approval.

Not reproduced

The log line is written when a session loads its tools, which needs a session against the API, so there is no capture from the setup we tested with. The line and the older API rejection come from Anthropic's error reference and its MCP page, read on October 23, 2026.

Tool input schema is invalid

API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid

API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'

What it means. A tool in the request declared an input_schema that fails the API's JSON Schema validation, so the API rejected the whole request. The number after tools. is the failing tool's position in the request's tool list, not a name you can look up. The first form means the schema is not valid JSON Schema draft 2020-12. The second means a top-level property name does not match the pattern the message quotes.

What causes it

• A server whose tool declares an invalid input schema.
• A schema declaring a JSON Schema dialect other than draft 2020-12 in $schema. Claude Code does not check those against the meta-schema, though the top-level property-name check still applies.
• A deployment where flag fetching is off, or one whose flags have never arrived. Claude Code records which tool would be rejected in the server's log and sends it anyway, so the error still occurs.

How to fix it

1. Run claude update if your version is earlier than 2.1.216. From that version Claude Code excludes MCP tools whose input schema would fail this validation when it loads a server's tools, so a request normally never includes one.
2. Remove or disable the server that declares the invalid schema. The error names the tool only by position, so check each server's log for a line naming a tool whose input schema would be rejected.
3. If no log names one, disable servers one at a time until the error clears.
4. If you maintain the server, fix the input_schema: it must be valid JSON Schema, and top-level property names must be 1 to 64 characters long and use only ASCII letters and digits, _, . and -.

What not to do

Do not stop at the first server whose removal clears the error and assume you found it. The error names a position, not a name, so the log line is the only thing that identifies the tool, and disabling several servers at once leaves you unable to tell which one it was.

Not reproduced

Raising this needs an MCP server that declares a schema the API rejects, and a session to send it in. The messages and the steps come from Anthropic's error reference and its MCP page, read on October 23, 2026.

No such tool available

Error: No such tool available: <tool name>

Error: No such tool available: read. Tool names are case-sensitive: call Read instead.

What it means. Claude called a tool by a name that is not in the session's tool list. Claude Code returns the error to Claude as the tool call's result rather than stopping the turn, so the conversation carries on. When Claude Code can tell why the tool is missing, it adds a sentence after the name that gives the reason or names the tool to call instead.

What causes it

• A tool name that is wrong by case, as in the second line.
• An MCP server still on its first connection attempt right after you resumed a session. Claude Code holds the call for up to 10 seconds and runs it once the tool is available.
• A server that failed to connect, or one already retrying after a failed attempt.
• A call whose tool name Claude Code cut to 200 characters.

How to fix it

1. If it happens once, nothing is needed. Claude reads the error and the turn continues.
2. If calls to one server's tools keep failing, run /mcp in the session or claude mcp list in your shell to check the server's status, and reconnect a failed server from /mcp.
3. If a server is merely slow to connect, raise MCP_TIMEOUT so the wait has room.
4. If the name in the message is a built-in tool in the wrong case, use the name the message gives you.

What not to do

Do not ask Claude to try again when the tool name is wrong by case, and do not read a single occurrence as a broken install. The message already names the tool to call in the case-sensitivity form, and a lone one is the CLI telling the model what happened rather than telling you something is broken.

Not reproduced

An MCP tool name that is cut to 200 characters is one route to this message and a saved conversation is another, and neither is within reach of the setup we tested with. The messages and the steps come from Anthropic's error reference and its MCP page, read on October 23, 2026.

The connection closed before the tool call was answered

MCP server "<name>" connection closed before the tool call was answered. The tool may have run: check whether it did before running it again.

What it means. A tool call to an HTTP MCP server or a claude.ai connector lost its connection before the server answered, so Claude Code cannot tell whether the tool ran. Repeating the call could repeat the tool's action, such as creating a second issue.

What causes it

• A network drop between the call going out and the answer coming back.
• A server that restarted or was redeployed mid-call.
• A proxy or gateway that closed the connection.

How to fix it

1. Check in the service the tool acts on whether the action happened, for example whether the issue or the record it was meant to create is there.
2. If the action happened, do not run the tool again. Claude received this message in place of the tool's result, so tell Claude the outcome.
3. If the action did not happen, ask Claude to run the tool again. You do not need to reconnect the server first, because Claude Code connects again for the next call to one of its tools.
4. If you build the server and the tool is safe to call twice, mark it as safe to repeat so Claude Code can repeat a lost call on its own.

What not to do

Do not repeat the call blindly, and do not assume the tool did not run because the answer was lost. Claude Code repeats the call by itself, once, and only when the server marks the tool safe to repeat, which is how a server that must not run twice says so.

Not reproduced

Reaching this needs a live HTTP server whose connection drops between the call and the answer, which is not a state we can arrange from a test machine. The message and the steps come from Anthropic's error reference, read on October 23, 2026.

MCP tool output is too large

Error: result (33,979 characters across 600 lines) exceeds maximum allowed tokens. Output has been saved to <session>/tool-results/mcp-bigout-big_report-1792792895943.txt.
Format: Plain text
Use offset and limit parameters to read specific portions of the file, search within it for specific content, and jq to make structured queries.
...

What it means. The tool's result was larger than the limit allows, so Claude Code saved it to a file and put a short note in the conversation where the result would have been, naming that file. Anthropic's documentation describes this behaviour without printing the wording, so the line above is the real one, raised here and pasted as printed, with two marked cuts. Claude Code shows a warning when any MCP tool output passes 10,000 tokens, and the default maximum is 25,000 tokens, set by MAX_MCP_OUTPUT_TOKENS. When a successful result with no image content exceeds the limit, Claude Code saves it to a file and replaces it in the conversation with a message that names the file path, so Claude reads the file when it needs the content. Two more limits sit beside it: unless the server raises a tool's own limit, a text result longer than 50,000 characters is saved to a file whatever its token count, and a response from an HTTP or SSE server that passes 16 MiB is stopped and the request fails.

What causes it

• A tool that returns a large document, a long query result or a whole file in one reply.
• Images in a tool result, which count against MAX_MCP_OUTPUT_TOKENS even when the tool declares its own character limit.
• A server returning more than 16 MiB in one response or one WebSocket message.

How to fix it

1. Leave it alone where you can. An oversized result is saved to a file in the session's tool-results directory under ~/.claude/projects/, and Claude can read it when it needs the content.
2. Raise the limit for the tools that do not declare one by setting MAX_MCP_OUTPUT_TOKENS before you start Claude Code, for example export MAX_MCP_OUTPUT_TOKENS=50000. The warning threshold itself is fixed. Tools setting anthropic/maxResultSizeChars use that value for text content regardless of this variable.
3. If you maintain the server, return less data per response, for example by paginating results. Anthropic's docs list no setting for the 16 MiB response limit, and a WebSocket message over it closes the connection and fails the calls in progress.
4. Ask the server's author to declare anthropic/maxResultSizeChars on a tool whose big output is expected, so the tool's own limit decides rather than the global one.

What not to do

Do not raise the limit to make a slow session feel fixed. Everything under the limit still enters the conversation and is sent with every later request, so a tool returning 30,000 tokens on each call spends them again on every turn. Fix the tool's output size instead.

Reproduced

One local server, one tool returning about 34,000 characters of text, and the token limit turned down so that result trips it in a single call. The result is short of the 50,000 characters that would save it to a file on length alone, so what reached the limit here is the token budget:

$ MAX_MCP_OUTPUT_TOKENS=1000 claude -p "Call the bigout tool big_report once, then reply with only the number of characters of text it returned." --allowedTools "mcp__bigout__big_report" --output-format stream-json --verbose
Error: result (33,979 characters across 600 lines) exceeds maximum allowed tokens. Output has been saved to <session>/tool-results/mcp-bigout-big_report-1792792895943.txt.
Format: Plain text
Use offset and limit parameters to read specific portions of the file, search within it for specific content, and jq to make structured queries.
...

Two cuts, both marked. The path after saved to is shortened to <session>: it is the throwaway home directory the run used, not anyone's. And the ... stands for the rest of the note, a block of instructions to the model about reading the file in order and saying what it did not read. The result itself is not in the conversation at all, which is the whole point of the behaviour. Claude Code 2.1.309 on Linux x64, October 23, 2026.

Sources: Anthropic's MCP output limits section, read October 27, 2026.

Blocked by managed policy, or a reserved name

MCP server <name> is blocked by enterprise managed policy

"workspace" is a reserved MCP server name and was not loaded

What it means. The first line appears when you select Reconnect on a server in /mcp, or turn a disabled server back on there, and a setting that restricts MCP servers blocks that server. The second names one of your servers whose name Claude Code reserves, which it skips at load time.

What causes it

• A deniedMcpServers entry matching the server, including one in your own ~/.claude/settings.json or the project's .claude/settings.json.
• An allowedMcpServers list the server does not match.
• strictPluginOnlyCustomization with mcp locked, which blocks servers configured in ~/.claude.json and .mcp.json.
• disableClaudeAiConnectors, when the server is a claude.ai connector.
• A name among those Claude Code reserves, which include workspace, claude-in-chrome, computer-use, Claude Preview and Claude Browser.

How to fix it

1. Check your own user and project settings files for one of those settings and change or remove it.
2. If none of your own settings explains the block, ask your administrator which managed setting blocks the server.
3. Rename a reserved server where you define it, for example from workspace to my-workspace, then update anything that referred to it by the old name.

What not to do

Do not read a policy block as a broken server and start reinstalling it. Nothing about the server changed, and claude mcp add rejects a reserved name outright, so the server that loads is the only one a rename can fix.

Not reproduced

Producing these needs an administrator's policy document, which a test machine cannot have, or a reserved name in a configuration we would then have to load in a session. The messages and the steps come from Anthropic's error reference and its MCP configuration warnings, read on October 23, 2026.

Running several sessions at once

An MCP server you never use is not free: its tool names and instructions load at the start of every session, and its full tool definitions load too when tool search is off, for example on an older model, on a Microsoft Foundry deployment hosted on Azure, or with the search turned off. Omniscio, the desktop app we make for running many Claude Code sessions at once, keeps a list of your MCP servers with how often each one is actually called, and decides per project or per session which servers a session starts with, resolving a session override first, then the project's choice, then the global default. It also raises an alert when the servers you have switched on add up to too much overhead, by estimated tool-definition tokens, by measured memory while sessions run, or by having gone unused. The MCP Servers guide covers the per-session controls, the features page lists the rest of it, and the download page has the installers.

Sources

Every meaning and every step on this page rests on one of these, and each capture rests on the run described under how we tested. The date beside each source is the day we read it.

• Claude Code error reference, for the connection-timeout, stored-credential, sign-in, tool-name, input-schema, tool-availability and policy messages and the steps under each. Read October 27, 2026.
• Connect Claude Code to tools via MCP, for server status and its detail, the configuration warnings, automatic reconnection, tool availability, the time limits and the output limits. Read October 27, 2026.
• MCP quickstart, for the troubleshooting symptoms, the reachability checks and the stdio command checks. Read October 23, 2026.
• Environment variables, for MCP_TIMEOUT, MCP_TOOL_TIMEOUT, MAX_MCP_OUTPUT_TOKENS, MCP_OAUTH_CALLBACK_PORT and MCP_SDK_GENERATION. Read October 23, 2026.

Anthropic's error reference and MCP pages move with nearly every Claude Code release, and they keep notes such as "Before v2.1.302" and "Before v2.1.307". Read them again before you trust a copy of this page from a few months back.

Common questions

What does Failed to connect mean in claude mcp list?

Claude Code could not reach or start that one server. It is the server's failure, not the list command's. The status line carries the detail: claude mcp get shows it on an Issue: line, with the HTTP status or error code and any text the server returned.

How long does Claude Code wait for an MCP server to start?

Thirty seconds, set by the MCP_TIMEOUT environment variable. Raise it for the run, as in MCP_TIMEOUT=60000 claude, if the server is slow on its first start while npx downloads it.

Why does my MCP server keep asking me to sign in again?

The server rejected the credential on a tool call, usually because the sign-in or token expired, or because the token lacks a permission the tool needs. Run /mcp, select the server and sign in again. If the message names a scope and you pinned oauth.scopes, add that scope to the list first.

Why does my MCP server connect but show no tools?

The server started but registered no tools, which usually means it is missing a required environment variable such as an API key. Pass it with --env KEY=value on claude mcp add, or in the env field of the server's entry.

What is the MCP tool output limit in Claude Code?

Claude Code warns when any MCP tool output passes 10,000 tokens, and the default maximum is 25,000 tokens, set by MAX_MCP_OUTPUT_TOKENS. A result over the limit with no images is saved to a file and replaced in the conversation with a message naming that file. Unless the server raises a tool's own limit, a text result longer than 50,000 characters is saved to a file whatever its token count.

How do I fix an MCP server that the API rejects for its tool names?

A full tool name such as mcp__server__tool is capped at 128 characters. Claude Code leaves a longer tool out of the request and the server's other tools keep working, so give the server a shorter name in your configuration, then update any permission rule or hook matcher that named the old one.