Claude Code MCP Not Connecting? Diagnose Config, Auth and Startup Errors

When an MCP server fails in Claude Code, deleting the configuration and starting again is usually a poor first move. You lose the evidence that could explain the failure, and a working server in another project may disappear along with it. Start by identifying whether Claude Code found the server, connected to it, discovered its tools and completed the operation you asked for.

This guide covers the Claude Code CLI, not the separate Claude Desktop chat configuration. The commands and behavior were checked against current documentation on November 6, 2026. They have not been tested against a live Claude Code account for this article.

Start from the project where the failure happens

Open a terminal in that project and collect a small diagnostic record before editing anything:

claude --version
claude mcp list
claude mcp get your-server-name
claude doctor

Replace your-server-name with the configured name. The CLI reference documents version reporting and claude doctor, which prints installation and settings diagnostics without opening a session. Inside an existing session, use /mcp to inspect the server.

Write down the operating system, launch directory, server name, transport and exact error. Keep this record private until you have removed tokens, authorization headers, internal URLs and sensitive paths. A screenshot of an entire terminal is rarely the smallest useful bug report.

Match the status to the next check

The official MCP quickstart distinguishes these states:

What you see	Next check
No configured server	Project directory, scope and config parsing
Authentication required	The server's sign-in method
Connection failure	Error details, endpoint or launch command
Connected, but tool discovery failed	Tool-list error, then a targeted reconnect
Pending approval or disabled	Current project's approval and enablement
Blocked by managed policy	Administrator's policy decision

Treat the status as a starting point rather than a complete diagnosis. If a server appears in the list but a request fails, adding a second definition under a different name is unlikely to explain what happened. Keep one known configuration and investigate the next failing step.

A missing server is often a scope problem

The MCP reference maps CLI registrations to these locations:

Scope	Location	Where it applies
Local	Project entry in ~/.claude.json	You, in that project
Project	Project-root .mcp.json	That project's users
User	Top-level mcpServers in ~/.claude.json	You, across projects

Local is the default. CLAUDE_CONFIG_DIR changes the configuration directory, so inspect the location your installation actually uses rather than creating another guessed filename.

Imagine you added a server while working in billing-service, then opened marketing-site and found no server. Before concluding that registration failed, check whether the original entry was local to billing-service. Widening it to user scope may be appropriate, but that is a decision about where the integration should be available, not a necessary troubleshooting step.

For a project file, preserve a private backup before editing and check that the JSON parses. Then inspect Claude Code's own warnings, because valid JSON can still contain an invalid server definition. Avoid copying your entire personal configuration into the repository to make one server appear.

Separate remote authentication from a broken endpoint

For an HTTP server, compare the complete configured URL with the vendor's setup instructions, including its path. A working homepage only establishes that the website responds; it does not demonstrate that an MCP request reaches the intended endpoint.

For OAuth servers, use the configured server's sign-in flow. The CLI supports claude mcp login your-server-name; /mcp offers the interactive route. Review the account and requested access before approving it, especially when the server can change records or send messages.

If the error names a rejected token, check its intended service, expiry and permissions privately. Don't substitute your Claude API key for an unrelated service's credential just because both are called API keys.

The MCP reference also documents environment-variable expansion in server configuration, including warnings for missing variables and special handling of protected credential names. Confirm that the process launching Claude Code receives the intended variable without printing its value. Increasing a timeout will not repair an absent credential.

For a local server, inspect the command that actually starts

A stdio integration runs a process, so check the executable, arguments, dependencies and environment before investigating the remote service that process eventually calls. Only run a server command you trust; a troubleshooting session is not a reason to execute an unfamiliar package from a copied forum answer.

Claude Code's registration syntax uses -- between its own options and the server command. Compare the saved definition with the vendor's documented command rather than rewriting both the command and the environment at once.

The configuration-debugging guide notes that relative paths resolve from the directory where Claude Code was launched, not from the .mcp.json location. An explicit path can make a useful temporary test: if that fixes startup, you have isolated path resolution without reinstalling the server.

When the trusted command exits immediately, inspect its error output. When it remains running, that alone does not prove it speaks MCP successfully; continue to discovery and a real tool call.

Connected but no usable tools needs a different investigation

The configuration-debugging guide recommends reconnecting a server that connects but returns no tools, then using claude --debug=mcp if the problem persists. Inspect the relevant debug log locally, and share only a redacted excerpt that captures the failure.

Keep the scope of the conclusion narrow. If initialization succeeds but listing tools fails, changing every credential and network setting at once makes the result harder to interpret. Capture the discovery error, change one plausible cause, then repeat the same check.

A server blocked by organizational policy belongs with the administrator. Disabling TLS verification or bypassing tool permissions would change the security boundary while leaving the original problem unexplained.

Use a small, known connection as a control

If your organization allows it and you trust the destination, Anthropic's public documentation server provides a no-authentication check. Use a fresh terminal session in the same project so the comparison stays relevant. Registration changes local configuration and the test contacts Anthropic's documentation service; it is optional, not a prerequisite for troubleshooting your own server.

claude mcp add --scope local --transport http docs-check https://code.claude.com/docs/mcp
claude mcp get docs-check
claude

Choose another name if docs-check already exists. In the session, ask:

Use docs-check to find the documentation for MCP_TIMEOUT.

Inspect the actual tool invocation and result rather than accepting a plausible answer from model memory. Once finished, remove only the temporary entry:

claude mcp remove docs-check --scope local

If this HTTP control works while your target HTTP server fails, focus next on the target's URL, authentication and implementation. If a stdio server fails, a successful HTTP control does not clear its local dependencies or startup command. The comparison is useful precisely because it establishes something limited.

Change timeouts only after identifying which timer expired

The environment-variable reference separates MCP_TIMEOUT for startup from MCP_TOOL_TIMEOUT for tool execution, with a per-server timeout override in milliseconds. Idle and remote-request timers also matter, so identify the expired timer before extending a limit.

A longer startup allowance is reasonable when the process is healthy but genuinely slow to become ready. It is a poor substitute for investigating a missing executable, rejected token or incorrect endpoint. Record the old value, choose a bounded change and repeat the same operation so you can tell whether it helped.

Likewise, reconnect commands vary by version. /mcp reconnect all requires an interactive terminal session on v2.1.284 or later; for a single broken server, prefer its individual reconnect control so unrelated integrations remain outside the experiment.

Know when you have fixed it

I would call the connection restored only after the intended project loads the intended definition, the server exposes the expected tools, and one authorized operation returns a result you can inspect. Reopen a session from the original project to check that the fix survives the launch conditions that first failed.

If you need help from the server maintainer, send the CLI version, operating system, transport, scope, redacted error, failing step and one minimal reproduction. Include what changed between the failed and successful checks, but leave credentials and private tool results out of the report. That gives the maintainer a problem they can investigate rather than a pile of unrelated configuration changes.

I'm Paras, a technical writer working with AI and developer-tool teams.

I help turn integration failures and API edge cases into clear documentation developers can actually use.

Book a 30-minute call.