Claude Code Tool Not Showing Up: 7 Fixes That Work

You added an MCP server to your Claude Code config, restarted the session, and... nothing. No tools in the sidebar, no tool calls when you ask for them, no indication that anything connected at all.

This is the most common support issue in the MCP ecosystem. The good news: it's almost always one of a handful of causes, and every one of them is fixable in under five minutes. This guide walks through the seven fixes that resolve claude code mcp tools missing in the vast majority of cases, ordered from most common to least.

Common Reasons Tools Don't Appear in Claude Code

Claude Code discovers MCP tools at session startup. It reads your settings JSON, spawns each configured server process, performs a handshake, and registers the tools the server advertises. If any step in that chain fails, tools silently don't appear.

The failure is silent by default — Claude Code doesn't throw a visible error when an MCP server fails to connect. This is by design (you don't want error popups for optional tools), but it makes debugging harder.

The causes fall into five categories:

1. Config errors — Malformed JSON, wrong file path, typos in server names
2. Process failures — The server binary crashes, isn't found, or exits immediately
3. Environment issues — Missing API keys, wrong variable names, shell not sourced
4. Permission problems — npx can't write to cache, file permissions block execution
5. Transport failures — stdio pipe breaks, HTTP connection refused, timeout

Let's fix each one.

Fix 1: Verify Your MCP Server JSON Configuration

This is the cause roughly half the time. A single misplaced comma in your settings JSON silently breaks every MCP server in the file — not just the one with the error.

Validate the JSON

cat ~/.claude/settings.json | python3 -m json.tool

If this prints formatted JSON, the syntax is valid. If it prints an error, it tells you exactly which line has the problem.

Common JSON mistakes

Trailing comma after the last server entry:

{
  "mcpServers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": { "TAVILY_API_KEY": "tvly-xxx" }
    },  // ← This comma breaks everything
  }
}

Missing comma between server entries:

{
  "mcpServers": {
    "tavily": { ... }   // ← Missing comma here
    "apify": { ... }
  }
}

Wrong nesting level — servers must be inside mcpServers, not at root level.

Check the file location

Claude Code reads from two locations:

• User-level: ~/.claude/settings.json
• Project-level: .claude/settings.json (relative to your project root)

If you edited one but Claude Code is reading the other, your changes won't take effect. Check both. For a known-working config example, see our Tavily MCP server setup guide.

Fix 2: Check Server Process and Startup Logs

The JSON is valid, but the server process itself might be failing. Test it outside Claude Code:

npx -y tavily-mcp@latest

Replace tavily-mcp@latest with whatever package your config specifies. You should see the server start and wait for input (stdio mode) or bind to a port (HTTP mode).

What failures look like

Package not found:

npm ERR! 404 Not Found - GET https://registry.npmjs.org/@nonexistent/mcp-server

→ Check the package name. Typos here are common — tavily-mcp vs @tavily/mcp-server vs tavily-mcp-server.

Immediate exit with no output: → Usually means the server hit an error during initialization. Run with DEBUG=* or check if the package has a --verbose flag.

Node.js version error:

SyntaxError: Unexpected token '?.'

→ The server requires a newer Node.js version. Check with node --version — most MCP servers need v18+.

For deeper startup crash diagnosis, see our guide on MCP server crashes on startup.

Fix 3: Resolve Environment Variable and API Key Issues

Most MCP servers need an API key passed via environment variables. If the key is missing, wrong, or not reaching the server process, the server may start but fail during the handshake — which means no tools registered.

Test the variable exists

echo $TAVILY_API_KEY

If this prints nothing, the variable isn't set in your current shell. Common reasons:

• You added it to .bashrc but you're running zsh (needs .zshrc)
• You added it to .zshrc but didn't source it yet
• You set it in a different terminal session

Hard-code temporarily to isolate

Replace the ${VARIABLE} reference with the actual key in your settings JSON:

"env": { "TAVILY_API_KEY": "tvly-your-actual-key" }

If tools appear after this change, the problem is environment variable resolution, not the server itself. Fix the variable, then switch back to the reference.

Verify the key is valid

An expired, revoked, or incorrectly copied API key will cause the server to fail authentication during startup. Log into the tool's dashboard and confirm the key is active. Copy-paste it fresh — invisible characters from password managers or Slack messages cause silent failures surprisingly often.

Fix 4: Handle Permission and Path Problems

npx cache permissions

npx caches packages in ~/.npm/_npx. If this directory has wrong permissions (common after running npm with sudo), the server can't install:

ls -la ~/.npm/_npx

Fix with:

sudo chown -R $(whoami) ~/.npm

PATH issues

