# MCP Server Not Working in Claude Code?

> claude mcp list shows Failed to connect or Pending approval — the five checks that find the cause: scope, approval, the -- separator, env vars, timeouts.

- Canonical: https://guides-ai.pages.dev/guides/claude-code-mcp-troubleshooting/
- Plate 05.07 · Topic: MCP (https://guides-ai.pages.dev/topics/mcp/)
- Published: 06 Sept 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.pages.dev/

Most "MCP doesn't work" reports are one of five things. Start with the status line — it usually names the problem.

## 1. Read the status

```bash
claude mcp list
claude mcp get github
```

Lists every configured server with its health: `✔ Connected`, `! Needs authentication`, `✘ Failed to connect` (with the HTTP status or error after it), `⏸ Pending approval (run claude to approve)`, `✘ Rejected`, or `⊘ Disabled for this project`. Inside a session, `/mcp` shows the same panel and lets you toggle servers per project.

## 2. Wrong scope

A server added with the default **local** scope lives in `~/.claude.json` under the project path you ran the command in — it does not exist in other folders. `--scope project` writes `.mcp.json` in the repo (shared); `--scope user` makes it available everywhere:

```bash
claude mcp add --transport http --scope user context7 https://mcp.context7.com/mcp
```

If `claude mcp list` is empty in a new project, you added the server somewhere else.

## 3. Project servers wait for approval

Servers from a repo's `.mcp.json` are only loaded after you approve them in an interactive session (a trust dialog). If you clicked "no" once:

```bash
claude mcp reset-project-choices
```

Then run `claude` in the project and approve. A server listed in the `disabledMcpjsonServers` setting stays rejected until you remove it there.

## 4. The command line itself

For stdio servers, everything after `--` belongs to the server; without it Claude Code tries to parse the server's flags as its own:

```bash
claude mcp add --transport stdio myserver -- npx -y @example/server --port 8080
```

Two more classics: a JSON entry with a `url` but no `"type": "http"` is rejected — add the type. And a pasted token with a trailing newline produces a header that never authenticates; trim it:

```bash
TOKEN=$(cat token.txt | tr -d '\n')
claude mcp add --transport http myserver https://example.com/mcp --header "Authorization: Bearer $TOKEN"
```

Claude Code also warns about leading/trailing whitespace in `command`, `args`, `env` and `headers`, and about `${VAR}` references with no value — give them a fallback: `${API_KEY:-}` or `${API_BASE_URL:-https://api.example.com}`.

## 5. Slow start, big output

A server that installs on first run (`npx …`) can exceed the startup timeout:

```bash
MCP_TIMEOUT=10000 claude
```

Ten seconds instead of the default. A tool that returns huge payloads hits the output cap (25,000 tokens by default; warned at 10,000) — raise it with `MAX_MCP_OUTPUT_TOKENS=50000 claude`, or make the tool paginate.

## Still stuck

Run the server by hand (`npx -y @example/server`) and watch its stderr — a missing binary, a bad API key or a Python version error shows up there long before Claude Code can tell you. On Windows, wrap `npx` servers as `cmd /c npx …` if the shell can't find the shim.

---

Next: [install an MCP server in Claude Code](/guides/install-mcp-server-claude-code/) · [connect a remote MCP server over HTTP](/guides/claude-code-remote-mcp-servers/) · generate a config in the [MCP config tool](/tools/mcp-config/).