Troubleshooting and Production Patterns

Reading the failure signals

MCP connection problems surface in two places: claude mcp list in your shell, and the /mcp panel inside a session. Both show status indicators. The indicators point to different root causes and require different responses — recognizing the right pattern cuts the time to resolution significantly.

"No MCP servers configured"

This message in the /mcp panel means Claude Code found no servers for the current directory. The two most common causes:

Wrong project directory: Local-scoped servers are tied to the exact directory or git repository root where you added them. If you start Claude Code from a different directory, those servers are not active. Re-add the server from the correct project, or add it with --scope user to make it available everywhere.

Configuration file at the wrong path: Claude Code reads two specific files — ~/.claude.json for local and user scope, and <project>/.mcp.json for project scope. It does not read ~/.claude/.mcp.json, ~/.claude/mcp.json, or any other location. If you edited a file at a non-standard path, the servers will not appear.

Diagnosing HTTP connection failures

For "Failed to connect" or "Connection error" on an HTTP server, test reachability directly:

curl -I https://mcp.sentry.dev/mcp

Read the response to identify the problem:

• 404 or 405: The server is up but the path is wrong. Many MCP endpoints only accept POST requests, so 404/405 on a HEAD or GET request still confirms reachability. Compare the URL in your configuration to the server's documented endpoint.
• 401 or 403: The server is up but needs authentication. Use the OAuth flow in /mcp or pass a token with --header.
• No response / connection refused: The server is not reachable from your machine. Check the URL and your network.

Starting from v2.1.191, when an HTTP server returns 404, Claude Code shows the message "MCP endpoint not found at <url>" with the exact URL it tried — making it easy to spot a path mismatch.

Diagnosing stdio connection failures

For stdio servers, run the server command directly in your terminal:

npx -y @playwright/mcp@latest

Two outcomes tell you what is wrong:

• The command starts and waits for input: The server itself works. The problem is in your Claude Code configuration. Run claude mcp get <name> and compare the command shown there to what you just ran. A mismatch usually means you omitted the -- separator when adding the server, causing Claude to parse the server command as its own flags.
• The command errors: The error message identifies the missing piece — Node.js not installed, a missing package, insufficient permissions.

Startup timeouts and slow local servers

The default MCP startup timeout is 30 seconds. stdio servers whose first run downloads a package via npx can exceed this. Increase the limit with MCP_TIMEOUT (in milliseconds) before launching:

MCP_TIMEOUT=60000 claude

For tools that take a long time to produce results — running test suites, generating reports, querying large datasets — the idle timeout terminates the call if the server goes silent. The default is 5 minutes for HTTP/SSE/WebSocket and 30 minutes for stdio. Adjust with CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT in milliseconds, or set it to 0 to disable the check:

CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=0 claude

.mcp.json changes that do not take effect

Claude Code reads .mcp.json at session start. Edits made during a running session require a session restart to apply. If servers still do not appear after restarting, open /mcp and look for a parse warning — Claude Code skips malformed entries and shows the offending field in the panel.

If a project-scope server stays at "Pending approval" even after you approved it, check whether the workspace is trusted. Approvals from project settings (.claude/settings.json) are not applied in untrusted workspaces. Either run claude interactively and accept the trust dialog, or add the approval to your user settings instead. To reset all approval choices and start fresh:

claude mcp reset-project-choices

Production patterns for CI and unattended use

Three patterns matter when running Claude Code non-interactively with MCP servers.

Pre-authenticate before -p sessions: In non-interactive mode (claude -p), the OAuth flow cannot run. Run claude mcp login <name> for each server that needs OAuth before starting any -p pipeline. Servers that still need sign-in are flagged as unavailable in tool search — Claude names them specifically rather than silently failing, which makes debugging straightforward.

Write permission rules for MCP tools: Restrict which MCP tools Claude can call without approval using deny or allow rules. MCP tool names follow the pattern mcp__servername__toolname, so a rule like mcp__github__push_commits targets that specific action. Use these rules to prevent unintended writes in automated pipelines.

Proxy-compatible tool search settings: If your CI environment routes Claude Code through an API proxy that does not support tool_reference blocks, tool search will fail silently. Set ENABLE_TOOL_SEARCH=false to load all MCP tools upfront, or confirm with your proxy vendor that tool_reference forwarding is supported before enabling deferral.