Claude Code inherits the PATH from its parent process. If you installed Node.js via nvm, the PATH in Claude Code's context might not include the nvm-managed binary:

which npx
# Should return something like: /home/user/.nvm/versions/node/v22.x.x/bin/npx

If which npx returns nothing in your shell, Claude Code won't find it either. Ensure your shell profile exports the correct PATH before Claude Code launches.

File system permissions

On macOS, the first time Claude Code tries to run an MCP server, you may get a Gatekeeper prompt that blocks execution in the background. Run the npx command manually in Terminal first to trigger and approve the prompt.

Fix 5: Debug Transport and Connection Failures

MCP servers communicate via two transport types: stdio (default) and streamable HTTP. Most config-based servers use stdio — the server runs as a child process and communicates through standard input/output pipes.

stdio failures

If the server starts but tools still don't appear, the stdio handshake may be failing. Common causes:

• The server prints non-JSON to stdout — Some packages print a "Server started!" message that breaks the JSON-RPC protocol. Check if the server has a --quiet or --silent flag.
• Buffering issues — On some systems, stdout buffering delays the initial handshake past Claude Code's timeout. Setting NODE_OPTIONS="--max-old-space-size=4096" in the env block sometimes resolves this indirectly.

HTTP failures

For servers using HTTP transport, check that the port isn't already in use:

lsof -i :3000

And that the server is binding to the correct interface (localhost vs 0.0.0.0). For more on transport-specific issues, see our broken pipe troubleshooting guide.

When to Reinstall or Switch MCP Server Versions

If all five fixes above don't resolve the issue, the problem may be the server package itself.

Clear the npx cache and reinstall

rm -rf ~/.npm/_npx
npx -y tavily-mcp@latest

This forces a fresh download instead of using a potentially corrupted cached version.

Pin a specific version

The @latest tag means you get whatever version was most recently published. If a recent release introduced a bug:

"args": ["-y", "tavily-mcp@0.3.2"]

Pin to the last version that worked. Check the package's npm page or GitHub releases for version history.

Try an alternative server

Many tools have multiple MCP server implementations. If the official one doesn't work, search for alternatives. For example, Tavily has both the official tavily-mcp package and community implementations. The Apify MCP server tutorial walks through an alternative configuration pattern that works when the default setup fails.

The nuclear option

If nothing works with a specific server, test with a known-good minimal server to confirm Claude Code's MCP integration itself is working:

{
  "mcpServers": {
    "test": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"]
    }
  }
}

This test server requires no API key and exposes sample tools. If these tools appear, Claude Code is fine — the problem is specific to the server you're trying to configure.

Frequently Asked Questions

Why don't my MCP tools show up in Claude Code?

The most common cause is malformed JSON in your settings file — a single syntax error silently breaks all MCP server connections. Validate with cat ~/.claude/settings.json | python3 -m json.tool. Other frequent causes: missing or invalid API keys, the server package not being found by npx, Node.js version too old (need v18+), or editing the wrong settings file (user-level vs project-level). Claude Code doesn't display errors when MCP servers fail to connect, so you need to test each server manually outside Claude Code to identify the failure.

How do I check if an MCP server is actually running in Claude Code?

Claude Code doesn't have a built-in MCP server status panel. The best diagnostic method is testing the server independently: run the same npx command from your config directly in your terminal. If it starts without errors, the server binary works. Then check your settings JSON for syntax issues. You can also ask Claude Code directly: "What MCP tools do you have available?" — if the server connected successfully, its tools will appear in the response.

Do I need to restart Claude Code after changing MCP server config?

Yes. Claude Code connects to MCP servers at session startup and does not monitor the settings file for changes. After editing ~/.claude/settings.json or .claude/settings.json, you must start a new Claude Code session for changes to take effect. Closing and reopening the terminal window, or running claude again, starts a fresh session that reads the updated config.

Can too many MCP servers cause tools to not load?

Having many MCP servers configured doesn't prevent tools from loading, but it can cause timeouts. Each server is spawned and handshaked during startup. If you have 10+ servers and some are slow to initialize, Claude Code may time out waiting for all of them. The servers that respond in time will work; the slow ones silently drop. If you suspect this, temporarily reduce to 2-3 servers and add them back one at a time to identify which one stalls.

My API key is correct but the MCP server still doesn't connect — what now?

Verify the environment variable is actually reaching the server process. Hard-code the key directly in the JSON config (temporarily) to rule out variable resolution issues. If that works, the problem is your shell environment — the variable exists in your terminal but isn't being inherited by Claude Code's spawned process. Also check that the key prefix is correct (Tavily keys start with tvly-, Apify tokens start with apify_api_). Finally, confirm the key hasn't been revoked or rate-limited by logging into the service's dashboard.