Claude Code — MCP server not loading, tools missing from session

Quick fix (TL;DR)

Real error messages you'll see

These are the exact strings returned by the Claude API service and its SDKs when this error occurs. Copy-paste-searching any of them should land on this page.

$ claude mcp list
No MCP servers configured for this project.

(but ~/.claude.json has "mcpServers": {...})

$ claude mcp list
my-postgres: ✓ connected

$ claude
> what tables are in my database?
(no tools called — Claude answers from parametric knowledge)

$ claude
⚠ New MCP servers found in .mcp.json:
   - my-analytics
   - my-postgres
Do you trust these servers? [y/N]

Reference

MCP config scopes in Claude Code (highest precedence first)

<code>claude mcp</code> CLI commands

Root causes, ranked by frequency

Based on developer reports across Claude API forums, GitHub issues, and Anthropic community during 2025–2026.

• 26%
  Server configured for Claude Desktop, not Claude Code. Claude Desktop reads ~/Library/Application Support/Claude/claude_desktop_config.json; Claude Code does not.
• 18%
  Project .mcp.json not yet trusted. First entry to the directory prompts for trust; declining leaves the servers unloaded silently.
• 14%
  Server loads but does not advertise expected tools. Connection succeeds, tools/list returns an empty array — server misconfiguration.
• 10%
  Wrong scope for the config. Added at user scope; project has its own .mcp.json that overrides.
• 8%
  Command path wrong or missing. Same PATH issue as Claude Desktop — commands added by hand often lack absolute paths.
• 7%
  Trust decisions cached but user changed scope. Trust choice was made under user scope; new project scope needs re-approval.
• 10%
  Environment variables not propagated. Server needs DATABASE_URL or an API key that lives in the user's shell, not in the MCP config.
• 7%
  Server crashes on startup. Silent — claude mcp list shows connected briefly then disconnects.

Fixes — copy-paste solutions

# Add a stdio server at PROJECT scope (checked into .mcp.json)
claude mcp add postgres \
  --scope project \
  -- /opt/homebrew/bin/uvx mcp-server-postgres \
     --connection-string "postgres://user:pass@localhost/mydb"

# Add a stdio server at USER scope (all projects, personal)
claude mcp add filesystem \
  --scope user \
  -- /opt/homebrew/bin/uvx mcp-server-filesystem /Users/me/projects

# Add an SSE remote server
claude mcp add company-tools \
  --scope project \
  --transport sse \
  https://mcp.internal.example.com/sse

# Add with a full JSON blob (env vars, args)
claude mcp add-json postgres '{
  "command": "/opt/homebrew/bin/uvx",
  "args": ["mcp-server-postgres"],
  "env": {"DATABASE_URL": "postgres://..."}
}' --scope project

# Verify
claude mcp list
# postgres: ✓ connected (project scope)
# filesystem: ✓ connected (user scope)

# Test each server's tools directly
claude mcp inspect postgres    # opens the Inspector for that server

# On first cd into a repo with .mcp.json:
$ cd my-repo
$ claude
⚠ New MCP servers found in .mcp.json:
   - postgres
   - github
Do you trust these servers? They will run with your file access. [y/N]

# If you answered "y" — trust is recorded, servers load on every future entry.
# If you answered "N" — servers stay unloaded silently until you re-prompt.

# Re-prompt for the current project:
claude mcp reset-project-choices
claude    # you will be asked again on next start

# Check current trust status
cat ~/.claude.json | jq '.projects."/absolute/path/to/my-repo".trustedMcpServers'

# 1) List loaded servers and their status
claude mcp list

# postgres: ✓ connected
# github: ✗ startup failed (see log)
# custom: ✓ connected (0 tools)   ← connected but useless

# 2) Read the per-server log
ls ~/.claude/logs/mcp/
# mcp-server-github-2026-07-30.log
tail -f ~/.claude/logs/mcp/mcp-server-github-*.log

# 3) Inspect a specific server (interactive)
claude mcp inspect github
# opens the MCP Inspector UI at localhost:5173

# 4) Run the server manually to see stderr directly
/opt/homebrew/bin/uvx mcp-server-github
# (typically errors are clearer here than through the client wrapper)

# 5) Enable verbose logging for the whole session
CLAUDE_MCP_LOG_LEVEL=debug claude

# 6) Confirm the server is advertising tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  /opt/homebrew/bin/uvx mcp-server-github

Prevention checklist

Ship these seven safeguards once and this error stops appearing in your logs.

• Configure MCP with claude mcp add; do not hand-edit config files.
• Use project scope (.mcp.json) for team-wide servers and check the file in.
• Use absolute command paths — never rely on the shell PATH inherited by the CLI.
• Verify with claude mcp list after every config change.
• For CI/headless runs, set CLAUDE_TRUST_ALL_MCP=1 only in disposable containers.
• When a server advertises no tools, run it through claude mcp inspect to confirm the manifest.
• Document required env vars in the .mcp.json comments so teammates set them before first run.

Frequently asked questions

Related errors & hubs