Claude Code MCP Server Not Loading? Check Config Scope, Restart, and Tool Names

2026-06-21

claude-codemcpconfigurationdebuggingstdio

When an MCP server does not appear in Claude Code, it is easy to start debugging the server implementation immediately.

Often the problem is simpler: the config was edited in the wrong place, the app was not restarted, or you are looking for the wrong tool name.

This checklist focuses on local stdio MCP servers.

1. Confirm the config scope

Claude Code can load MCP servers from different scopes depending on how you register them.

Common options include:

claude mcp add my-server -- node /absolute/path/to/server.js

or a JSON configuration file.

The important point is to verify the config that Claude Code actually reads. Do not assume Claude Desktop, Claude Code, project-local config, and user-level config all share the same file.

If you changed a config file and nothing happened, first confirm that file is in the active scope.

2. Use absolute paths

For stdio servers, use explicit absolute paths in the command or args:

{
  "mcpServers": {
    "knowledge": {
      "command": "node",
      "args": ["C:/path/to/mcp-server/dist/index.js"],
      "env": {
        "CONTENT_DIR": "C:/path/to/content"
      }
    }
  }
}

Relative paths may work in one shell and fail in another because the working directory is not what you expect.

3. Restart after config changes

MCP configuration changes are not always hot-reloaded.

If you add a server, change a command, change args, or change environment variables, restart the Claude Code session before judging the result.

For a stdio server, remember that the client launches the server process. If the client never restarted it, your new command may not be running.

4. Check for tool names, not just server names

MCP tools may show up with generated names such as:

mcp__knowledge__list_articles
mcp__knowledge__get_article

If the server name is knowledge, the visible callable tools may include that namespace. Search for the tool prefix, not only the server display name.

5. Test the server outside Claude Code

Before blaming Claude Code, run the server directly:

node /absolute/path/to/mcp-server/dist/index.js

For a stdio server, it may appear to hang because it is waiting for JSON-RPC input. That is normal. Startup diagnostics should go to stderr, not stdout.

For a stronger test, use an MCP SDK client or inspector to call listTools.

6. Keep stdout clean

If the server uses stdio transport, avoid console.log() for diagnostics. stdout is the protocol channel. Use stderr:

process.stderr.write("MCP server running\n");

For details, see MCP stdio Server Logging: Keep Logs on stderr, Not stdout.

Summary

When a Claude Code MCP server does not load, check the boring parts first:

correct config scope
absolute command paths
restart after config changes
actual tool names
standalone server execution
stderr logging for diagnostics

Only after those pass should you spend time debugging the server logic.