Claude Code MCP Server Not Loading: Troubleshooting Guide

When a Claude Code MCP server is not loading, start with its reported state instead of rewriting the configuration blindly:

claude mcp list
claude mcp get SERVER_NAME

Inside an interactive Claude Code session, run:

/mcp

These checks separate the most common causes: the server is not configured, it is waiting for project approval, authentication is missing, it is disabled, or Claude Code attempted the connection and received a specific failure.

Read the MCP server status first

claude mcp add printing Added ... only confirms that Claude Code wrote the configuration. It does not prove the command starts, the URL responds, or the credentials work.

The status normally points to the next action:

Status	Meaning	Next action
Connected	Claude Code loaded the server successfully	Test one low-risk tool call
Needs authentication	The server requires sign-in or credentials	Open /mcp or run the supported login flow
Pending approval	A project server is waiting for workspace trust or approval	Start Claude interactively in the project and review it
Disabled for this project	Project settings disabled the server	Re-enable it from /mcp if authorized
Rejected	A settings rule rejects the project server	Review the effective settings with the administrator
Failed to connect	Claude Code attempted a connection and it failed	Inspect claude mcp get SERVER_NAME for the issue detail
Not configured	A remote entry has no usable URL	Add the correct endpoint

Anthropic's Claude Code MCP reference documents these states and the associated approval behavior.

1. Confirm the server exists in the expected scope

Run:

claude mcp list

Then inspect the server:

claude mcp get my-server

Claude Code supports local, project, and user scopes. A definition saved in one project will not necessarily appear in another. The same name in more than one scope can also create a conflict, especially when the endpoints differ.

If you find duplicate definitions, keep the intended one and remove the other explicitly:

claude mcp remove my-server --scope local

Use the correct scope for your installation. Do not remove a team-managed definition without understanding why it exists.

2. Approve project-scoped MCP servers

A server committed in .mcp.json is code-adjacent configuration with real capabilities. Claude Code therefore requires workspace trust and project-server approval.

If the status says Pending approval, launch Claude Code interactively from the repository:

claude

Review the workspace trust prompt and the server details before approving. A cloned repository cannot approve its own MCP servers through committed project settings. This prevents an untrusted repository from silently granting itself access to tools or data.

If your organization manages approvals centrally, follow its policy rather than adding a local bypass.

3. Match the transport to the server

An incorrect transport is one of the easiest ways to create a configuration that looks plausible but never connects.

Remote HTTP server

For a normal remote HTTPS endpoint:

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

Local stdio server

For a process Claude Code launches locally, place the complete command after --:

claude mcp add my-server -- npx -y @example/mcp-server

The separator matters. It prevents flags intended for npx, uvx, or another local command from being parsed as Claude Code flags.

SSE or WebSocket

Use SSE only when the provider explicitly supplies an SSE endpoint. Use an explicit WebSocket configuration when the server needs a persistent push connection. Do not label a remote URL as stdio or omit type from a URL-based JSON entry; Claude Code can otherwise interpret the entry as a local process definition.

The FixTools MCP Config Generator creates a project configuration or CLI command for the selected transport and reduces hand-written JSON errors.

4. Fix authentication failures

Open /mcp and select the server to complete an OAuth flow when supported. Current Claude Code versions also support command-line login for configured OAuth servers:

claude mcp login my-server

For header-based authentication, confirm:

• The environment variable is set in the same shell that launches Claude Code.
• The header name and scheme match the server documentation.
• The token has not expired or been revoked.
• No leading or trailing whitespace was copied with the secret.
• A proxy is not stripping the authorization header.

Do not paste real tokens into screenshots, issue reports, or committed .mcp.json files.

5. Check missing variables and hidden whitespace

Claude Code warns when a referenced environment variable is missing and when configuration fields contain hidden leading or trailing whitespace.

Inspect the output of:

claude mcp list

Pay attention to warnings naming fields such as headers.Authorization, url, command, args, or environment-variable keys. Claude Code does not automatically trim these values; edit the source configuration.

A missing ${VARIABLE} may remain unexpanded in the loaded configuration. Set the variable before launching Claude Code or use a documented default only when that default is safe.

6. Diagnose Failed to connect

For a Failed to connect state, run:

claude mcp get my-server

Current Claude Code versions show an Issue: line with an HTTP status, transport error code, or sanitized server response when it is safe to display. Interpret common failures as follows:

• 401 or 403: credentials are missing, invalid, expired, or lack permission.
• 404: the server URL or MCP path is wrong.
• Connection refused: the local process or remote service is not listening at the configured address.
• Command not found: the stdio executable is unavailable in the environment that launched Claude Code.
• TLS or certificate error: the certificate chain or inspecting proxy needs to be fixed; do not disable verification as a shortcut.
• Timeout: the server started too slowly, the network is blocked, or the tool exceeded its execution budget.

Test a remote server's health endpoint or a local server's launch command outside Claude Code only when the provider documents a safe method. A stdio MCP server may appear to hang when run directly because it is waiting for a client over standard input; silence alone does not prove it is broken.

7. Adjust timeouts only after finding the slow layer

For slow startup, set the MCP startup timeout when launching Claude Code:

MCP_TIMEOUT=10000 claude

That example allows ten seconds. Increasing the value may help a legitimate server that needs more startup time, but it will not repair a wrong command, blocked port, invalid URL, or failed authentication.

Tool execution timeout is separate. A server entry can use a timeout value in milliseconds for individual tool calls. Keep timeouts bounded and investigate why a tool needs an unusually large window.

8. Check disabled and reserved names

If the server is disabled for the project, re-enable it from /mcp only if you are authorized to use it. If settings explicitly reject the server, inspect the effective local, user, project, and managed settings.

Claude Code also reserves names used by built-in servers. Rename a custom entry when the CLI reports a reserved-name conflict. Use a short identifier containing letters, numbers, hyphens, or underscores.

9. Validate the configuration without exposing secrets

Before sharing a broken configuration:

1. Replace tokens, passwords, cookies, private hostnames, and account identifiers.
2. Preserve structural details such as type, command, args, url, env, and header names.
3. Include the sanitized status and issue code.
4. State the Claude Code version and operating system.
5. Explain whether the server is local stdio or remote HTTP/SSE/WebSocket.

A redacted but structurally accurate report is more useful than a screenshot with the important fields hidden or a complete file that leaks credentials.

A reliable MCP recovery sequence

Use this order to avoid random changes:

1. Run claude mcp list.
2. Run claude mcp get SERVER_NAME.
3. Resolve pending trust or approval.
4. Confirm scope and remove unintended duplicate definitions.
5. Confirm the transport and endpoint or launch command.
6. Complete authentication.
7. Fix missing variables or whitespace warnings.
8. Test connectivity and adjust timeouts only when evidence points to them.
9. Reopen /mcp and verify the server state before calling a tool.

For configuration help, generate a clean starting point with the MCP Config Generator. For architecture and security context, read the Claude MCP Guide and Claude troubleshooting hub.

Sources and verification

This guide was verified on September 3, 2026 against Anthropic's Claude Code MCP reference, Claude Code troubleshooting documentation, and the Model Context Protocol introduction.