SU8 Codes
< Back to blog
Official article 28 min read

Fixing MCP Server Connection Errors in Claude Code

MCP server failed to connect in Claude Code? This troubleshooting guide starts with a symptom/cause/first-check table, then covers config locations and scopes, command paths and runtimes, stdio vs HTTP/SSE/WebSocket transports, project approval and permissions, startup and tool timeouts, debug logs, environment variables and working directories, OAuth and callback ports, and proxy/CA issues, with commands and expected output from the official docs. Based on Claude Code documentation and MCP specification 2026-07-28, checked November 15, 2026.

#mcp#claude-code#troubleshooting
Fixing MCP Server Connection Errors in Claude Code

An MCP server failed to connect in Claude Code, and claude mcp list gives you one line: ✘ Failed to connect. That line says Claude Code could not reach the server. It does not say whether the problem is the config file, the launch command, a missing runtime, the transport, project approval, a timeout, authentication, a port, or the network. This guide starts with a symptom table, then walks through each layer with commands and the output the official docs describe. Commands and expected results follow the official documentation checked on November 15, 2026. If you want the protocol basics first, see What Is MCP.

Quick table: symptom, likely cause, first check

SymptomLikely causeFirst check
✘ Failed to connectThe server did not start, the URL did not respond, or the server rejected the token in headers.AuthorizationRead the failure detail on the status line, then the Issue: line from claude mcp get <name>
✘ Connection errorThe connection attempt threw an exception; the text can contain the server URL, so Claude Code omits itRun curl -I <url>, or run the configured stdio command directly
⏸ Pending approvalA project-scoped .mcp.json server has not been approved, or the folder is not trustedRun claude in the project and approve it; if needed, run claude mcp reset-project-choices
! Needs authenticationA remote server expects OAuth (an authorization protocol) or a tokenSign in from /mcp, or run claude mcp login <name>
Connected, but zero toolsThe server registered no tools, often because an environment variable is missingInspect the tool list in /mcp; add the variable under env or with --env
Startup timeoutThe first npx run is downloading a package and exceeds the 30-second defaultMCP_TIMEOUT=60000 claude
404 MCP endpoint not foundThe URL is missing a path or points at the wrong endpointCompare the full URL from claude mcp get <name> with the server's documented endpoint
401 or 403 with an Authorization headerThe token is invalid, or the variable expanded to an empty valueUpdate the header; check whether the variable is one Claude Code reads as empty
Works in a terminal, fails in Claude CodeRelative path, working directory, or environment differsUse absolute paths in command and args; put required variables in env
Every remote server failsProxy, CA (certificate authority) certificate, DNS, or an enterprise policyRun curl -I on the same URL; check the Proxy row in /status; set HTTPS_PROXY or NODE_EXTRA_CA_CERTS
The process exits mid-sessionThe stdio server crashed or received a shutdown signalReconnect from /mcp; run the command directly to see the error
Connects, then dropsThe remote connection dropped; automatic reconnects stoppedReconnect from /mcp; try /mcp reconnect all on a recent version

Three different failures

Failed to connect and Connection error both mean the server did not start or the URL did not respond. The quickstart notes one more case: an HTTP server that rejects the token in headers.Authorization also shows one of these two statuses. A server that wants a token you have not configured shows ! Needs authentication instead.

Failed to connect carries more information. Claude Code appends the failure detail to the status line in claude mcp list, and claude mcp get <name> prints it on an Issue: line. The detail contains the HTTP status or error code plus any error text the server returned. Connection error has no detail because the exception text can embed the full server URL, and a URL can carry secrets.

Some statuses look like connection failures but are configuration decisions. Claude Code never attempted a connection:

StatusMeaningWhat to do
⏸ Pending approval (run claude to approve)A .mcp.json server has not been approvedRun claude in the project and approve it
✘ Rejected (see disabledMcpjsonServers in settings)A disabledMcpjsonServers entry rejects itRemove the entry from settings
⊘ Disabled for this project (re-enable via /mcp)The project turned it offRe-enable it in /mcp
✘ Blocked by enterprise managed policyAn organization policy blocks itAsk your administrator which policy applies

Start with these two commands:

claude mcp list
claude mcp get <name>

claude mcp list shows a health status next to each server, such as ✔ Connected, ! Needs authentication, or ✘ Failed to connect. claude mcp get <name> shows which scope holds the definition, the command or URL, and the Issue: line. Inside a session, /mcp shows the same status and detail.

