When an MCP server isn't working in Claude Code, first identify the stage: if the server is missing, check its configuration source and scope; if it fails to connect, check startup, network, or authentication; if it is Connected but has no tools, check discovery and permissions. A successful add means configuration was written. Connected does not prove a later business operation succeeded.
This guide is for developers who already have an MCP server and primarily use the terminal CLI. It follows the official Claude Code MCP documentation, checked November 13, 2026. Server and client versions and organization policies can change the statuses and controls available. The isolated test below covers configuration and failure status on an older CLI, not model calls, OAuth, or a real server.
Record the status and choose a branch
Run these commands in the same project directory where you launch Claude Code, replacing server-name with the server's name:
pwd
claude --version
claude mcp list
claude mcp get server-name
list and get can start a stdio server or attempt a remote connection, so confirm you trust the configuration and server first. Inside an interactive session, use /mcp to inspect server details, status, and tool count. Don't publish raw output, configuration, or logs: URLs, arguments, environment variables, and errors can contain credentials or internal addresses. Current documentation lists statuses including Connected, Needs authentication, and Failed to connect, as well as pending approval, disabled, and policy-blocked states. Labels can differ by version. Official status reference
| Observation | Next check | What it tells you |
|---|---|---|
Server absent or get cannot find it |
Directory, source, scope, approval, and policy | This alone doesn't establish a server failure |
| Needs authentication / Failed to connect | Authentication, process, or network, depending on transport | Configuration was found, but a usable connection was not established |
Connected, but expected tools missing from /mcp |
Tool count, discovery, permissions, and server exposure | Connection does not establish tool availability to the model |
| Tool visible but call fails | Specific tool error, authorization scope, and server response | Connection and discovery succeeded, but the business request may still fail |
Server missing: identify the configuration source
- Check directory and scope. The default local scope applies only to the project where the server was added. Project scope uses
.mcp.jsonin the project root; user scope works across projects. For duplicate names, local takes precedence over project, then user; the entire higher-priority entry is used, without merging fields. Inspect the expected entry and scope rather than deleting the configuration wholesale. Scopes and precedence - Check configuration parsing and the launch environment. Compare the
mcpServersJSON shape and transport type with the official format; a remote entry containing a URL needs the correcttype. Look for configuration warnings inlistand check that the environment launching Claude Code supplies the required variables, without printing their values. The documentation says an unset${VAR}without a default in.mcp.jsonnormally produces a warning and remains unexpanded; some credential variables in remote URLs and headers instead read as empty. Configuration warnings, environment expansion - Check project approval and disabled status. A server in a trusted project's
.mcp.jsonmay need review and approval in an interactiveclaudesession. Approve only after checking the command and source./mcpcan also show disabled servers. Organization-managed policy may block or hide a server; ask an administrator instead of bypassing it. Project approvals, managed configuration - Check the entry point. Manual configuration, plugins, and claude.ai connectors have different sources. For plugin servers, inspect
/pluginand/mcp; for claude.ai connectors, check the account connection and/mcp. The documentation says claude.ai connectors do not load when an API key or third-party provider is the active authentication method; use/statusto check. Terminal, VS Code, and JetBrains sessions fetch connectors through Claude Code, while desktop app local and SSH sessions receive them from the app. Connector conditions
One isolated local test: On November 13, 2026, we used Claude Code 2.1.87 on macOS with an empty HOME, an isolated configuration directory, and two temporary working directories. We added a local-scope server whose command pointed to a nonexistent program. add reported Added; get and list in the same directory reported Failed to connect; list in the other directory reported no configured servers. Each step ran once, without login, model calls, or external connections. This observation supports only the configuration and connection statuses for that version and synthetic input; it does not establish current UI or real-server behavior.
Found but failing to connect: narrow by transport
- Local stdio process: In
get, compare the executable and arguments against the server's own startup instructions. Separately check the actual launch directory and required environment variables. Confirm that the program exists and the current user can execute it. Avoid exposing secrets in logs. Check how relative paths in project configuration resolve from the launch directory and whether the process exits immediately. - Remote HTTP / SSE: Check the provider's MCP endpoint, network or proxy reachability, and any returned status code. If authentication is required, select the server in
/mcpand follow its authorization prompts. For authorization failures, check the account and provider's permission scope. Keep bearer tokens out of articles, tickets, and repositories. Remote authentication - Approval, disabled, or policy status: These are not network errors. Address the reported state first, and ask an administrator about enterprise policy. Current documentation also describes retries for transient first-connection failures over HTTP/SSE, but not the same first-connection retry for stdio; consult your version's
/mcpand reconnection reference.
Historical reports suggest useful comparisons, not proof that a current version has the same defect. In issue #16107, opened January 2, 2026, a user reported project-scoped connection failures on Linux from 2.0.71 while manual protocol initialization responded. The reporter later identified a Laravel Boost protocol version mismatch and said upgrading the server resolved it. Check both client and server versions; a handshake observation alone does not establish a client bug or justify copying an old downgrade suggestion.
Connected but tools unavailable: inspect discovery and calls
Open /mcp in the current session and select the server to inspect its tool count and names. Current documentation says the panel flags servers that advertise tool capability but expose none. A remote server may show cached and a previously discovered count: the list came from cache and connection happens on first use. Discovery cache requires 2.1.221 or later and depends on configuration or rollout; a cached count is not proof that a live call succeeded. Tool availability, status details
If the count is zero or the intended tool is missing, check in order:
- Whether the server exposes the expected tool to this account and connection. Consult its documentation or ask its maintainer to inspect the tool list. A successful handshake does not guarantee the expected tools were returned.
- The server source and disabled state in
/mcp, current session permission rules, and any organization connector-tool controls. In cloud sessions, a partial tool count can also reflect deny rules, name length, or server-side visibility. Official availability reference - Tool search can defer loading definitions, so their absence from the initial context does not alone mean tools are missing. A server still connecting can also produce
No such tool available. Wait for connection to finish, then check the tool by name. Tool search - If the server and tool are visible, choose a specific, explicitly read-only tool you are authorized to use and a nonsensitive test object. Ask Claude to call it and inspect the actual tool result—for example, read a test record you may access and verify the returned object. If no suitable read-only tool exists, stop at discovery rather than performing a write for the test. A model's claim that it called a tool is not sufficient; inspect the call and response.
Issue #88392, opened August 20, 2026, reported intermittent connected sessions with no tools in non-interactive use while another MCP client could list them; the reporter later said an upgrade to 2.1.239 resolved it. In issue #49019, opened April 16, 2026, a reporter described plugin servers showing Connected while their tools did not enter the session. These are reports from different environments, not proof of the cause of your problem. A comparison client should use the same identity, server, and permissions.
When an account connector is missing
If manually configured MCP servers work but a claude.ai connector is absent from /mcp, check the active authentication method in /status, the connector authorization on claude.ai, and whether your organization permits it. If necessary, inspect the collapsed unused-connectors list and duplicate-endpoint indications in /mcp. The documentation says some Anthropic-hosted connectors do not support local OAuth from Claude Code and must instead be connected on claude.ai. Official connector reference
For example, issue #77588, opened July 14, 2026, reported that account connectors did not initialize in a macOS CLI while manually configured servers worked. The reporter also observed a mismatch between the displayed version and the running executable. This is one historical report; for a similar symptom, record the actual entry point, version, and authentication method, then check current documentation or provide sanitized details to an administrator or maintainer.
If the problem is project instructions not loading rather than an unavailable MCP server or tool, see Claude Code CLAUDE.md troubleshooting.
If the problem remains, provide a minimal reproduction: client version and entry point, operating system, server source and transport, directory and scope, status and sanitized error, expected tool, and whether another client can see it. Remove tokens, cookies, internal URLs, and business data while retaining enough detail to distinguish connection failure from discovery failure.