Connect Claude Code to tools via MCP changedmcp
Nearest release: v2.1.304, published under 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 19 Oct 2026 19:44 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+320added
Lines−350removed
From line
23
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits83to this page, all time
#### Mark a tool to load upfront or stay deferred ### Defer a server's tools
The whole hunk
from line 23, old and new numbered
/
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 23
2323
2424Browse reviewed connectors in the [Anthropic Directory](https://claude.ai/directory). Directory connectors use the same MCP infrastructure as Claude Code, so you can add any remote server listed there with `claude mcp add`.
2525
26<Warning>
27 Verify you trust each server before connecting it. Servers that fetch external content can expose you to [prompt injection risk](/docs/en/security#protect-against-prompt-injection).
28</Warning>
26> [!WARNING]
27>
28> Verify you trust each server before connecting it. Servers that fetch external content can expose you to [prompt injection risk](/docs/en/security#protect-against-prompt-injection).
2929
3030To build your own server, see the [MCP server guide](https://modelcontextprotocol.io/docs/develop/build-server) for protocol fundamentals and the [Claude connector building docs](https://claude.com/docs/connectors/building) for authentication, testing, and Directory submission.
3131
3232You can also have Claude scaffold a server for you with the official [`mcp-server-dev` plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev).
3333
34<Steps>
35 <Step title="Install the plugin">
36 In the VS Code extension or the desktop app, follow [Install a plugin](/docs/en/plugins/install#install-a-plugin) instead of this step. In a terminal, start Claude Code by running `claude`, then enter this at its prompt:
37
38 ```
39 /plugin install mcp-server-dev@claude-plugins-official
40 ```
41
42 If the install fails, match the message Claude Code reports:
43
44 * `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.
45 * `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](/docs/en/plugins/troubleshooting#plugin-not-found-in-marketplace).
46
47 If the install summary reports `Run /reload-plugins to apply.`, Claude Code then runs that reload for you. If the reload warns that your next message would re-read the conversation, run `/reload-plugins --force`.
48 </Step>
49
50 <Step title="Run the build skill">
51 ```
52 /mcp-server-dev:build-mcp-server
53 ```
54
55 Claude asks about your use case and scaffolds a remote HTTP or local stdio server.
56 </Step>
57</Steps>
34**1. Install the plugin**
35
36In the VS Code extension or the desktop app, follow [Install a plugin](/docs/en/plugins/install#install-a-plugin) instead of this step. In a terminal, start Claude Code by running `claude`, then enter this at its prompt:
37
38```
39/plugin install mcp-server-dev@claude-plugins-official
40```
41
42If the install fails, match the message Claude Code reports:
43
44* `Marketplace "claude-plugins-official" not found`: add the marketplace with `/plugin marketplace add anthropics/claude-plugins-official`, then retry the install.
45* `Plugin "<name>" not found in marketplace "claude-plugins-official"`: your local copy of the marketplace catalog may be out of date. Refresh it with `/plugin marketplace update claude-plugins-official`, then retry the install. If the retry prints the same message, see [Plugin not found in marketplace](/docs/en/plugins/troubleshooting#plugin-not-found-in-marketplace).
46
47If the install summary reports `Run /reload-plugins to apply.`, Claude Code then runs that reload for you. If the reload warns that your next message would re-read the conversation, run `/reload-plugins --force`.
48
49**2. Run the build skill**
50
51```
52/mcp-server-dev:build-mcp-server
53```
54
55Claude asks about your use case and scaffolds a remote HTTP or local stdio server.
5856
5957## Installing MCP servers
6058
from line 84
8684
8785### Option 2: Add a remote SSE server
8886
89<Warning>
90 The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available.
91</Warning>
87> [!WARNING]
88>
89> The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available.
9290
9391Some services still expose only an SSE endpoint. Add these with the same `claude mcp add --transport http <name> <url>` command as [an HTTP server](#option-1-add-a-remote-http-server). Claude Code tries the HTTP transport first and switches to SSE when the server doesn't accept it. The automatic switch requires Claude Code v2.1.265 or later.
9492
from line 123
125123 -- npx -y airtable-mcp-server
126124```
127125
128<Note>
129 For stdio servers, the `--` (double dash) separates Claude's own options, such as `--transport`, `--env`, and `--scope`, from the command and arguments that run the server. Everything after `--` is passed to the server untouched.
130
131 For example:
132
133 * `claude mcp add --transport stdio myserver -- npx server` → runs `npx server`
134 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → runs `python server.py --port 8080` with `KEY=value` in environment
135
136 Without `--`, Claude Code would try to parse the server's flags, like `--port` above, as its own options.
137
138 `--env` accepts multiple `KEY=value` pairs. If the server name comes directly after `--env`, the CLI reads the name as another pair and rejects it, so place at least one other option, such as `--transport stdio`, between `--env` and the server name.
139</Note>
126> [!NOTE]
127>
128> For stdio servers, the `--` (double dash) separates Claude's own options, such as `--transport`, `--env`, and `--scope`, from the command and arguments that run the server. Everything after `--` is passed to the server untouched.
129>
130> For example:
131>
132> * `claude mcp add --transport stdio myserver -- npx server` → runs `npx server`
133> * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → runs `python server.py --port 8080` with `KEY=value` in environment
134>
135> Without `--`, Claude Code would try to parse the server's flags, like `--port` above, as its own options.
136>
137> `--env` accepts multiple `KEY=value` pairs. If the server name comes directly after `--env`, the CLI reads the name as another pair and rejects it, so place at least one other option, such as `--transport stdio`, between `--env` and the server name.
140138
141139#### How Claude Code stops a stdio server
142140
from line 168
170168
171169Each is one of the inputs the four options in [Installing MCP servers](#installing-mcp-servers) take. Find the shape you have below to turn it into the command Claude Code accepts. Each command writes to [local scope](#local-scope) unless you add `--scope project` or `--scope user`.
172170
173<span id="from-a-url" />
174
175171#### Add a server from a URL
176172
177173A URL means the server is remote. For an `https://` endpoint, add it with `--transport http`, or follow [Option 2](#option-2-add-a-remote-sse-server) when the instructions say the endpoint uses SSE. For a `wss://` endpoint, use [Option 4](#option-4-add-a-remote-websocket-server) instead, since `--transport` doesn't accept `ws`:
from line 178
182178
183179If the instructions also give an API key or token header, pass it with `--header` as shown in [Option 1](#option-1-add-a-remote-http-server).
184180
185<span id="from-an-npx-uvx-or-binary-command" />
186
187181#### Add a server from an `npx`, `uvx`, or binary command
188182
189183A launch command means the server runs as a local stdio process. Put the whole command after `--`, so Claude Code passes flags such as `-y` to the command that starts the server instead of reading them as its own options. Pass any environment variables the instructions ask for with `--env`, after the server name and before `--`:
from line 187
193187```
194188
195189[Option 3](#option-3-add-a-local-stdio-server) covers the `--` separator in full.
196
197<span id="from-an-mcpservers-json-block" />
198190
199191#### Add a server from an `mcpServers` JSON block
200192
from line 403
411403
412404Claude Code asks stdio servers for that revision by default. To keep a stdio channel server on the earlier handshake, set [`MCP_PROTOCOL_NEGOTIATION`](/docs/en/env-vars) to `legacy`, which keeps every server on it.
413405
414<Tip>
415 Tips:
416
417 * Use the `-s` or `--scope` flag to specify where the configuration is stored:
418 * `local` (default): available only to you in the current project
419 * `project`: shared with everyone in the project via the `.mcp.json` file
420 * `user`: available to you across all projects
421 * Set environment variables with `-e` or `--env` flags (for example, `-e KEY=value`)
422 * The `--transport` and `--header` flags also accept `-t` and `-H` short forms
423 * Configure MCP server startup timeout using the `MCP_TIMEOUT` environment variable (for example, `MCP_TIMEOUT=10000 claude` sets a 10-second timeout)
424 * Set a per-server tool execution timeout by adding a `timeout` field in milliseconds to that server's `.mcp.json` entry, for example `"timeout": 600000` for ten minutes. This overrides the `MCP_TOOL_TIMEOUT` environment variable for that server only
425 * Claude Code displays a warning when MCP tool output exceeds 10,000 tokens and limits output to 25,000 tokens by default. To change the token limit, set the `MAX_MCP_OUTPUT_TOKENS` environment variable, for example `MAX_MCP_OUTPUT_TOKENS=50000`. The warning threshold is fixed. Unless the server raises a tool's own limit, successful text results longer than 50,000 characters are saved to a file regardless of this variable. See [MCP output limits and warnings](#mcp-output-limits-and-warnings)
426 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication
427</Tip>
406> [!TIP]
407>
408> Tips:
409>
410> * Use the `-s` or `--scope` flag to specify where the configuration is stored:
411> * `local` (default): available only to you in the current project
412> * `project`: shared with everyone in the project via the `.mcp.json` file
413> * `user`: available to you across all projects
414> * Set environment variables with `-e` or `--env` flags (for example, `-e KEY=value`)
415> * The `--transport` and `--header` flags also accept `-t` and `-H` short forms
416> * Configure MCP server startup timeout using the `MCP_TIMEOUT` environment variable (for example, `MCP_TIMEOUT=10000 claude` sets a 10-second timeout)
417> * Set a per-server tool execution timeout by adding a `timeout` field in milliseconds to that server's `.mcp.json` entry, for example `"timeout": 600000` for ten minutes. This overrides the `MCP_TOOL_TIMEOUT` environment variable for that server only
418> * Claude Code displays a warning when MCP tool output exceeds 10,000 tokens and limits output to 25,000 tokens by default. To change the token limit, set the `MAX_MCP_OUTPUT_TOKENS` environment variable, for example `MAX_MCP_OUTPUT_TOKENS=50000`. The warning threshold is fixed. Unless the server raises a tool's own limit, successful text results longer than 50,000 characters are saved to a file regardless of this variable. See [MCP output limits and warnings](#mcp-output-limits-and-warnings)
419> * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication
428420
429421The per-server `timeout` is a hard wall-clock limit per tool call, and progress notifications from the server don't extend it. Values below 1000 are ignored and fall through to `MCP_TOOL_TIMEOUT`, or to its default of about 28 hours when that variable is unset. For an HTTP, SSE, or [claude.ai connector](/docs/en/mcp#use-mcp-servers-from-claude-ai) server there is also a second, per-request timer that covers each request through to the server's first response byte. Claude Code sets that timer to the greatest of three values: 60 seconds, the tool timeout that applies to the server, and `MCP_TIMEOUT`. The 28-hour default of an unset `MCP_TOOL_TIMEOUT` doesn't enter that comparison, and a value below 60 seconds doesn't shorten the timer. Stdio and WebSocket servers have no per-request timer.
430422
from line 535
543535
544536Local scope is the default. A local-scoped server loads only in the project where you added it and stays private to you. Claude Code stores it in `~/.claude.json` under that project's path, so the same server won't appear in your other projects. Use local scope for personal development servers, experimental configurations, or servers with credentials you don't want in version control.
545537
546<Note>
547 The term "local scope" for MCP servers differs from general local settings. MCP local-scoped servers are stored in `~/.claude.json` (your home directory), while general local settings use `.claude/settings.local.json` (in the project directory). See [Settings](/docs/en/settings#where-settings-live) for details on settings file locations.
548</Note>
538> [!NOTE]
539>
540> The term "local scope" for MCP servers differs from general local settings. MCP local-scoped servers are stored in `~/.claude.json` (your home directory), while general local settings use `.claude/settings.local.json` (in the project directory). See [Settings](/docs/en/settings#where-settings-live) for details on settings file locations.
549541
550542```bash theme={null}
551543# Add a local-scoped server (default)
from line 768
776768
777769If you configured `headers.Authorization` for the server and the server rejects that header, Claude Code reports the connection as failed instead of falling back to OAuth. Check that the token is valid for the MCP endpoint, or remove the header to use the OAuth flow.
778770
779<Steps>
780 <Step title="Add the server that requires authentication">
781 If you already added the `sentry` server in the [MCP quickstart](/docs/en/mcp-quickstart#connect-a-server-that-requires-sign-in), skip this step: running `claude mcp add` again with the same server name at the same scope fails with `MCP server sentry already exists in local config`. Otherwise, run:
782
783 ```bash theme={null}
784 claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
785 ```
786 </Step>
787
788 <Step title="Use the /mcp command within Claude Code">
789 In Claude Code, use the command:
790
791 ```text wrap theme={null}
792 /mcp
793 ```
794
795 Then follow the steps in your browser to log in.
796 </Step>
797</Steps>
798
799<Tip>
800 Tips:
801
802 * Authentication tokens are stored securely and refreshed automatically
803 * Use "Clear authentication" in the `/mcp` menu to revoke access
804 * If your browser doesn't open automatically, copy the provided URL and open it manually
805 * If the browser redirect fails with a connection error after authenticating, paste the full callback URL from your browser's address bar into the URL prompt that appears in Claude Code
806 * OAuth authentication works with HTTP servers
807</Tip>
771**1. Add the server that requires authentication**
772
773If you already added the `sentry` server in the [MCP quickstart](/docs/en/mcp-quickstart#connect-a-server-that-requires-sign-in), skip this step: running `claude mcp add` again with the same server name at the same scope fails with `MCP server sentry already exists in local config`. Otherwise, run:
774
775```bash theme={null}
776claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
777```
778
779**2. Use the /mcp command within Claude Code**
780
781In Claude Code, use the command:
782
783```text wrap theme={null}
784/mcp
785```
786
787Then follow the steps in your browser to log in.
788
789> [!TIP]
790>
791> Tips:
792>
793> * Authentication tokens are stored securely and refreshed automatically
794> * Use "Clear authentication" in the `/mcp` menu to revoke access
795> * If your browser doesn't open automatically, copy the provided URL and open it manually
796> * If the browser redirect fails with a connection error after authenticating, paste the full callback URL from your browser's address bar into the URL prompt that appears in Claude Code
797> * OAuth authentication works with HTTP servers
808798
809799### Authenticate from the command line
810800
from line 829
839829
840830Some MCP servers don't support automatic OAuth setup via Dynamic Client Registration. If you see an error like "Incompatible auth server: does not support dynamic client registration," the server requires pre-configured credentials. Claude Code also supports servers that use a Client ID Metadata Document (CIMD) instead of Dynamic Client Registration, and discovers these automatically. If automatic discovery fails, register an OAuth app through the server's developer portal first, then provide the credentials when adding the server.
841831
842<Steps>
843 <Step title="Register an OAuth app with the server">
844 Create an app through the server's developer portal and note your client ID and client secret.
845
846 If the registration form asks for a redirect URI, pick any available port and enter `http://localhost:PORT/callback` with that port. You'll use the same port in the next step.
847
848 In v2.1.229, Claude Code sent `http://127.0.0.1:PORT/callback` instead, and servers that exact-match the registered redirect URI rejected the sign-in with a redirect URI mismatch. Claude Code v2.1.231 restored the `localhost` form. To recover on v2.1.229, upgrade Claude Code, or temporarily add the `http://127.0.0.1:PORT/callback` form to the server's registered redirect URIs.
849 </Step>
850
851 <Step title="Add the server with your credentials">
852 The tabs cover both commands: `claude mcp add` takes your client ID and callback port as flags, and `claude mcp add-json` takes them in an `oauth` object. If you registered a redirect URI, set the callback port to the port in that URI.
853
854 <Tabs>
855 <Tab title="claude mcp add">
856 Use `--client-id` to pass your app's client ID. The `--client-secret` flag prompts for the secret with masked input:
857
858 ```bash theme={null}
859 claude mcp add --transport http \
860 --client-id your-client-id --client-secret --callback-port 8080 \
861 my-server https://mcp.example.com/mcp
862 ```
863 </Tab>
864
865 <Tab title="claude mcp add-json">
866 Include the `oauth` object in the JSON config and pass `--client-secret` as a separate flag:
867
868 ```bash theme={null}
869 claude mcp add-json my-server \
870 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
871 --client-secret
872 ```
873 </Tab>
874
875 <Tab title="claude mcp add-json (callback port only)">
876 To fix only the callback port and let Claude Code register the client automatically, set `callbackPort` on its own:
877
878 ```bash theme={null}
879 claude mcp add-json my-server \
880 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'
881 ```
882 </Tab>
883
884 <Tab title="CI / env var">
885 Set the secret via environment variable to skip the interactive prompt:
886
887 ```bash theme={null}
888 MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
889 --client-id your-client-id --client-secret --callback-port 8080 \
890 my-server https://mcp.example.com/mcp
891 ```
892 </Tab>
893 </Tabs>
894 </Step>
895
896 <Step title="Authenticate in Claude Code">
897 Run `/mcp` in Claude Code and follow the browser login flow.
898 </Step>
899</Steps>
900
901<Tip>
902 Tips:
903
904 * The client secret is stored securely in your system keychain (macOS) or a credentials file, not in your config
905 * You can set the client secret only when you add the server. When you authenticate with `claude mcp login` or from `/mcp`, Claude Code uses the stored secret and doesn't prompt for one or read `MCP_CLIENT_SECRET`
906 * To add or change the secret later, remove the server with `claude mcp remove <name>`, then add it again with `--client-secret` and the same `--scope`
907 * If the server uses a public OAuth client with no secret, use only `--client-id` without `--client-secret`
908 * These flags only apply to HTTP and SSE transports. They have no effect on stdio servers
909 * Use `claude mcp get <name>` to verify that OAuth credentials are configured for a server
910</Tip>
832**1. Register an OAuth app with the server**
833
834Create an app through the server's developer portal and note your client ID and client secret.
835
836If the registration form asks for a redirect URI, pick any available port and enter `http://localhost:PORT/callback` with that port. You'll use the same port in the next step.
837
838In v2.1.229, Claude Code sent `http://127.0.0.1:PORT/callback` instead, and servers that exact-match the registered redirect URI rejected the sign-in with a redirect URI mismatch. Claude Code v2.1.231 restored the `localhost` form. To recover on v2.1.229, upgrade Claude Code, or temporarily add the `http://127.0.0.1:PORT/callback` form to the server's registered redirect URIs.
839
840**2. Add the server with your credentials**
841
842The tabs cover both commands: `claude mcp add` takes your client ID and callback port as flags, and `claude mcp add-json` takes them in an `oauth` object. If you registered a redirect URI, set the callback port to the port in that URI.
843
844**claude mcp add**
845
846Use `--client-id` to pass your app's client ID. The `--client-secret` flag prompts for the secret with masked input:
847
848```bash theme={null}
849claude mcp add --transport http \
850 --client-id your-client-id --client-secret --callback-port 8080 \
851 my-server https://mcp.example.com/mcp
852```
853
854**claude mcp add-json**
855
856Include the `oauth` object in the JSON config and pass `--client-secret` as a separate flag:
857
858```bash theme={null}
859claude mcp add-json my-server \
860 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
861 --client-secret
862```
863
864**claude mcp add-json (callback port only)**
865
866To fix only the callback port and let Claude Code register the client automatically, set `callbackPort` on its own:
867
868```bash theme={null}
869claude mcp add-json my-server \
870 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'
871```
872
873**CI / env var**
874
875Set the secret via environment variable to skip the interactive prompt:
876
877```bash theme={null}
878MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
879 --client-id your-client-id --client-secret --callback-port 8080 \
880 my-server https://mcp.example.com/mcp
881```
882
883**3. Authenticate in Claude Code**
884
885Run `/mcp` in Claude Code and follow the browser login flow.
886
887> [!TIP]
888>
889> Tips:
890>
891> * The client secret is stored securely in your system keychain (macOS) or a credentials file, not in your config
892> * You can set the client secret only when you add the server. When you authenticate with `claude mcp login` or from `/mcp`, Claude Code uses the stored secret and doesn't prompt for one or read `MCP_CLIENT_SECRET`
893> * To add or change the secret later, remove the server with `claude mcp remove <name>`, then add it again with `--client-secret` and the same `--scope`
894> * If the server uses a public OAuth client with no secret, use only `--client-id` without `--client-secret`
895> * These flags only apply to HTTP and SSE transports. They have no effect on stdio servers
896> * Use `claude mcp get <name>` to verify that OAuth credentials are configured for a server
911897
912898### Override OAuth metadata discovery
913899
from line 1040
10541040
10551041If you have a JSON configuration for an MCP server, you can add it directly:
10561042
1057<Steps>
1058 <Step title="Add an MCP server from JSON">
1059 ```bash theme={null}
1060 # Basic syntax
1061 claude mcp add-json <name> '<json>'
1062
1063 # Example: Adding an HTTP server with JSON configuration
1064 claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'
1065
1066 # Example: Adding a stdio server with JSON configuration
1067 claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'
1068
1069 # Example: Adding an HTTP server with pre-configured OAuth credentials
1070 claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret
1071 ```
1072 </Step>
1073
1074 <Step title="Verify the server was added">
1075 ```bash theme={null}
1076 claude mcp get weather-api
1077 ```
1078 </Step>
1079</Steps>
1080
1081<Tip>
1082 Tips:
1083
1084 * Make sure the JSON is properly escaped in your shell
1085 * The JSON must conform to the MCP server configuration schema
1086 * You can use `--scope user` to add the server to your user configuration instead of the project-specific one
1087</Tip>
1043**1. Add an MCP server from JSON**
1044
1045```bash theme={null}
1046# Basic syntax
1047claude mcp add-json <name> '<json>'
1048
1049# Example: Adding an HTTP server with JSON configuration
1050claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'
1051
1052# Example: Adding a stdio server with JSON configuration
1053claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'
1054
1055# Example: Adding an HTTP server with pre-configured OAuth credentials
1056claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret
1057```
1058
1059**2. Verify the server was added**
1060
1061```bash theme={null}
1062claude mcp get weather-api
1063```
1064
1065> [!TIP]
1066>
1067> Tips:
1068>
1069> * Make sure the JSON is properly escaped in your shell
1070> * The JSON must conform to the MCP server configuration schema
1071> * You can use `--scope user` to add the server to your user configuration instead of the project-specific one
10881072
10891073## Import MCP servers from Claude Desktop
10901074
10911075If you've already configured MCP servers in Claude Desktop, you can import them:
10921076
1093<Steps>
1094 <Step title="Import servers from Claude Desktop">
1095 ```bash theme={null}
1096 # Basic syntax
1097 claude mcp add-from-claude-desktop
1098 ```
1099 </Step>
1100
1101 <Step title="Select which servers to import">
1102 After running the command, you'll see an interactive dialog that allows you to select which servers you want to import.
1103 </Step>
1104
1105 <Step title="Verify the servers were imported">
1106 ```bash theme={null}
1107 claude mcp list
1108 ```
1109 </Step>
1110</Steps>
1077**1. Import servers from Claude Desktop**
1078
1079```bash theme={null}
1080# Basic syntax
1081claude mcp add-from-claude-desktop
1082```
1083
1084**2. Select which servers to import**
1085
1086After running the command, you'll see an interactive dialog that allows you to select which servers you want to import.
1087
1088**3. Verify the servers were imported**
1089
1090```bash theme={null}
1091claude mcp list
1092```
11111093
11121094Server names added through `claude mcp` commands can contain only letters, numbers, hyphens, and underscores. Claude Desktop doesn't apply that restriction, so a Claude Desktop server whose name contains any other character, such as a space, can't be imported. The import reports each name it rejects and still imports the other servers you selected.
11131095
1114<Tip>
1115 Tips:
1116
1117 * This feature only works on macOS and Windows Subsystem for Linux (WSL)
1118 * It reads the Claude Desktop configuration file from its standard location on those platforms
1119 * Use the `--scope user` flag to add servers to your user configuration
1120 * Imported servers keep the same names as in Claude Desktop when the name contains only letters, numbers, hyphens, and underscores. Claude Code reports a server whose name contains any other character and skips it
1121 * If servers with the same names already exist, they get a numerical suffix (for example, `server_1`)
1122</Tip>
1096> [!TIP]
1097>
1098> Tips:
1099>
1100> * This feature only works on macOS and Windows Subsystem for Linux (WSL)
1101> * It reads the Claude Desktop configuration file from its standard location on those platforms
1102> * Use the `--scope user` flag to add servers to your user configuration
1103> * Imported servers keep the same names as in Claude Desktop when the name contains only letters, numbers, hyphens, and underscores. Claude Code reports a server whose name contains any other character and skips it
1104> * If servers with the same names already exist, they get a numerical suffix (for example, `server_1`)
11231105
11241106## Use MCP servers from claude.ai
11251107
11261108If you've logged into Claude Code with a [claude.ai](https://claude.ai) account, MCP servers you've added in claude.ai, known as [connectors](https://claude.com/docs/connectors), are automatically available in Claude Code:
11271109
1128<Steps>
1129 <Step title="Configure MCP servers in claude.ai">
1130 Add servers at [claude.ai/customize/connectors](https://claude.ai/customize/connectors). On Team and Enterprise plans, only admins can add servers.
1131 </Step>
1132
1133 <Step title="Authenticate the MCP server">
1134 Complete any required authentication steps in claude.ai.
1135 </Step>
1136
1137 <Step title="View and manage servers in Claude Code">
1138 In Claude Code, use the command:
1139
1140 ```text wrap theme={null}
1141 /mcp
1142 ```
1143
1144 Servers from claude.ai appear in the list with indicators showing they come from claude.ai.
1145 </Step>
1146</Steps>
1110**1. Configure MCP servers in claude.ai**
1111
1112Add servers at [claude.ai/customize/connectors](https://claude.ai/customize/connectors). On Team and Enterprise plans, only admins can add servers.
1113
1114**2. Authenticate the MCP server**
1115
1116Complete any required authentication steps in claude.ai.
1117
1118**3. View and manage servers in Claude Code**
1119
1120In Claude Code, use the command:
1121
1122```text wrap theme={null}
1123/mcp
1124```
1125
1126Servers from claude.ai appear in the list with indicators showing they come from claude.ai.
11471127
11481128Anthropic also provides some connectors itself, without you or an admin adding them. On accounts where [Claude Docs](/docs/en/artifacts#write-a-document-with-claude-docs) is available, `/mcp` lists `claude.ai Claude Docs` with no setup, and Claude uses it when you ask for a document meant for other people. To turn it off, add a `serverName` entry of `"claude.ai Claude Docs"` to `deniedMcpServers` or use the `/mcp` toggle, both described in [Disable claude.ai connectors](#disable-claude-ai-connectors).
11491129
from line 1225
12451225}
12461226```
12471227
1248<Warning>
1249 **Configuring the executable path**: the `command` field must reference the Claude Code executable. If the `claude` command is not in your system's PATH, you'll need to specify the full path to the executable.
1250
1251 To find the full path:
1252
1253 ```bash theme={null}
1254 which claude
1255 ```
1256
1257 Then use the full path in your configuration:
1258
1259 ```json theme={null}
1260 {
1261 "mcpServers": {
1262 "claude-code": {
1263 "type": "stdio",
1264 "command": "/full/path/to/claude",
1265 "args": ["mcp", "serve"],
1266 "env": {}
1267 }
1268 }
1269 }
1270 ```
1271
1272 Without the correct executable path, you'll encounter errors like `spawn claude ENOENT`.
1273</Warning>
1274
1275<Tip>
1276 Tips:
1277
1278 * In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.
1279 * This MCP server only exposes Claude Code's tools to your MCP client, so your own client is responsible for implementing user confirmation for individual tool calls.
1280</Tip>
1228> [!WARNING]
1229>
1230> **Configuring the executable path**: the `command` field must reference the Claude Code executable. If the `claude` command is not in your system's PATH, you'll need to specify the full path to the executable.
1231>
1232> To find the full path:
1233>
1234> ```bash theme={null}
1235> which claude
1236> ```
1237>
1238> Then use the full path in your configuration:
1239>
1240> ```json theme={null}
1241> {
1242> "mcpServers": {
1243> "claude-code": {
1244> "type": "stdio",
1245> "command": "/full/path/to/claude",
1246> "args": ["mcp", "serve"],
1247> "env": {}
1248> }
1249> }
1250> }
1251> ```
1252>
1253> Without the correct executable path, you'll encounter errors like `spawn claude ENOENT`.
1254
1255> [!TIP]
1256>
1257> Tips:
1258>
1259> * In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.
1260> * This MCP server only exposes Claude Code's tools to your MCP client, so your own client is responsible for implementing user confirmation for individual tool calls.
12811261
12821262When the JSON text in a Bash or PowerShell tool call's result includes a `backgroundOutputPath` field, the call left its command running [in the background](/docs/en/tools-reference#background-commands), such as when the call set `run_in_background: true` or the command reached its timeout. The field gives the path of the command's output file. Nothing notifies your client when the command finishes, and the file gets no closing line when it does, so reading the file shows the output written so far. To detect the end, append a marker to the command, such as `npm test; echo DONE`, and look for it in the file. The `backgroundOutputPath` field requires Claude Code v2.1.295 or later.
12831263
from line 1392
14121392
14131393### Reference MCP resources
14141394
1415<Steps>
1416 <Step title="List available resources">
1417 Type `@` in your prompt to see available resources from all connected MCP servers. Resources appear alongside files in the autocomplete menu.
1418 </Step>
1419
1420 <Step title="Reference a specific resource">
1421 Use the format `@server:protocol://resource/path` to reference a resource:
1422
1423 ```text wrap theme={null}
1424 Can you analyze @github:issue://123 and suggest a fix?
1425 ```
1426
1427 ```text wrap theme={null}
1428 Please review the API documentation at @docs:file://api/authentication
1429 ```
1430 </Step>
1431
1432 <Step title="Multiple resource references">
1433 You can reference multiple resources in a single prompt:
1434
1435 ```text wrap theme={null}
1436 Compare @postgres:schema://users with @docs:file://database/user-model
1437 ```
1438 </Step>
1439</Steps>
1440
1441<Tip>
1442 Tips:
1443
1444 * Resources are automatically fetched and included as attachments when referenced
1445 * Resource paths are fuzzy-searchable in the @ mention autocomplete
1446 * Claude Code automatically provides tools to list and read MCP resources when servers support them
1447 * Resources can contain any type of content that the MCP server provides (text, JSON, structured data, etc.)
1448</Tip>
1395**1. List available resources**
1396
1397Type `@` in your prompt to see available resources from all connected MCP servers. Resources appear alongside files in the autocomplete menu.
1398
1399**2. Reference a specific resource**
1400
1401Use the format `@server:protocol://resource/path` to reference a resource:
1402
1403```text wrap theme={null}
1404Can you analyze @github:issue://123 and suggest a fix?
1405```
1406
1407```text wrap theme={null}
1408Please review the API documentation at @docs:file://api/authentication
1409```
1410
1411**3. Multiple resource references**
1412
1413You can reference multiple resources in a single prompt:
1414
1415```text wrap theme={null}
1416Compare @postgres:schema://users with @docs:file://database/user-model
1417```
1418
1419> [!TIP]
1420>
1421> Tips:
1422>
1423> * Resources are automatically fetched and included as attachments when referenced
1424> * Resource paths are fuzzy-searchable in the @ mention autocomplete
1425> * Claude Code automatically provides tools to list and read MCP resources when servers support them
1426> * Resources can contain any type of content that the MCP server provides (text, JSON, structured data, etc.)
14491427
14501428MCP Apps UI resources are entries with a `ui://` URI or the `text/html;profile=mcp-app` media type: pages for a host application to render rather than content for Claude to read. They don't appear in the `@` suggestions or in the resource list tool's results, and a server that offers only UI resources shows an empty resource list. Reading a UI resource by its URI still works.
14511429
from line 1431
14531431
14541432Tool search keeps MCP context usage low by deferring tool definitions until Claude needs them. Only tool names and server instructions load at session start, so adding more MCP servers has minimal impact on your context window. Claude Code doesn't impose a fixed per-server tool cap; the practical limit is your context window budget.
14551433
1456<Note>
1457 Tool search isn't supported on Microsoft Foundry [deployments hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options), which reject it server-side: Claude Code detects the rejection and loads MCP tools upfront for that deployment instead. [`ENABLE_TOOL_SEARCH`](#configure-tool-search) can't override this, since the rejection comes from the deployment itself.
1458</Note>
1459
1460<span id="for-mcp-server-authors" />
1434> [!NOTE]
1435>
1436> Tool search isn't supported on Microsoft Foundry [deployments hosted on Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options), which reject it server-side: Claude Code detects the rejection and loads MCP tools upfront for that deployment instead. [`ENABLE_TOOL_SEARCH`](#configure-tool-search) can't override this, since the rejection comes from the deployment itself.
14611437
14621438### Tool search for MCP server authors
14631439
from line 1456
14801456
14811457Descriptions and instructions from some of the MCP servers that Anthropic hosts at `api.anthropic.com` reach Claude in full. To change the limits for the other MCP servers in your session, set [`CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH`](/docs/en/env-vars#variables) to a number of characters. The number you set replaces both limits: `8192`, for example, raises the shorter limit and lowers the longer one. This variable requires Claude Code v2.1.280 or later.
14821458
1483<h4 id="per-tool-alwaysload">
1484 Mark a tool to load upfront or stay deferred
1485</h4>
1459#### Mark a tool to load upfront or stay deferred
14861460
14871461To control how one of your server's tools loads, set `"anthropic/alwaysLoad"` in that tool's `_meta` object. The person who adds your server to Claude Code can also set [`alwaysLoad`](#exempt-a-server-from-deferral) for the whole server in their configuration, and their setting can override yours:
14881462
from line 1544
15701544
15711545Setting `alwaysLoad: true` also makes startup wait for the server's tools, capped at the standard 5-second connect timeout, since they must be present when the first prompt is built. A remote server with a valid [`cached` entry](#server-status-detail) supplies its tools from the cache without connecting, so it doesn't hold startup. Other servers connect in the background by default; set [`MCP_CONNECTION_NONBLOCKING=0`](/docs/en/env-vars) to make startup wait for them too.
15721546
1573<h3 id="defer-a-servers-tools">
1574 Defer a server's tools
1575</h3>
1547### Defer a server's tools
15761548
15771549To keep all of a server's tools behind tool search, set `"alwaysLoad": false` in that server's entry in your MCP configuration. That includes tools that the server's author has [marked to load upfront](#per-tool-alwaysload). If you leave `alwaysLoad` out, those marked tools load upfront. Requires Claude Code v2.1.287 or later.
15781550
from line 1556
15841556
15851557### Execute MCP prompts
15861558
1587<Steps>
1588 <Step title="Discover available prompts">
1589 Type `/` to see the commands available to you, including those from MCP servers. Claude Code lists each MCP prompt as `/servername:promptname (MCP)`. Typing `/mcp__servername__promptname` also runs it.
1590 </Step>
1591
1592 <Step title="Execute a prompt without arguments">
1593 ```text wrap theme={null}
1594 /mcp__github__list_prs
1595 ```
1596 </Step>
1597
1598 <Step title="Execute a prompt with arguments">
1599 Many prompts accept arguments. Pass them space-separated after the command. Claude Code splits the arguments on whitespace, so each argument is a single token:
1600
1601 ```text wrap theme={null}
1602 /mcp__github__pr_review 456
1603 ```
1604
1605 ```text wrap theme={null}
1606 /mcp__jira__create_issue login-bug high
1607 ```
1608 </Step>
1609</Steps>
1610
1611<Tip>
1612 Tips:
1613
1614 * MCP prompts are dynamically discovered from connected servers
1615 * Arguments are parsed based on the prompt's defined parameters
1616 * Prompt results are injected directly into the conversation
1617 * In the `/mcp__servername__promptname` form, Claude Code replaces any character in the server name outside `A-Z`, `a-z`, `0-9`, `_`, and `-` with `_`, and uses the prompt name as the server declares it
1618</Tip>
1559**1. Discover available prompts**
1560
1561Type `/` to see the commands available to you, including those from MCP servers. Claude Code lists each MCP prompt as `/servername:promptname (MCP)`. Typing `/mcp__servername__promptname` also runs it.
1562
1563**2. Execute a prompt without arguments**
1564
1565```text wrap theme={null}
1566/mcp__github__list_prs
1567```
1568
1569**3. Execute a prompt with arguments**
1570
1571Many prompts accept arguments. Pass them space-separated after the command. Claude Code splits the arguments on whitespace, so each argument is a single token:
1572
1573```text wrap theme={null}
1574/mcp__github__pr_review 456
1575```
1576
1577```text wrap theme={null}
1578/mcp__jira__create_issue login-bug high
1579```
1580
1581> [!TIP]
1582>
1583> Tips:
1584>
1585> * MCP prompts are dynamically discovered from connected servers
1586> * Arguments are parsed based on the prompt's defined parameters
1587> * Prompt results are injected directly into the conversation
1588> * In the `/mcp__servername__promptname` form, Claude Code replaces any character in the server name outside `A-Z`, `a-z`, `0-9`, `_`, and `-` with `_`, and uses the prompt name as the server declares it
16191589
16201590## Managed MCP configuration
16211591
16221592
No line in this hunk matches that.