Where Claude Code reads the config

MCP servers live in one of three scopes, or configuration levels.

ScopeFileWho can use it
local (default)~/.claude.json, under the current project's entryOnly you, only this project
project.mcp.json at the project rootEveryone who clones the repository
user~/.claude.json, under the top-level mcpServers keyOnly you, every project

Project config has a few rules that are easy to break. The file must be .mcp.json at the repository root, not inside .claude/. Servers go under the mcpServers key, not under a top-level servers key as in VS Code's mcp.json. A mcpServers key in settings.json is not read at all. The docs also list paths Claude Code does not read: ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json, and %APPDATA%\Claude\mcp.json.

A project entry looks like this:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Claude Code reads .mcp.json at session start. Exit the session and restart after editing it. If one entry is malformed, Claude Code skips that entry and loads the others; claude mcp list prints a parse warning that names the offending field.

When the same server name is defined in more than one scope with different endpoints, claude mcp list and /mcp show a conflict warning. Run claude mcp get <name> to see which scope actually loads, then remove the copy you do not want:

claude mcp remove <name> --scope <scope>

One quieter config problem is hidden whitespace, often a trailing newline pasted along with a token. Claude Code checks command, url, every entry in args, and the keys and values under env and headers. It warns in claude mcp list and /mcp, names the affected field without printing its value, and uses the value exactly as written. You have to edit the config to remove the whitespace.

Command, args, and runtime

A stdio server (standard input and standard output) is a subprocess that Claude Code launches on your machine. In claude mcp add, the -- separator splits Claude Code's own options from the server command. Everything after -- goes to the server untouched:

claude mcp add --transport stdio myserver -- npx server
claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080

Without --, Claude Code tries to parse flags such as --port as its own options. --env has a placement rule too: the server name cannot come directly after --env, or the CLI reads it as another KEY=value pair and rejects it. Put at least one other option, such as --transport stdio, between them.

After writing the config, run claude mcp get <name> and compare its Command line with the command that works in your terminal. The docs give a direct test: run the configured command by hand.

npx -y @playwright/mcp@latest

There are two expected outcomes. If the command starts and waits for input, the server itself works; the remaining problem is on the Claude Code side, in the config, path, or environment. If the command errors, the message usually names what is missing, such as Node.js or a browser.

If you want to test the server outside Claude Code, use MCP Inspector. It requires Node 22.19.0 or newer:

npx @modelcontextprotocol/inspector node path/to/server/index.js

The Inspector is the reference developer tool for MCP servers and ships web, CLI, and TUI clients.

Check the runtime as well. For Node-based servers, run node --version and npx --version. For Python-based servers, check uvx --version or uv --version. On macOS or Linux, command -v npx and command -v uvx show whether the command is on PATH, the list of directories your shell searches for executables. On Windows PowerShell, use Get-Command npx. A path means the command is available; an empty result means it is not installed or not on PATH.

The MCP debugging guide warns that a stdio server's working directory may be undefined, and on macOS can even be /. Use absolute paths for local scripts. A relative path in command or args resolves against the directory where you launched Claude Code, not the directory that holds .mcp.json. Executables that already live on PATH, such as npx and uvx, can stay as bare command names.

Windows has another trap. The MCP local-server guide notes that a ${APPDATA} reference or an ENOENT error in the server's logs may require adding the expanded %APPDATA% value to env, for example C:\\Users\\user\\AppData\\Roaming\\. That page describes Claude Desktop, and states that the same principles apply to any stdio-based MCP client.

Finally, check what the server writes to stdout. The MCP stdio spec is explicit: the server must not write anything to stdout that is not a valid MCP message. Logs belong on stderr. A server that prints a startup banner or debug line to stdout may look fine in a terminal, while Claude Code reads something that is not JSON-RPC, the JSON-based remote procedure call format, and the connection fails. Running the command by hand and watching for non-JSON output on stdout helps rule this out.

Transport type and protocol version

A common JSON mistake is a url entry with no type. Claude Code reads an entry with no type as a stdio server, skips the entry, and reports:

MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry.

Use HTTP for remote servers when you can:

claude mcp add --transport http example https://mcp.example.com/mcp

