Connect to MCP servers changedmcp-quickstart
Nearest release: v2.1.305, published an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 20 Oct 2026 18:25 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 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+237added
Lines−243removed
From line
6
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits13to this page, all time
The whole hunk
from line 6, old and new numbered
/
from line 6
66
77This guide walks you through connecting one MCP server end to end with the Claude Code CLI. By the end, you'll have a server connected and responding, know where its configuration lives on disk, and know how to fix the most common connection errors.
88
9<Note>
10 You can also add MCP servers from other surfaces, including the desktop app, VS Code, and the web. See [Connect from other surfaces](#connect-from-other-surfaces).
11</Note>
9> [!NOTE]
10>
11> You can also add MCP servers from other surfaces, including the desktop app, VS Code, and the web. See [Connect from other surfaces](#connect-from-other-surfaces).
1212
1313For every way to connect and configure MCP servers in Claude Code, see the [MCP reference](/docs/en/mcp).
1414
from line 25
2525
2626The steps are the same for any server: add it, check the connection status, then use it in a session, with an optional cleanup step at the end. Some servers add a step, like a browser sign-in, shown in [Additional MCP server examples](#additional-mcp-server-examples). For more servers to connect, browse the [Anthropic Directory](/docs/en/mcp#find-and-build-mcp-servers).
2727
28<Steps>
29 <Step title="Add the MCP server">
30 Register the server with Claude Code. Run this in your terminal, not inside a `claude` session: you're configuring the server before starting a conversation.
28**1. Add the MCP server**
3129
32 ```bash theme={null}
33 claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
34 ```
30Register the server with Claude Code. Run this in your terminal, not inside a `claude` session: you're configuring the server before starting a conversation.
3531
36 The parts of the command:
32```bash theme={null}
33claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
34```
3735
38 * `claude mcp add`: registers a server with Claude Code.
39 * `--transport http`: the server is hosted at a URL rather than run as a local process.
40 * `claude-code-docs`: a name you make up. Calling the same server `docs` would work identically. Claude Code uses whatever name you pick to label the server's tools in Claude's output and to refer to the server in commands like `claude mcp remove`.
41 * `https://code.claude.com/docs/mcp`: the URL where the server is hosted.
36The parts of the command:
4237
43 The command prints a confirmation like `Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config`, followed by a `File modified:` line showing the configuration file it wrote. The `local config` part means the server is registered to you, in this project: if you start Claude Code in a different project, this server isn't active there. To register a server once for all your projects, add it at user scope, covered in [Change server scope](#change-server-scope).
44 </Step>
38* `claude mcp add`: registers a server with Claude Code.
39* `--transport http`: the server is hosted at a URL rather than run as a local process.
40* `claude-code-docs`: a name you make up. Calling the same server `docs` would work identically. Claude Code uses whatever name you pick to label the server's tools in Claude's output and to refer to the server in commands like `claude mcp remove`.
41* `https://code.claude.com/docs/mcp`: the URL where the server is hosted.
4542
46 <Step title="Check the connection status">
47 Confirm the server appears in your server list and check its status:
43The command prints a confirmation like `Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config`, followed by a `File modified:` line showing the configuration file it wrote. The `local config` part means the server is registered to you, in this project: if you start Claude Code in a different project, this server isn't active there. To register a server once for all your projects, add it at user scope, covered in [Change server scope](#change-server-scope).
4844
49 ```bash theme={null}
50 claude mcp list
51 ```
45**2. Check the connection status**
5246
53 The server appears with a status indicator:
47Confirm the server appears in your server list and check its status:
5448
55 | Status | Meaning |
56 | :- | :- |
57 | `✔ Connected` | Ready to use. This is what you should see for `claude-code-docs` |
58 | `! Connected · tools fetch failed` | The server connected but couldn't list its tools. Run `claude mcp get <name>` for the error detail |
59 | `! Needs authentication` | The server is reachable but needs a browser sign-in, or a token passed with `--header`. See [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in) |
60 | `✘ Failed to connect` | Server didn't respond. See [Troubleshooting](#troubleshooting) |
61 | `✘ Connection error` | The connection attempt threw an error. See [Troubleshooting](#troubleshooting) |
62 | ``⏸ Pending approval (run `claude` to approve)`` | A project-scoped server you haven't approved yet. See [Edit .mcp.json directly](#edit-mcp-json-directly) |
63 | `⊘ Disabled for this project (re-enable via /mcp)` | A server turned off for this project by the project's `disabledMcpServers` list. See [Disable a server without removing it](/docs/en/mcp#disable-a-server-without-removing-it) |
49```bash theme={null}
50claude mcp list
51```
6452
65 Some legacy Windows consoles, such as the default console on Windows 10, don't support these Unicode glyphs and show `√` and `×` in place of `✔` and `✘`.
66 </Step>
53The server appears with a status indicator:
6754
68 <Step title="Use the server">
69 Start a session and ask Claude to use the new server by name:
55| Status | Meaning |
56| :- | :- |
57| `✔ Connected` | Ready to use. This is what you should see for `claude-code-docs` |
58| `! Connected · tools fetch failed` | The server connected but couldn't list its tools. Run `claude mcp get <name>` for the error detail |
59| `! Needs authentication` | The server is reachable but needs a browser sign-in, or a token passed with `--header`. See [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in) |
60| `✘ Failed to connect` | Server didn't respond. See [Troubleshooting](#troubleshooting) |
61| `✘ Connection error` | The connection attempt threw an error. See [Troubleshooting](#troubleshooting) |
62| ``⏸ Pending approval (run `claude` to approve)`` | A project-scoped server you haven't approved yet. See [Edit .mcp.json directly](#edit-mcp-json-directly) |
63| `⊘ Disabled for this project (re-enable via /mcp)` | A server turned off for this project by the project's `disabledMcpServers` list. See [Disable a server without removing it](/docs/en/mcp#disable-a-server-without-removing-it) |
7064
71 ```bash theme={null}
72 claude
73 ```
65Some legacy Windows consoles, such as the default console on Windows 10, don't support these Unicode glyphs and show `√` and `×` in place of `✔` and `✘`.
7466
75 ```text wrap theme={null}
76 Use the claude-code-docs server to look up what MCP_TIMEOUT does
77 ```
67**3. Use the server**
7868
79 <Info>
80 You don't normally need to name a server in your prompt, since Claude chooses relevant tools on its own. Naming it here guarantees the demonstration goes through the new server rather than another tool, such as web fetch, that could answer the same question.
81 </Info>
69Start a session and ask Claude to use the new server by name:
8270
83 If Claude Code asks for permission the first time Claude calls the server, approve it. The tool call in Claude's output is labeled with the server name, which is how you confirm the answer came from the MCP server rather than Claude's built-in knowledge.
84 </Step>
71```bash theme={null}
72claude
73```
8574
86 <Step title="Remove the server">
87 This step is optional. When you're done experimenting, you can remove the server:
75```text wrap theme={null}
76Use the claude-code-docs server to look up what MCP_TIMEOUT does
77```
8878
89 ```bash theme={null}
90 claude mcp remove claude-code-docs
91 ```
79> [!NOTE]
80>
81> You don't normally need to name a server in your prompt, since Claude chooses relevant tools on its own. Naming it here guarantees the demonstration goes through the new server rather than another tool, such as web fetch, that could answer the same question.
9282
93 The command confirms with `Removed MCP server "claude-code-docs" from local config` and a `File modified:` line showing the file it updated.
83If Claude Code asks for permission the first time Claude calls the server, approve it. The tool call in Claude's output is labeled with the server name, which is how you confirm the answer came from the MCP server rather than Claude's built-in knowledge.
9484
95 <Note>
96 Each connected server takes some space in [Claude's context window](/docs/en/how-claude-code-works#the-context-window) because its tool names and server instructions load into every session. Removing servers you no longer use keeps that space free.
97 </Note>
98 </Step>
99</Steps>
85**4. Remove the server**
10086
87This step is optional. When you're done experimenting, you can remove the server:
88
89```bash theme={null}
90claude mcp remove claude-code-docs
91```
92
93The command confirms with `Removed MCP server "claude-code-docs" from local config` and a `File modified:` line showing the file it updated.
94
95> [!NOTE]
96>
97> Each connected server takes some space in [Claude's context window](/docs/en/how-claude-code-works#the-context-window) because its tool names and server instructions load into every session. Removing servers you no longer use keeps that space free.
98
10199## Where servers are saved
102100
103101The `claude mcp add` command writes the server's details to a configuration file. By default it registers the server at `local` scope: private to you, active only in the current project. Pass `--scope user` to register it once for all your projects, or `--scope project` to share it with teammates. [Change server scope](#change-server-scope) walks through both.
104102
105<Note>
106 `claude mcp add` works the same in every shell, including PowerShell and Command Prompt. Inside a `claude` session, use the `/mcp` command to check and manage servers you've already added.
107</Note>
103> [!NOTE]
104>
105> `claude mcp add` works the same in every shell, including PowerShell and Command Prompt. Inside a `claude` session, use the `/mcp` command to check and manage servers you've already added.
108106
109107There are other ways to add a server, each with its own section:
110108
from line 160
162160
163161The [Playwright MCP server](https://github.com/microsoft/playwright-mcp) is a good one to try: it gives Claude a browser it can navigate, click, and read, and it needs no account. It runs through `npx`, so it requires [Node.js](https://nodejs.org/en/download) 18 or later.
164162
165<Steps>
166 <Step title="Add the Playwright server">
167 Register the server with the command Claude Code should run to start it:
163**1. Add the Playwright server**
168164
169 ```bash theme={null}
170 claude mcp add playwright -- npx -y @playwright/mcp@latest
171 ```
165Register the server with the command Claude Code should run to start it:
172166
173 This command differs from the hosted example in three ways:
167```bash theme={null}
168claude mcp add playwright -- npx -y @playwright/mcp@latest
169```
174170
175 * There's no `--transport` flag, because local servers use the default `stdio` transport.
176 * Everything after the `--` separator is the command Claude Code runs to start the server.
177 * `-y` tells `npx` to install the package without prompting.
171This command differs from the hosted example in three ways:
178172
179 The command prints a confirmation like `Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest to local config`, followed by a `File modified:` line showing the configuration file it wrote.
173* There's no `--transport` flag, because local servers use the default `stdio` transport.
174* Everything after the `--` separator is the command Claude Code runs to start the server.
175* `-y` tells `npx` to install the package without prompting.
180176
181 Playwright drives whichever Chrome is already installed on your machine. To use a different browser, append `--browser` with the browser name, for example `--browser firefox`, after `@playwright/mcp@latest`.
182 </Step>
177The command prints a confirmation like `Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest to local config`, followed by a `File modified:` line showing the configuration file it wrote.
183178
184 <Step title="Check the connection">
185 The `Added` confirmation means the entry was saved, not that the command runs. Check the connection:
179Playwright drives whichever Chrome is already installed on your machine. To use a different browser, append `--browser` with the browser name, for example `--browser firefox`, after `@playwright/mcp@latest`.
186180
187 ```bash theme={null}
188 claude mcp list
189 ```
181**2. Check the connection**
190182
191 The first check can show `✘ Failed to connect` while `npx` downloads the package, so wait a moment and run it again. Once the download finishes, the status changes to `✔ Connected`. If it still shows `✘ Failed to connect` after a couple of retries, see [Troubleshooting](#troubleshooting).
192 </Step>
183The `Added` confirmation means the entry was saved, not that the command runs. Check the connection:
193184
194 <Step title="Use the browser">
195 Give Claude a task that needs the browser:
185```bash theme={null}
186claude mcp list
187```
196188
197 ```text wrap theme={null}
198 Use playwright to open https://example.com and tell me the page title
199 ```
189The first check can show `✘ Failed to connect` while `npx` downloads the package, so wait a moment and run it again. Once the download finishes, the status changes to `✔ Connected`. If it still shows `✘ Failed to connect` after a couple of retries, see [Troubleshooting](#troubleshooting).
200190
201 A browser window opens so you can watch it work, and the tool calls in Claude's output are labeled with the `playwright` server name and the action, like `browser_navigate`.
191**3. Use the browser**
202192
203 Try pointing it at your local dev server to check that a page still renders after a change, or have it walk through a bug report step by step.
204 </Step>
205</Steps>
193Give Claude a task that needs the browser:
206194
195```text wrap theme={null}
196Use playwright to open https://example.com and tell me the page title
197```
198
199A browser window opens so you can watch it work, and the tool calls in Claude's output are labeled with the `playwright` server name and the action, like `browser_navigate`.
200
201Try pointing it at your local dev server to check that a page still renders after a change, or have it walk through a bug report step by step.
202
207203### Connect a server that requires sign-in
208204
209205Hosted services like Sentry, Linear, and Notion run their MCP servers behind OAuth: you add the server's URL, then sign in through your browser.
from line 206
210206
211207The steps below use Sentry as the example. To connect a different service, substitute its URL, which you can find in the [Anthropic Directory](/docs/en/mcp#find-and-build-mcp-servers) or the service's documentation.
212208
213<Steps>
214 <Step title="Add the server">
215 The `add` command is the same as for the docs server, with Sentry's URL:
209**1. Add the server**
216210
217 ```bash theme={null}
218 claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
219 ```
211The `add` command is the same as for the docs server, with Sentry's URL:
220212
221 After adding, `claude mcp list` shows the server with `! Needs authentication`. That's expected: the next step completes the sign-in.
222 </Step>
213```bash theme={null}
214claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
215```
223216
224 <Step title="Authenticate in your browser">
225 Start a Claude Code session and open the MCP panel:
217After adding, `claude mcp list` shows the server with `! Needs authentication`. That's expected: the next step completes the sign-in.
226218
227 ```text wrap theme={null}
228 /mcp
229 ```
219**2. Authenticate in your browser**
230220
231 Select `sentry` from the list, press Enter, and choose `Authenticate`. Your browser opens to Sentry's sign-in page. Approve the connection there.
221Start a Claude Code session and open the MCP panel:
232222
233 Back in Claude Code, the server's status changes to connected. If sign-in fails or the browser doesn't open, see [Troubleshooting](#troubleshooting).
234 </Step>
223```text wrap theme={null}
224/mcp
225```
235226
236 <Step title="Use the server">
237 Ask Claude something that needs the service, like `What Sentry projects do I have access to?`, and look for tool calls labeled with the `sentry` server name in its output.
238 </Step>
239</Steps>
227Select `sentry` from the list, press Enter, and choose `Authenticate`. Your browser opens to Sentry's sign-in page. Approve the connection there.
240228
229Back in Claude Code, the server's status changes to connected. If sign-in fails or the browser doesn't open, see [Troubleshooting](#troubleshooting).
230
231**3. Use the server**
232
233Ask Claude something that needs the service, like `What Sentry projects do I have access to?`, and look for tool calls labeled with the `sentry` server name in its output.
234
241235Servers that authenticate with a static token instead of OAuth take the token at add time with `--header "Authorization: Bearer <token>"`. See the [GitHub example](/docs/en/mcp#example-connect-to-github-for-code-reviews) for a worked version.
242236
243237## Edit .mcp.json directly
from line 281
287281
288282If 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.
289283
290<AccordionGroup>
291 <Accordion title="/mcp shows No MCP servers configured">
292 Claude Code didn't find any servers for the current directory. The most common causes:
284> **/mcp shows No MCP servers configured**
285>
286> Claude Code didn't find any servers for the current directory. The most common causes:
287>
288> * You ran `claude mcp add` from a different project. Local-scoped servers are tied to the project where you added them: the repository root, or the exact directory if you weren't in a git repository. Re-add the server from the project you're in now, or add it with `--scope user` so it isn't tied to a project.
289> * 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.
290> * 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.
293291
294 * You ran `claude mcp add` from a different project. Local-scoped servers are tied to the project where you added them: the repository root, or the exact directory if you weren't in a git repository. Re-add the server from the project you're in now, or add it with `--scope user` so it isn't tied to a project.
295 * 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.
296 * 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.
297 </Accordion>
292> **Status shows Failed to connect or Connection error**
293>
294> 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).
295>
296> Your first step depends on which status you see:
297>
298> * `Failed to connect`: start with the failure detail on the status itself. `claude mcp list` and `claude mcp get <name>` show the HTTP status or error code and any error text the server returned, which often names the problem directly, such as a missing header or a rejected token. Before v2.1.219, `Failed to connect` showed only the bare status, and you needed the curl and command checks later in this section to find the cause.
299> * `Connection error`: Claude Code appends no detail to this status on any version, so go straight to the curl and command checks later in this section.
300>
301> If the detail points to a credential or URL, also check the warnings in the `claude mcp list` output. Claude Code flags config values with hidden leading or trailing whitespace, a common cause of authentication failures after pasting a token.
302>
303> If an HTTP server returns `404 Not Found`, Claude Code shows `MCP endpoint not found at <origin>. Check the URL in your MCP config.` when you select the server in `/mcp`. The message names the URL's origin, such as `https://mcp.example.com`, without its path, so run `claude mcp get <name>` to see the full URL you configured. Compare its path to the server's documented MCP endpoint path, then run `claude mcp remove <name>` and re-add with the correct URL. Before v2.1.219, the message included the URL's path as well, and before v2.1.191, a `404` showed a generic `Error POSTing to endpoint` message without the URL.
304>
305> For HTTP servers, confirm the URL is reachable from your machine:
306>
307> ```bash theme={null}
308> curl -I https://mcp.sentry.dev/mcp
309> ```
310>
311> In PowerShell, use `curl.exe` instead of `curl` so the request goes to the real curl binary rather than the `Invoke-WebRequest` alias.
312>
313> The response tells you which kind of problem you have:
314>
315> * A `404` or `405`: the server is up. Many MCP endpoints answer only POST requests, so this still confirms the URL is reachable from your machine.
316> * A `401` or `403`: the server is up and you need to authenticate. Use the browser sign-in in [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in), or for servers that take a token instead, like GitHub's, pass it with `--header "Authorization: Bearer <token>"` on the `claude mcp add` command.
317> * No response at all: check the URL and your network.
318>
319> For stdio servers, run the configured command directly in your terminal to see the underlying error. For the Playwright server from this guide, run:
320>
321> ```bash theme={null}
322> npx -y @playwright/mcp@latest
323> ```
324>
325> What happens next tells you where the problem is:
326>
327> * The command starts and waits for input: the server itself works.
328>
329> 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.
330> * The command errors: the message names what's missing, such as Node.js or a browser.
298331
299 <Accordion title="Status shows Failed to connect or Connection error">
300 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).
332> **Connection timed out at startup**
333>
334> 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`](/docs/en/env-vars) environment variable, in milliseconds:
335>
336> ```bash theme={null}
337> MCP_TIMEOUT=60000 claude
338> ```
339>
340> In PowerShell, set the variable before the command on the same line:
341>
342> ```powershell theme={null}
343> $env:MCP_TIMEOUT = "60000"; claude
344> ```
345>
346> 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](/docs/en/setup#update-claude-code).
301347
302 Your first step depends on which status you see:
348> **Server already exists**
349>
350> You've already added a server with that name at the same scope. Either remove the existing entry first or choose a different name:
351>
352> ```bash theme={null}
353> claude mcp remove claude-code-docs
354> ```
355>
356> 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`.
303357
304 * `Failed to connect`: start with the failure detail on the status itself. `claude mcp list` and `claude mcp get <name>` show the HTTP status or error code and any error text the server returned, which often names the problem directly, such as a missing header or a rejected token. Before v2.1.219, `Failed to connect` showed only the bare status, and you needed the curl and command checks later in this section to find the cause.
305 * `Connection error`: Claude Code appends no detail to this status on any version, so go straight to the curl and command checks later in this section.
358> **Server connects but no tools appear**
359>
360> 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.
361>
362> Pass the variable with `--env KEY=value` on `claude mcp add`, or in the `env` field of the server's `.mcp.json` entry. The server's documentation lists the variables it needs.
363>
364> Before v2.1.302, `/mcp` showed the status `tools fetch failed` for a server using [protocol revision 2026-07-28](/docs/en/mcp#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](/docs/en/setup#update-claude-code).
306365
307 If the detail points to a credential or URL, also check the warnings in the `claude mcp list` output. Claude Code flags config values with hidden leading or trailing whitespace, a common cause of authentication failures after pasting a token.
366> **Changes to .mcp.json don't take effect**
367>
368> Claude Code reads `.mcp.json` at session start. Exit and restart the session after editing the file.
369>
370> If your servers still don't appear, run `claude mcp list` and look for a parse warning. Claude Code skips malformed entries and shows the offending field there.
371>
372> If you previously rejected the server when prompted, reset project approvals:
373>
374> ```bash theme={null}
375> claude mcp reset-project-choices
376> ```
308377
309 If an HTTP server returns `404 Not Found`, Claude Code shows `MCP endpoint not found at <origin>. Check the URL in your MCP config.` when you select the server in `/mcp`. The message names the URL's origin, such as `https://mcp.example.com`, without its path, so run `claude mcp get <name>` to see the full URL you configured. Compare its path to the server's documented MCP endpoint path, then run `claude mcp remove <name>` and re-add with the correct URL. Before v2.1.219, the message included the URL's path as well, and before v2.1.191, a `404` showed a generic `Error POSTing to endpoint` message without the URL.
310
311 For HTTP servers, confirm the URL is reachable from your machine:
312
313 ```bash theme={null}
314 curl -I https://mcp.sentry.dev/mcp
315 ```
316
317 In PowerShell, use `curl.exe` instead of `curl` so the request goes to the real curl binary rather than the `Invoke-WebRequest` alias.
318
319 The response tells you which kind of problem you have:
320
321 * A `404` or `405`: the server is up. Many MCP endpoints answer only POST requests, so this still confirms the URL is reachable from your machine.
322 * A `401` or `403`: the server is up and you need to authenticate. Use the browser sign-in in [Connect a server that requires sign-in](#connect-a-server-that-requires-sign-in), or for servers that take a token instead, like GitHub's, pass it with `--header "Authorization: Bearer <token>"` on the `claude mcp add` command.
323 * No response at all: check the URL and your network.
324
325 For stdio servers, run the configured command directly in your terminal to see the underlying error. For the Playwright server from this guide, run:
326
327 ```bash theme={null}
328 npx -y @playwright/mcp@latest
329 ```
330
331 What happens next tells you where the problem is:
332
333 * The command starts and waits for input: the server itself works.
334
335 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.
336 * The command errors: the message names what's missing, such as Node.js or a browser.
337 </Accordion>
338
339 <Accordion title="Connection timed out at startup">
340 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`](/docs/en/env-vars) environment variable, in milliseconds:
341
342 ```bash theme={null}
343 MCP_TIMEOUT=60000 claude
344 ```
345
346 In PowerShell, set the variable before the command on the same line:
347
348 ```powershell theme={null}
349 $env:MCP_TIMEOUT = "60000"; claude
350 ```
351
352 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](/docs/en/setup#update-claude-code).
353 </Accordion>
354
355 <Accordion title="Server already exists">
356 You've already added a server with that name at the same scope. Either remove the existing entry first or choose a different name:
357
358 ```bash theme={null}
359 claude mcp remove claude-code-docs
360 ```
361
362 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`.
363 </Accordion>
364
365 <Accordion title="Server connects but no tools appear">
366 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.
367
368 Pass the variable with `--env KEY=value` on `claude mcp add`, or in the `env` field of the server's `.mcp.json` entry. The server's documentation lists the variables it needs.
369 </Accordion>
370
371 <Accordion title="Changes to .mcp.json don't take effect">
372 Claude Code reads `.mcp.json` at session start. Exit and restart the session after editing the file.
373
374 If your servers still don't appear, run `claude mcp list` and look for a parse warning. Claude Code skips malformed entries and shows the offending field there.
375
376 If you previously rejected the server when prompted, reset project approvals:
377
378 ```bash theme={null}
379 claude mcp reset-project-choices
380 ```
381 </Accordion>
382
383 <Accordion title="OAuth sign-in fails or browser doesn't open">
384 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](/docs/en/mcp#authenticate-with-remote-mcp-servers) for fixed callback ports and pre-configured credentials.
385 </Accordion>
386</AccordionGroup>
378> **OAuth sign-in fails or browser doesn't open**
379>
380> 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](/docs/en/mcp#authenticate-with-remote-mcp-servers) for fixed callback ports and pre-configured credentials.
387381
388382## Next steps
389383
No line in this hunk matches that.