An MCP server can appear as Connected in claude mcp list while its tools remain unavailable in a Claude Code session. Connected confirms that Claude Code reached the server. It does not prove that the server returned a valid, non-empty tool list.
Start by separating three symptoms:
/mcpshows zero tools for the server./mcpshows tools, but Claude does not select them.- Claude finds a tool but cannot call it.
Zero tools points to the server response. Tools that exist but are ignored point to Tool Search or an unclear request. A tool that is found but blocked points to permissions, not the connection.
Check the tool count in /mcp
Run this inside Claude Code:
/mcpThe panel shows each server’s status and available tools. Check the tool count before changing the configuration or rewriting the prompt.
/mcp state |
What it means | Check next |
|---|---|---|
| Connection failed | Process, network, or authentication issue | Command, URL, auth, and logs |
| Connected, zero tools | Connection works but no tools arrived | Reconnect and debug logs |
| Connected, one or more | Claude Code received the tool list | Tool Search and permissions |
| Pending | Connection or reconnection in progress | Wait, then check again |
Changing the prompt will not fix a server that exposes zero tools. Claude cannot call a tool it never received.
I would not rebuild .mcp.json until this check is done. A zero count and a nonzero count lead to different fixes.
If the count is zero, inspect the server response
Reconnect the server from /mcp. If the count remains zero, start Claude Code with MCP debugging enabled:
claude --debug mcpLook for these failures:
- the server starts and exits immediately
- the initialization response does not advertise the
toolscapability tools/listfails or returns an empty list- required environment variables are missing in the server process
- a stdio server writes ordinary logs to standard output
The MCP stdio transport reserves standard output for JSON-RPC messages. Diagnostic logging belongs on standard error. A console.log mixed into protocol output can break initialization or tool-list parsing even when the process itself starts.
Confirm project-server approval
Servers declared in a project’s .mcp.json require approval when first used. Closing or declining the prompt can leave the configuration present but inactive for that user.
Select the server in /mcp and check its approval state. A committed .mcp.json shares configuration with the team; it does not share each developer’s trust decision.
These commands show the registered scope and resolved configuration:
claude mcp list
claude mcp get <server-name>Check relative paths and the execution environment
Relative paths in .mcp.json can resolve from the directory where Claude Code was launched rather than from the configuration file’s directory. For project-local executables, use ${CLAUDE_PROJECT_DIR} explicitly.
{
"mcpServers": {
"local-tools": {
"command": "node",
"args": ["${CLAUDE_PROJECT_DIR}/tools/mcp-server.js"]
}
}
}An unresolved executable often produces a spawn ... ENOENT error. If the command works in an interactive terminal but not in Claude Code, compare PATH and the environment variables passed to the child process.
When tools exist but Claude does not use them
If /mcp shows one or more tools, the server has already passed tool discovery. The remaining question is whether Claude can find the right tool for the current request.
Claude Code can defer MCP tool schemas and search for relevant tools when needed. This keeps a large MCP setup from filling the context window at session start. Make the task and server explicit when testing selection:
Use the GitHub MCP server to list open issues in this repository.
Find the required MCP tool before answering.If the problem started after enabling or disabling a plugin, reload the current session’s plugins:
/reload-pluginsModel support, API proxies, and Tool Search settings can affect this behavior. Check the current Claude Code MCP documentation rather than assuming every environment uses the same loading strategy.
When Claude finds the tool but cannot call it
Once Claude names the tool or asks for call approval, tool discovery is working. Check the permission rule and the user’s response instead of recreating the connection.
MCP tools commonly use names shaped like this:
mcp__<server-name>__<tool-name>A permission rule with the wrong server or tool name can block the call. Compare the displayed tool name with the allow, ask, or deny rule exactly.
Debug it in this order
Connected is only the first checkpoint. Use the tool count to avoid debugging the wrong layer:
- Zero tools: reconnect, then inspect
claude --debug mcpand the server’stools/listresponse. - Tools exist but are ignored: test Tool Search with a concrete server-specific request.
- Tool is selected but blocked: inspect the resolved tool name and permission policy.