In JSON, "type": "streamable-http" is an alias for "http", so configs copied from server docs work without edits. SSE, or Server-Sent Events, is deprecated. For a service that only exposes an SSE endpoint, use the same --transport http command; Claude Code tries HTTP first and switches to SSE when the server does not accept it. That automatic switch requires Claude Code v2.1.265 or later. On an older version, or to connect over SSE directly, use --transport sse.

WebSocket servers are configured in .mcp.json or with claude mcp add-json, because --transport does not accept ws. WebSocket authentication is header-only and does not use OAuth.

When an HTTP server returns 404, selecting it in /mcp shows:

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

The message names only the origin, not the path. Get the full URL from claude mcp get <name>, compare its path with the server's documented MCP endpoint, then remove and re-add the server:

claude mcp remove <name>

Protocol versions can also block a connection. As of November 15, 2026, the latest MCP specification is 2026-07-28. Its standard transports are stdio and Streamable HTTP. Earlier revisions used a connection-scoped session with an initialize handshake; the older HTTP+SSE transport is deprecated. On a version mismatch, a server can return UnsupportedProtocolVersionError with code -32022; the error's data field lists the versions the server supports. Claude Code's v2 runtime negotiates the newer revision, as described in the "MCP client runtimes" section of its docs. MCP_SDK_GENERATION and MCP_PROTOCOL_NEGOTIATION can pin the runtime and negotiation mode for diagnosis; check the documented limits before keeping either as a permanent setting.

Permissions and approval

Project-scoped servers in .mcp.json need a one-time approval in interactive sessions. If you dismissed the prompt, the server stays at ⏸ Pending approval. Bring the prompt back with:

claude mcp reset-project-choices

Restart Claude Code, and it asks again for every project server.

Workspace trust affects approval too. A cloned repository cannot approve its own servers: enableAllProjectMcpServers or enabledMcpjsonServers committed in the project's .claude/settings.json is ignored in an untrusted folder, and the server stays at ⏸ Pending approval. Run claude, accept the workspace trust dialog, then approve.

Three settings keys control project servers:

KeyEffect
enableAllProjectMcpServersApprove every server in project .mcp.json files without prompting
enabledMcpjsonServersApprove only the named servers
disabledMcpjsonServersReject the named servers in every permission mode

Permission rules use the server and tool name. To match every tool from one server, write mcp__<server>__*. To match a single tool, write mcp__<server>__<tool>. Allow rules accept globs only after a literal mcp__<server>__ prefix; an unanchored allow glob such as "*", "B*", or "mcp__*" is skipped and approves nothing. Deny and ask rules can use "mcp__*" to cover every MCP tool.

If the server shows as connected but Claude cannot use its tools, check the tool count. /mcp shows the count next to each connected server and flags servers that claim the tools capability but expose no tools. A count of zero often means a required environment variable is missing; add it with --env or under env in .mcp.json.

Tool names can also be dropped. The full name is mcp__<server>__<tool>, and the API accepts at most 128 characters. Claude Code leaves an over-long tool out of what it sends to the model while the server's other tools keep working. Start a session with claude --debug and the debug log shows:

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

If the server name is long, give it a shorter name in the config, such as db instead of analytics-database, and update permission rules and hook matchers that referenced the old name.

To test whether your own configuration is involved, start in safe mode:

claude --safe-mode

Safe mode disables CLAUDE.md, skills, plugins, hooks, MCP servers, and other customizations. If the problem disappears, the cause is in one of those. You can also start with a clean config directory and only user settings, which excludes project-level .claude/settings.json, CLAUDE.md, and .mcp.json:

CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user

Timeouts and slow starts

The default MCP server startup timeout is 30 seconds. The first npx run may download a package for longer than that, and claude mcp list can show ✘ Failed to connect until the download finishes; run it again and the status can become ✔ Connected. Raise the limit with MCP_TIMEOUT, in milliseconds:

MCP_TIMEOUT=60000 claude

For an HTTP or SSE server, a transient error on the first connection gets up to three retries. A 5xx response, a connection refused, or a timeout counts as transient. Authentication errors and not-found errors are not retried because they need a configuration change. After three failures, the server is marked failed.

A remote server that drops mid-session gets up to five reconnect attempts with exponential backoff, starting at one second and doubling. After five failures, an interactive session shows MCP server "<name>" disconnected · open /mcp to reconnect, and you can reconnect manually from /mcp. Recent versions can retry every failed or unauthenticated server at once:

/mcp reconnect all

That command requires Claude Code v2.1.284 or later; earlier versions print MCP server "all" not found.

A stdio server's first connection is not retried automatically. If the process exits mid-session or fails to start, the server is marked failed and you reconnect from its menu in /mcp. Keep the stdio and remote retry behavior separate when you troubleshoot.

One timeout has nothing to do with the network: the computer sleeping or its clock jumping forward. The error text is:

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

Reconnect and keep the machine awake until the attempt finishes; in an interactive session, use Reconnect from /mcp.

Tool-call timeouts are a different layer. MCP_TOOL_TIMEOUT bounds one tool execution and defaults to about 28 hours. HTTP, SSE, and claude.ai connector servers also have a per-request timer of at least 60 seconds, covering the time until the server sends the first byte. A per-server timeout field in .mcp.json takes precedence. If a server sends no response and no progress notification for the idle window, the call aborts early; the default is five minutes for network servers and 30 minutes for stdio, and CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT changes it. Use this distinction: a failure during connection points at startup timeout; a failure after connecting points at tool timeout or idle timeout.

Where the logs are

Start light. The /mcp detail view has an Issue: row with the same failure detail shown by claude mcp list and claude mcp get. That row often names the HTTP status, the error code, or the server's own error text.

For more detail, turn on MCP debug logging:

claude --debug=mcp

A stdio server's stderr goes to the debug log at ~/.claude/debug/<session-id>.txt. The debugging guide recommends this command when a server connects but reports zero tools, then reading that server's stderr in the log. To choose the log file:

claude --debug-file /tmp/claude-debug.log

DEBUG=1 is equivalent to --debug; logs go to ~/.claude/debug/<session-id>.txt by default, and CLAUDE_CODE_DEBUG_LOGS_DIR sets the log file path (it is a file path, not a directory). Inside a session, /debug [issue] enables debug logging and asks Claude to diagnose using the log output and settings paths.

A few supporting commands help. /doctor checks the installation and settings files. /status shows active settings sources and a Proxy row. /context breaks down what is loaded into the context window, including MCP tools. The /mcp panel also shows each server's tool count and flags servers that claim the tools capability but expose none.

Environment variables and working directory

A stdio server inherits the environment Claude Code passes to subprocesses, not everything in your interactive shell. The MCP debugging guide says stdio servers inherit only a limited, platform-dependent subset. Put the extra variables in the server entry:

{
  "mcpServers": {
    "myserver": {
      "command": "mcp-server-myapp",
      "env": {
        "MYAPP_API_KEY": "some_key"
      }
    }
  }
}

.mcp.json supports ${VAR} and ${VAR:-default} expansion in command, args, env, url, and headers. If a variable is unset and has no default, the config still loads; claude mcp list warns about the missing variable and uses the unexpanded ${VAR} text. An empty string counts as set, so ${VAR:-default} expands to the empty string. In a URL, that can turn the value into /mcp, and claude mcp list reports 'url' is not a valid URL. To get the default, unset the variable instead of setting it to an empty string.

Some credential variables are read as empty in a remote server's url and headers. The covered names include Claude Code's own credentials such as ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN, cloud credentials such as AWS_BEARER_TOKEN_BEDROCK, and other credentials the environment carries such as HTTPS_PROXY and NPM_TOKEN. Writing Bearer ${ANTHROPIC_AUTH_TOKEN} sends Bearer with no credential; the server usually answers 401, and Claude Code reports a failed connection. Copy the value into a variable with your own name and reference that name instead.

CLAUDE_PROJECT_DIR is set in a spawned stdio server's environment to the project root. When you reference it in .mcp.json or ~/.claude.json, include a default such as ${CLAUDE_PROJECT_DIR:-.}, because expansion happens in Claude Code's environment, where the variable may not be set. Plugin-provided MCP configs substitute ${CLAUDE_PROJECT_DIR} directly and need no default.

To check whether a variable is set without printing its value, run [ -n "$MYAPP_API_KEY" ] && echo set || echo unset. set means it has a value; unset means it does not.

The working directory may be undefined. The MCP debugging guide says it can be / on macOS, so use absolute paths in config and .env files. Claude Code's own docs say a relative path in command or args resolves against the directory where you launched Claude Code, not the location of .mcp.json. Run pwd in that terminal to confirm the base directory.

