Claude Code MCP server not connecting, or its tools not showing: the fixes

Start with claude mcp list

Run claude mcp list from the project folder, or /mcp inside a session. Each server shows a status, and the status points at the fix:

The server is missing: check the scope

Local scope is the default for claude mcp add. A local server loads only in the folder where you added it, so it disappears when you open another repo. For a server you want in every project, add it with --scope user:

claude mcp add --transport http --scope user <name> <url>

• .mcp.json goes at the repository root with servers under an mcpServers key. A file inside .claude/, or a top-level servers key copied from VS Code's mcp.json, never loads.
• settings.json doesn't read an mcpServers key. Use .mcp.json or claude mcp add.
• The same name in two scopes with different URLs shows a warning in claude mcp list. Claude Code uses the highest-precedence definition whole, without merging fields, so remove the extra one with claude mcp remove <name> --scope <scope>.
• A cloned repo can't approve its own servers: approvals committed in its .claude/settings.json are ignored until you trust the folder.

The server fails to start

• Relative paths in command or args resolve against the folder you launched Claude Code from, not the folder holding .mcp.json. Use absolute paths for local scripts; npx and uvx on your PATH work as they are.
• Variables the server needs belong in its env block. A ${VAR} reference that isn't set shows a Missing environment variable warning and reaches the server unexpanded.
• A pasted key with a trailing newline shows a hidden whitespace warning naming the field, such as headers.Authorization. Claude Code doesn't trim it, so edit the value.
• A slow server can hit the startup timeout. MCP_TIMEOUT sets it in milliseconds (30000 by default): MCP_TIMEOUT=60000 claude.
• After a fix, choose Reconnect on the server in /mcp, or run /mcp reconnect all (Claude Code v2.1.284 or later) to retry every failed server.

Connected, but no tools

A server that shows Connected with zero tools started fine but returned no tool list. The /mcp panel shows each server's tool count and flags servers that advertise tools but expose none. Choose Reconnect in /mcp. If the count stays at zero, start Claude Code with claude --debug=mcp and read the server's stderr in the log at ~/.claude/debug/<session-id>.txt.

• Run /context to see whether any MCP tools are in the session at all. They have their own line in the breakdown.
• A subagent whose definition has a tools list gets only the MCP tools it names. mcp__<server>__* gives it all of one server's tools.
• A remote server that drops mid-session gets five reconnect attempts. After that Claude Code shows MCP server "<name>" disconnected; reconnect from /mcp.
• Right after a resume, a call to a tool whose server is still connecting can fail with No such tool available. Calls work once the server is up.

Taskhold-specific checks

Taskhold is a remote server at https://taskhold.com/api/mcp. Add it with --transport http, which is Streamable HTTP. When the taskhold tools don't appear, check these in order:

1. claude mcp list shows taskhold. If not, add it again with --scope user, or paste a fresh setup URL from Settings and say "set this up".
2. The header is Authorization: Bearer followed by a key that starts with atd_sk_. A 401 names the problem: missing_key, bad_header, not_a_taskhold_key or unknown_key.
3. Added without a key? Run /mcp, pick taskhold and choose Authenticate to sign in through the browser.
4. A 402 means the key works but the trial ended or the plan was canceled. Restarting the plan fixes it with no config change.
5. Settings in Taskhold shows Connected once the first call arrives. Ask Claude to call taskhold_list to test; in Claude Code the tools are named mcp__taskhold__*.

Once the tools load, every task the agent starts, its steps and its questions show on the live board. Setup for other clients: Cursor, Codex, VS Code and Gemini CLI. Subagents and their tools are covered in tracking Claude Code subagents.