Connect to MCP servers changedmcp-quickstart
Upstream edited this page at 28 Oct 2026 19:51 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 30 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+7added
Lines−7removed
From line
282
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits17to this page, all time
The whole hunk
from line 282, old and new numbered
/
from line 282
282282
283283If a server doesn't connect, check its status with `/mcp` inside a session or `claude mcp list` from your shell, then match the symptom below. The `/mcp` panel also lets you reconnect or authenticate without leaving the session.
284284
285> **/mcp shows No MCP servers configured**
285> [accordion] /mcp shows No MCP servers configured
286286>
287287> Claude Code didn't find any servers for the current directory. The most common causes:
288288>
from line 290
290290> * You edited a configuration file at the wrong path. The correct files are `~/.claude.json` and `<project>/.mcp.json`. Claude Code doesn't read paths such as `~/.claude/.mcp.json`, `~/.claude/config/mcp.json`, `~/.claude/mcp.json`, or `%APPDATA%\Claude\mcp.json`. For user-scoped servers, run `claude mcp add --scope user`, which writes to the `mcpServers` key in `~/.claude.json`; for project-scoped servers, edit `.mcp.json` at the project root.
291291> * You wrote a malformed entry in `.mcp.json`. Claude Code skips that entry and still loads the others. Run `claude mcp list` from your shell and look for the parse warning, which names the offending field.
292292
293> **Status shows Failed to connect or Connection error**
293> [accordion] Status shows Failed to connect or Connection error
294294>
295295> Both statuses mean the server didn't start or the URL didn't respond. They can also appear for HTTP servers that reject the token you configured in `headers.Authorization`; a server that wants a token you haven't configured shows `! Needs authentication` instead, covered in [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in).
296296>
from line 330
330330> Run `claude mcp get <name>` and confirm the command shown there matches what you just ran. If the command shown differs from what you typed, you likely omitted the `--` separator before the server command. Remove the server and re-add it with `--` in place. If you wrote `.mcp.json` by hand, check its syntax and location. Before v2.1.285, `claude mcp get` printed no `Command` line for a stdio entry saved without a `type` field, such as a hand-written `.mcp.json` entry. On those versions, run `claude mcp list` instead, which prints the command line either way.
331331> * The command errors: the message names what's missing, such as Node.js or a browser.
332332
333> **Connection timed out at startup**
333> [accordion] Connection timed out at startup
334334>
335335> The server took longer than the default 30-second startup timeout. A stdio server's first run can be slow while `npx` downloads the package. Increase the limit with the [`MCP_TIMEOUT`](https://code.claude.com/docs/en/env-vars) environment variable, in milliseconds:
336336>
from line 346
346346>
347347> Before v2.1.299, some connections to HTTP servers that were up timed out at startup regardless of `MCP_TIMEOUT`. If you use one of those versions and an HTTP server that is up still times out after you raise the limit, [update Claude Code](https://code.claude.com/docs/en/setup.md#update-claude-code).
348348
349> **Server already exists**
349> [accordion] Server already exists
350350>
351351> You've already added a server with that name at the same scope. Either remove the existing entry first or choose a different name:
352352>
from line 356
356356>
357357> If the name exists at more than one scope, `remove` reports `exists in multiple scopes`. Pass `--scope` to choose which copy to delete, for example `claude mcp remove claude-code-docs --scope local`.
358358
359> **Server connects but no tools appear**
359> [accordion] Server connects but no tools appear
360360>
361361> Run `/mcp` inside a session and select the server to see its tool list. If the list is empty, the server started but didn't register any tools, which usually means it's missing a required environment variable such as an API key.
362362>
from line 364
364364>
365365> Before v2.1.302, `/mcp` showed the status `tools fetch failed` for a server using [protocol revision 2026-07-28](https://code.claude.com/docs/en/mcp.md#mcp-client-runtimes) that left `resultType`, `ttlMs`, or `cacheScope` out of its replies. If you use one of those versions and a server shows that status, [update Claude Code](https://code.claude.com/docs/en/setup.md#update-claude-code).
366366
367> **Changes to .mcp.json don't take effect**
367> [accordion] Changes to .mcp.json don't take effect
368368>
369369> Claude Code reads `.mcp.json` at session start. Exit and restart the session after editing the file.
370370>
from line 376
376376> claude mcp reset-project-choices
377377> ```
378378
379> **OAuth sign-in fails or browser doesn't open**
379> [accordion] OAuth sign-in fails or browser doesn't open
380380>
381381> Run `/mcp`, select the server, and choose `Authenticate` again. If the browser doesn't open automatically, copy the URL shown in the terminal and open it manually. See [Authenticate with remote MCP servers](https://code.claude.com/docs/en/mcp.md#authenticate-with-remote-mcp-servers) for fixed callback ports and pre-configured credentials.
382382
No line in this hunk matches that.