Two environment settings tighten what a stdio server can see. CLAUDE_CODE_MCP_ALLOWLIST_ENV=1 starts stdio servers with a safe baseline environment plus the server's configured env, instead of inheriting your shell. CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 strips credentials from subprocess environments, including stdio MCP servers, while leaving HTTP_PROXY, HTTPS_PROXY, and GitHub tokens in place. Both are useful for reducing exposure, and both change which variables the server can read, so account for them when debugging a missing variable.

Authentication and OAuth

When a remote server returns 401 or 403, Claude Code's response depends on the config. A server with no Authorization header is marked as needing authentication, and /mcp offers the sign-in flow. A server whose headers.Authorization or headersHelper is configured is treated differently: Claude Code decides the credential to fix is the one you configured, reports a failed connection, and does not fall back to OAuth.

Sign in from a session or from the shell:

/mcp
claude mcp login <name>

For OAuth, the browser opens the authorization page. With no local browser, such as over SSH, claude mcp login prints the authorization URL, and you open it on your local machine and paste the full redirect URL back at the prompt. --no-browser forces that flow even when a local browser is detected. claude -p and Agent SDK sessions have no /mcp panel and cannot run the OAuth flow; complete the sign-in in an interactive session first.

The OAuth callback port can be held by another process:

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

On Windows, the documented equivalent is netstat -ano | findstr :<port>. If another program needs that port permanently, register a different redirect URI with the server and set the port with MCP_OAUTH_CALLBACK_PORT or --callback-port. By default Claude Code picks an available port, so conflicts mostly appear when you pin one.

No available ports for OAuth redirect means Claude Code could not listen on 127.0.0.1 for the callback. Security software or a sandbox policy may be blocking local listeners. The docs also note that before v2.1.268, Windows hosts where Hyper-V reserved port ranges covering Claude Code's picks could produce this error; newer versions fall back to an operating-system-assigned port.

The v2 runtime refuses to send OAuth credentials to a token endpoint that is not HTTPS, unless the endpoint is on localhost, 127.0.0.1, or ::1:

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

The proper fix is to serve the endpoint over HTTPS, for example behind a reverse proxy or tunnel that terminates TLS. The docs offer a temporary workaround: MCP_SDK_GENERATION=v1 does not apply this rule and also skips the issuer check. That gives up protection against authorization-server mix-up attacks and applies to every server in the process until you exit. Use it for diagnosis, not as a permanent setting.

An Issuer mismatch in authorization response error is a server-side problem: the authorization server returned an iss value that differs from the one in its metadata. The fix belongs on the server. The same v1 workaround exists, and the docs explicitly note that it removes the mix-up protection.

For a server with a headersHelper, Claude Code re-runs the helper and retries once before showing the error. The message distinguishes a rejected helper credential from a rejected static Authorization header. Update the helper or the header, then reconnect from /mcp.

Before removing a remote server, run this if you also want to revoke the token at the authorization server:

claude mcp logout <name>

claude mcp remove deletes the locally stored OAuth tokens and client registration, but it does not revoke them at the authorization server.

Ports

Beyond the OAuth callback port, a local HTTP MCP server's own port can be taken. Treat it like any local service: run curl -I against the configured URL and see whether anything answers. If nothing does, check whether a process is listening:

lsof -iTCP:<port> -sTCP:LISTEN

The expected output is a process line for the listener. An empty result means nothing is listening. On Windows, use netstat -ano | findstr :<port>. If another program holds the port, change the server's port or stop the other process, then update the URL in .mcp.json.

Proxy and network

If an HTTP server works in a browser or in curl but not in Claude Code, rule out the proxy and certificate path. Claude Code respects the standard proxy variables:

export HTTPS_PROXY=https://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"

Lowercase variants also work. Claude Code reads the first one set in the order https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY. If the proxy needs basic authentication, put the credentials in the proxy URL. WebSocket connections to localhost, ::1, and 127.0.0.0/8 are never sent through the proxy, so loopback addresses do not need a NO_PROXY entry.

MCP OAuth sign-in requests do use your proxy, CA, and client-certificate settings. For claude mcp login, set those variables in your shell, ~/.claude/settings.json, or a managed settings file, not in project or local settings. In an enterprise environment with a TLS-inspecting proxy, install the root certificate in the system trust store or point NODE_EXTRA_CA_CERTS at the PEM file:

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

Run /status in a session and check the Proxy row. It shows the active proxy URL and marks an unparseable value as invalid and ignored. If a certificate fails to load, the debug log contains a Failed to read or Failed to load line.

One network-layer cause is easy to miss: an organization can configure allowedMcpServers or deniedMcpServers through managed settings, the configuration an organization deploys centrally. A server blocked by an allowlist may not appear at all; one that does appear can show ✘ Blocked by enterprise managed policy. Ask your administrator; changing the client config will not help.

Known issues in the official repository

If the checks above do not explain the failure, search the anthropics/claude-code repository for the same symptom. These three issues were checked on November 15, 2026. Only the visible status and facts are recorded here; nothing below claims a fix or confirms the behavior still exists.

#4793: every stdio server on Windows 11 showed Failed to connect. The reporter used Node 22, npm 11.5.1, and Claude Code CLI 1.0.62. The servers were installed globally and ran from the command line, but claude mcp list failed for all of them in PowerShell, CMD, and the VS Code terminal. The issue was closed on August 4, 2025. If you see the same pattern, still work through the command, path, and runtime checks above; the visible issue body does not provide a fix that applies to every environment.

#61376: a 401 did not trigger OAuth. The reporter's HTTP MCP server returned a standard 401 to an unauthenticated initialize but did not include an RFC 9728 resource_metadata= hint. Claude Code showed Failed to connect instead of starting the sign-in flow. The issue was closed on May 27, 2026. If your server returns 401 without a sign-in prompt, try claude mcp login <name> manually, and check the server's WWW-Authenticate header and OAuth metadata.

#37625: Slack MCP still reports missing_token after sign-in. This issue was still open on November 15, 2026. The reported error is {"jsonrpc":"2.0","id":null,"error":{"code":-32001,"message":"missing_token"}}; the endpoint is reachable but returns 401, while other MCP servers work. An error code like this comes from the server, so the token and authorization configuration on the server side matter more than the transport in Claude Code.

When you file or update an issue, include the Claude Code version, operating system, the Issue: line from claude mcp get <name>, the /mcp status, reproduction steps, and redacted config and debug log excerpts. The official debugging guide asks for logs, configuration, reproduction steps, and environment details.

FAQ

Why does the server run in a terminal but fail in Claude Code?

Check relative paths first. Claude Code resolves them against the directory where you launched it, not the location of .mcp.json. Compare the configured command with the one that works, including the -- separator, arguments, and environment variables. Then check whether the server writes non-MCP text to stdout.

Does Claude Code retry automatically?

A remote HTTP or SSE server's first connection gets up to three retries for transient errors. A connected remote server that drops gets up to five reconnect attempts with exponential backoff. A stdio server's first connection is not retried automatically; reconnect from /mcp. Authentication errors and 404s are generally not retried because they need a config change.

Where does .mcp.json go?

At the project root, not inside .claude/, with servers under the mcpServers key. For a server only you use, ~/.claude.json holds the default local scope. Add --scope user to make it available in every project.

Is SSE still supported?

The docs mark SSE as deprecated and recommend HTTP for remote servers. For an SSE-only service, add it with --transport http and let Claude Code switch automatically (requires v2.1.265 or later), or use --transport sse directly.

The server connects but there are no tools. What now?

Check the tool count in /mcp. If it is zero, the server usually needs an environment variable; add it with env or --env. If the count is nonzero but Claude cannot use a tool, check whether a permission rule denies mcp__<server>__*, and whether the tool's full name is longer than 128 characters.

Can claude -p use a server that needs OAuth?

claude -p has no /mcp panel and cannot run the OAuth flow. Sign in first in an interactive session with /mcp or claude mcp login <name>, then run claude -p.

Why does the first npx launch time out?

The first run downloads the package and may exceed the 30-second startup timeout. Run the configured command once in a terminal to finish the download, or raise the limit with MCP_TIMEOUT=60000 claude.

Order of checks

Put the steps in a sequence: read the status and Issue: line from claude mcp list and claude mcp get <name> to learn whether this is a connection failure, pending approval, missing authentication, or a connected server with no tools; confirm Claude Code reads the config file you edited; run the server command directly to rule out the runtime and path; then check the transport, permissions, timeouts, environment variables, authentication, ports, and proxy. Each step has an observable output. Change one thing, re-run the same check, and the cause usually narrows quickly.

Sources