mcp.md +570 −84
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
1# Connect Claude Code to tools via MCP5# Connect Claude Code to tools via MCP
2 6
3> Learn how to connect Claude Code to your tools with the Model Context Protocol.7> Learn how to connect Claude Code to your tools with the Model Context Protocol.
4 8
59Claude Code can connect to hundreds of external tools and data sources through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open-source standard for AI-tool integrations. MCP servers give Claude Code access to your tools, databases, and APIs.
10Claude Code can connect to hundreds of external tools and data sources through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), an open source standard for AI-tool integrations. MCP servers give Claude Code access to your tools, databases, and APIs.
6 11
7## What you can do with MCP12## What you can do with MCP
8 13
10 15
11* **Implement features from issue trackers**: "Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub."16* **Implement features from issue trackers**: "Add the feature described in JIRA issue ENG-4521 and create a PR on GitHub."
12* **Analyze monitoring data**: "Check Sentry and Statsig to check the usage of the feature described in ENG-4521."17* **Analyze monitoring data**: "Check Sentry and Statsig to check the usage of the feature described in ENG-4521."
1318* **Query databases**: "Find emails of 10 random users who used feature ENG-4521, based on our Postgres database."* **Query databases**: "Find emails of 10 random users who used feature ENG-4521, based on our PostgreSQL database."
14* **Integrate designs**: "Update our standard email template based on the new Figma designs that were posted in Slack"19* **Integrate designs**: "Update our standard email template based on the new Figma designs that were posted in Slack"
15* **Automate workflows**: "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."20* **Automate workflows**: "Create Gmail drafts inviting these 10 users to a feedback session about the new feature."
21* **React to external events**: An MCP server can also act as a [channel](/en/channels) that pushes messages into your session, so Claude reacts to Telegram messages, Discord chats, or webhook events while you're away.
16 22
17## Popular MCP servers23## Popular MCP servers
18 24
76 82
77```bash theme={null}83```bash theme={null}
78# Basic syntax84# Basic syntax
7985claude mcp add --transport stdio <name> <command> [args...]claude mcp add [options] <name> -- <command> [args...]
80 86
81# Real example: Add Airtable server87# Real example: Add Airtable server
8288claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=YOUR_KEY \claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
83 -- npx -y airtable-mcp-server89 -- npx -y airtable-mcp-server
84```90```
85 91
86<Note>92<Note>
8793 **Understanding the "--" parameter:** **Important: Option ordering**
8894 The `--` (double dash) separates Claude's own CLI flags from the command and arguments that get passed to the MCP server. Everything before `--` are options for Claude (like `--env`, `--scope`), and everything after `--` is the actual command to run the MCP server.
95 All options (`--transport`, `--env`, `--scope`, `--header`) must come **before** the server name. The `--` (double dash) then separates the server name from the command and arguments that get passed to the MCP server.
89 96
90 For example:97 For example:
91 98
92 * `claude mcp add --transport stdio myserver -- npx server` → runs `npx server`99 * `claude mcp add --transport stdio myserver -- npx server` → runs `npx server`
93100 * `claude mcp add --transport stdio myserver --env KEY=value -- python server.py --port 8080` → runs `python server.py --port 8080` with `KEY=value` in environment * `claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080` → runs `python server.py --port 8080` with `KEY=value` in environment
94 101
95 This prevents conflicts between Claude's flags and the server's flags.102 This prevents conflicts between Claude's flags and the server's flags.
96</Note>103</Note>
113/mcp120/mcp
114```121```
115 122
123### Dynamic tool updates
124
125Claude Code supports MCP `list_changed` notifications, allowing MCP servers to dynamically update their available tools, prompts, and resources without requiring you to disconnect and reconnect. When an MCP server sends a `list_changed` notification, Claude Code automatically refreshes the available capabilities from that server.
126
127### Push messages with channels
128
129An MCP server can also push messages directly into your session so Claude can react to external events like CI results, monitoring alerts, or chat messages. To enable this, your server declares the `claude/channel` capability and you opt it in with the `--channels` flag at startup. See [Channels](/en/channels) to use an officially supported channel, or [Channels reference](/en/channels-reference) to build your own.
130
116<Tip>131<Tip>
117 Tips:132 Tips:
118 133
120 * `local` (default): Available only to you in the current project (was called `project` in older versions)135 * `local` (default): Available only to you in the current project (was called `project` in older versions)
121 * `project`: Shared with everyone in the project via `.mcp.json` file136 * `project`: Shared with everyone in the project via `.mcp.json` file
122 * `user`: Available to you across all projects (was called `global` in older versions)137 * `user`: Available to you across all projects (was called `global` in older versions)
123138 * Set environment variables with `--env` flags (e.g., `--env KEY=value`) * Set environment variables with `--env` flags (for example, `--env KEY=value`)
124139 * Configure MCP server startup timeout using the MCP\_TIMEOUT environment variable (e.g., `MCP_TIMEOUT=10000 claude` sets a 10-second timeout) * Configure MCP server startup timeout using the MCP\_TIMEOUT environment variable (for example, `MCP_TIMEOUT=10000 claude` sets a 10-second timeout)
125140 * Claude Code will display a warning when MCP tool output exceeds 10,000 tokens. To increase this limit, set the `MAX_MCP_OUTPUT_TOKENS` environment variable (e.g., `MAX_MCP_OUTPUT_TOKENS=50000`) * Claude Code will display a warning when MCP tool output exceeds 10,000 tokens. To increase this limit, set the `MAX_MCP_OUTPUT_TOKENS` environment variable (for example, `MAX_MCP_OUTPUT_TOKENS=50000`)
126 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication141 * Use `/mcp` to authenticate with remote servers that require OAuth 2.0 authentication
127</Tip>142</Tip>
128 143
154 169
155```json theme={null}170```json theme={null}
156{171{
172 "mcpServers": {
157 "database-tools": {173 "database-tools": {
158 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",174 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
159 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],175 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
161 "DB_URL": "${DB_URL}"177 "DB_URL": "${DB_URL}"
162 }178 }
163 }179 }
180 }
164}181}
165```182```
166 183
180 197
181**Plugin MCP features**:198**Plugin MCP features**:
182 199
183200* **Automatic lifecycle**: Servers start when plugin enables, but you must restart Claude Code to apply MCP server changes (enabling or disabling)* **Automatic lifecycle**: At session startup, servers for enabled plugins connect automatically. If you enable or disable a plugin during a session, run `/reload-plugins` to connect or disconnect its MCP servers
184201* **Environment variables**: Use `${CLAUDE_PLUGIN_ROOT}` for plugin-relative paths* **Environment variables**: use `${CLAUDE_PLUGIN_ROOT}` for bundled plugin files and `${CLAUDE_PLUGIN_DATA}` for [persistent state](/en/plugins-reference#persistent-data-directory) that survives plugin updates
185* **User environment access**: Access to same environment variables as manually configured servers202* **User environment access**: Access to same environment variables as manually configured servers
186* **Multiple transport types**: Support stdio, SSE, and HTTP transports (transport support may vary by server)203* **Multiple transport types**: Support stdio, SSE, and HTTP transports (transport support may vary by server)
187 204
208 225
209### Local scope226### Local scope
210 227
211228Local-scoped servers represent the default configuration level and are stored in your project-specific user settings. These servers remain private to you and are only accessible when working within the current project directory. This scope is ideal for personal development servers, experimental configurations, or servers containing sensitive credentials that shouldn't be shared.Local-scoped servers represent the default configuration level and are stored in `~/.claude.json` under your project's path. These servers remain private to you and are only accessible when working within the current project directory. This scope is ideal for personal development servers, experimental configurations, or servers containing sensitive credentials that shouldn't be shared.
229
230<Note>
231 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](/en/settings#settings-files) for details on settings file locations.
232</Note>
212 233
213```bash theme={null}234```bash theme={null}
214# Add a local-scoped server (default)235# Add a local-scoped server (default)
245 266
246### User scope267### User scope
247 268
248269User-scoped servers provide cross-project accessibility, making them available across all projects on your machine while remaining private to your user account. This scope works well for personal utility servers, development tools, or services you frequently use across different projects.User-scoped servers are stored in `~/.claude.json` and provide cross-project accessibility, making them available across all projects on your machine while remaining private to your user account. This scope works well for personal utility servers, development tools, or services you frequently use across different projects.
249 270
250```bash theme={null}271```bash theme={null}
251# Add a user server272# Add a user server
258 279
259* **Local scope**: Personal servers, experimental configurations, or sensitive credentials specific to one project280* **Local scope**: Personal servers, experimental configurations, or sensitive credentials specific to one project
260* **Project scope**: Team-shared servers, project-specific tools, or services required for collaboration281* **Project scope**: Team-shared servers, project-specific tools, or services required for collaboration
261282* **User scope**: Personal utilities needed across multiple projects, development tools, or frequently-used services* **User scope**: Personal utilities needed across multiple projects, development tools, or frequently used services
283
284<Note>
285 **Where are MCP servers stored?**
286
287 * **User and local scope**: `~/.claude.json` (in the `mcpServers` field or under project paths)
288 * **Project scope**: `.mcp.json` in your project root (checked into source control)
289 * **Managed**: `managed-mcp.json` in system directories (see [Managed MCP configuration](#managed-mcp-configuration))
290</Note>
262 291
263### Scope hierarchy and precedence292### Scope hierarchy and precedence
264 293
265MCP server configurations follow a clear precedence hierarchy. When servers with the same name exist at multiple scopes, the system resolves conflicts by prioritizing local-scoped servers first, followed by project-scoped servers, and finally user-scoped servers. This design ensures that personal configurations can override shared ones when needed.294MCP server configurations follow a clear precedence hierarchy. When servers with the same name exist at multiple scopes, the system resolves conflicts by prioritizing local-scoped servers first, followed by project-scoped servers, and finally user-scoped servers. This design ensures that personal configurations can override shared ones when needed.
266 295
296If a server is configured both locally and through a [claude.ai connector](#use-mcp-servers-from-claude-ai), the local configuration takes precedence and the connector entry is skipped.
297
267### Environment variable expansion in `.mcp.json`298### Environment variable expansion in `.mcp.json`
268 299
269Claude Code supports environment variable expansion in `.mcp.json` files, allowing teams to share configurations while maintaining flexibility for machine-specific paths and sensitive values like API keys.300Claude Code supports environment variable expansion in `.mcp.json` files, allowing teams to share configurations while maintaining flexibility for machine-specific paths and sensitive values like API keys.
305{/* ### Example: Automate browser testing with Playwright336{/* ### Example: Automate browser testing with Playwright
306 337
307 ```bash338 ```bash
308 # 1. Add the Playwright MCP server
309 claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest339 claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest
340 ```
341
342 Then write and run browser tests:
310 343
311344 # 2. Write and run browser tests ```text
312345 > "Test if the login flow works with test@example.com" Test if the login flow works with test@example.com
313346 > "Take a screenshot of the checkout page on mobile" ```
314347 > "Verify that the search feature returns results" ```text
348 Take a screenshot of the checkout page on mobile
349 ```
350 ```text
351 Verify that the search feature returns results
315 ``` */}352 ``` */}
316 353
317### Example: Monitor errors with Sentry354### Example: Monitor errors with Sentry
318 355
319```bash theme={null}356```bash theme={null}
320# 1. Add the Sentry MCP server
321claude mcp add --transport http sentry https://mcp.sentry.dev/mcp357claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
358```
359
360Authenticate with your Sentry account:
361
362```text theme={null}
363/mcp
364```
365
366Then debug production issues:
367
368```text theme={null}
369What are the most common errors in the last 24 hours?
370```
322 371
323372# 2. Use /mcp to authenticate with your Sentry account```text theme={null}
324373> /mcpShow me the stack trace for error ID abc123
374```
325 375
326376# 3. Debug production issues```text theme={null}
327377> "What are the most common errors in the last 24 hours?"Which deployment introduced these new errors?
328> "Show me the stack trace for error ID abc123"
329> "Which deployment introduced these new errors?"
330```378```
331 379
332### Example: Connect to GitHub for code reviews380### Example: Connect to GitHub for code reviews
333 381
334```bash theme={null}382```bash theme={null}
335# 1. Add the GitHub MCP server
336claude mcp add --transport http github https://api.githubcopilot.com/mcp/383claude mcp add --transport http github https://api.githubcopilot.com/mcp/
384```
385
386Authenticate if needed by selecting "Authenticate" for GitHub:
387
388```text theme={null}
389/mcp
390```
337 391
338392# 2. In Claude Code, authenticate if neededThen work with GitHub:
339> /mcp
340# Select "Authenticate" for GitHub
341 393
342394# 3. Now you can ask Claude to work with GitHub```text theme={null}
343395> "Review PR #456 and suggest improvements"Review PR #456 and suggest improvements
344396> "Create a new issue for the bug we just found"```
345397> "Show me all open PRs assigned to me"
398```text theme={null}
399Create a new issue for the bug we just found
400```
401
402```text theme={null}
403Show me all open PRs assigned to me
346```404```
347 405
348### Example: Query your PostgreSQL database406### Example: Query your PostgreSQL database
349 407
350```bash theme={null}408```bash theme={null}
351# 1. Add the database server with your connection string
352claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \409claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
353 --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"410 --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"
411```
354 412
355413# 2. Query your database naturallyThen query your database naturally:
356414> "What's our total revenue this month?"
357415> "Show me the schema for the orders table"```text theme={null}
358416> "Find customers who haven't made a purchase in 90 days"What's our total revenue this month?
417```
418
419```text theme={null}
420Show me the schema for the orders table
421```
422
423```text theme={null}
424Find customers who haven't made a purchase in 90 days
359```425```
360 426
361## Authenticate with remote MCP servers427## Authenticate with remote MCP servers
374 <Step title="Use the /mcp command within Claude Code">440 <Step title="Use the /mcp command within Claude Code">
375 In Claude code, use the command:441 In Claude code, use the command:
376 442
377443 ``` ```text theme={null}
378444 > /mcp /mcp
379 ```445 ```
380 446
381 Then follow the steps in your browser to login.447 Then follow the steps in your browser to login.
387 453
388 * Authentication tokens are stored securely and refreshed automatically454 * Authentication tokens are stored securely and refreshed automatically
389 * Use "Clear authentication" in the `/mcp` menu to revoke access455 * Use "Clear authentication" in the `/mcp` menu to revoke access
390456 * If your browser doesn't open automatically, copy the provided URL * If your browser doesn't open automatically, copy the provided URL and open it manually
457 * 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
391 * OAuth authentication works with HTTP servers458 * OAuth authentication works with HTTP servers
392</Tip>459</Tip>
393 460
461### Use a fixed OAuth callback port
462
463Some MCP servers require a specific redirect URI registered in advance. By default, Claude Code picks a random available port for the OAuth callback. Use `--callback-port` to fix the port so it matches a pre-registered redirect URI of the form `http://localhost:PORT/callback`.
464
465You can use `--callback-port` on its own (with dynamic client registration) or together with `--client-id` (with pre-configured credentials).
466
467```bash theme={null}
468# Fixed callback port with dynamic client registration
469claude mcp add --transport http \
470 --callback-port 8080 \
471 my-server https://mcp.example.com/mcp
472```
473
474### Use pre-configured OAuth credentials
475
476Some 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.
477
478<Steps>
479 <Step title="Register an OAuth app with the server">
480 Create an app through the server's developer portal and note your client ID and client secret.
481
482 Many servers also require a redirect URI. If so, choose a port and register a redirect URI in the format `http://localhost:PORT/callback`. Use that same port with `--callback-port` in the next step.
483 </Step>
484
485 <Step title="Add the server with your credentials">
486 Choose one of the following methods. The port used for `--callback-port` can be any available port. It just needs to match the redirect URI you registered in the previous step.
487
488 <Tabs>
489 <Tab title="claude mcp add">
490 Use `--client-id` to pass your app's client ID. The `--client-secret` flag prompts for the secret with masked input:
491
492 ```bash theme={null}
493 claude mcp add --transport http \
494 --client-id your-client-id --client-secret --callback-port 8080 \
495 my-server https://mcp.example.com/mcp
496 ```
497 </Tab>
498
499 <Tab title="claude mcp add-json">
500 Include the `oauth` object in the JSON config and pass `--client-secret` as a separate flag:
501
502 ```bash theme={null}
503 claude mcp add-json my-server \
504 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
505 --client-secret
506 ```
507 </Tab>
508
509 <Tab title="claude mcp add-json (callback port only)">
510 Use `--callback-port` without a client ID to fix the port while using dynamic client registration:
511
512 ```bash theme={null}
513 claude mcp add-json my-server \
514 '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'
515 ```
516 </Tab>
517
518 <Tab title="CI / env var">
519 Set the secret via environment variable to skip the interactive prompt:
520
521 ```bash theme={null}
522 MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
523 --client-id your-client-id --client-secret --callback-port 8080 \
524 my-server https://mcp.example.com/mcp
525 ```
526 </Tab>
527 </Tabs>
528 </Step>
529
530 <Step title="Authenticate in Claude Code">
531 Run `/mcp` in Claude Code and follow the browser login flow.
532 </Step>
533</Steps>
534
535<Tip>
536 Tips:
537
538 * The client secret is stored securely in your system keychain (macOS) or a credentials file, not in your config
539 * If the server uses a public OAuth client with no secret, use only `--client-id` without `--client-secret`
540 * `--callback-port` can be used with or without `--client-id`
541 * These flags only apply to HTTP and SSE transports. They have no effect on stdio servers
542 * Use `claude mcp get <name>` to verify that OAuth credentials are configured for a server
543</Tip>
544
545### Override OAuth metadata discovery
546
547If your MCP server's standard OAuth metadata endpoints return errors but the server exposes a working OIDC endpoint, you can point Claude Code at a specific metadata URL to bypass the default discovery chain. By default, Claude Code first checks RFC 9728 Protected Resource Metadata at `/.well-known/oauth-protected-resource`, then falls back to RFC 8414 authorization server metadata at `/.well-known/oauth-authorization-server`.
548
549Set `authServerMetadataUrl` in the `oauth` object of your server's config in `.mcp.json`:
550
551```json theme={null}
552{
553 "mcpServers": {
554 "my-server": {
555 "type": "http",
556 "url": "https://mcp.example.com/mcp",
557 "oauth": {
558 "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
559 }
560 }
561 }
562}
563```
564
565The URL must use `https://`. This option requires Claude Code v2.1.64 or later.
566
567### Use dynamic headers for custom authentication
568
569If your MCP server uses an authentication scheme other than OAuth (such as Kerberos, short-lived tokens, or an internal SSO), use `headersHelper` to generate request headers at connection time. Claude Code runs the command and merges its output into the connection headers.
570
571```json theme={null}
572{
573 "mcpServers": {
574 "internal-api": {
575 "type": "http",
576 "url": "https://mcp.internal.example.com",
577 "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
578 }
579 }
580}
581```
582
583The command can also be inline:
584
585```json theme={null}
586{
587 "mcpServers": {
588 "internal-api": {
589 "type": "http",
590 "url": "https://mcp.internal.example.com",
591 "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
592 }
593 }
594}
595```
596
597**Requirements:**
598
599* The command must write a JSON object of string key-value pairs to stdout
600* The command runs in a shell with a 10-second timeout
601* Dynamic headers override any static `headers` with the same name
602
603The helper runs fresh on each connection (at session start and on reconnect). There is no caching, so your script is responsible for any token reuse.
604
605Claude Code sets these environment variables when executing the helper:
606
607| Variable | Value |
608| :---------------------------- | :------------------------- |
609| `CLAUDE_CODE_MCP_SERVER_NAME` | the name of the MCP server |
610| `CLAUDE_CODE_MCP_SERVER_URL` | the URL of the MCP server |
611
612Use these to write a single helper script that serves multiple MCP servers.
613
614<Note>
615 `headersHelper` executes arbitrary shell commands. When defined at project or local scope, it only runs after you accept the workspace trust dialog.
616</Note>
617
394## Add MCP servers from JSON configuration618## Add MCP servers from JSON configuration
395 619
396If you have a JSON configuration for an MCP server, you can add it directly:620If you have a JSON configuration for an MCP server, you can add it directly:
406 630
407 # Example: Adding a stdio server with JSON configuration631 # Example: Adding a stdio server with JSON configuration
408 claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'632 claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'
633
634 # Example: Adding an HTTP server with pre-configured OAuth credentials
635 claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret
409 ```636 ```
410 </Step>637 </Step>
411 638
454 * It reads the Claude Desktop configuration file from its standard location on those platforms681 * It reads the Claude Desktop configuration file from its standard location on those platforms
455 * Use the `--scope user` flag to add servers to your user configuration682 * Use the `--scope user` flag to add servers to your user configuration
456 * Imported servers will have the same names as in Claude Desktop683 * Imported servers will have the same names as in Claude Desktop
457684 * If servers with the same names already exist, they will get a numerical suffix (e.g., `server_1`) * If servers with the same names already exist, they will get a numerical suffix (for example, `server_1`)
458</Tip>685</Tip>
459 686
687## Use MCP servers from Claude.ai
688
689If you've logged into Claude Code with a [Claude.ai](https://claude.ai) account, MCP servers you've added in Claude.ai are automatically available in Claude Code:
690
691<Steps>
692 <Step title="Configure MCP servers in Claude.ai">
693 Add servers at [claude.ai/settings/connectors](https://claude.ai/settings/connectors). On Team and Enterprise plans, only admins can add servers.
694 </Step>
695
696 <Step title="Authenticate the MCP server">
697 Complete any required authentication steps in Claude.ai.
698 </Step>
699
700 <Step title="View and manage servers in Claude Code">
701 In Claude Code, use the command:
702
703 ```text theme={null}
704 /mcp
705 ```
706
707 Claude.ai servers appear in the list with indicators showing they come from Claude.ai.
708 </Step>
709</Steps>
710
711To disable claude.ai MCP servers in Claude Code, set the `ENABLE_CLAUDEAI_MCP_SERVERS` environment variable to `false`:
712
713```bash theme={null}
714ENABLE_CLAUDEAI_MCP_SERVERS=false claude
715```
716
460## Use Claude Code as an MCP server717## Use Claude Code as an MCP server
461 718
462You can use Claude Code itself as an MCP server that other applications can connect to:719You can use Claude Code itself as an MCP server that other applications can connect to:
513 770
514 * The server provides access to Claude's tools like View, Edit, LS, etc.771 * The server provides access to Claude's tools like View, Edit, LS, etc.
515 * In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.772 * In Claude Desktop, try asking Claude to read files in a directory, make edits, and more.
516773 * Note that this MCP server is simply exposing Claude Code's tools to your MCP client, so your own client is responsible for implementing user confirmation for individual tool calls. * Note that this MCP server is only exposing Claude Code's tools to your MCP client, so your own client is responsible for implementing user confirmation for individual tool calls.
517</Tip>774</Tip>
518 775
519## MCP output limits and warnings776## MCP output limits and warnings
527To increase the limit for tools that produce large outputs:784To increase the limit for tools that produce large outputs:
528 785
529```bash theme={null}786```bash theme={null}
530# Set a higher limit for MCP tool outputs
531export MAX_MCP_OUTPUT_TOKENS=50000787export MAX_MCP_OUTPUT_TOKENS=50000
532claude788claude
533```789```
538* Generate detailed reports or documentation794* Generate detailed reports or documentation
539* Process extensive log files or debugging information795* Process extensive log files or debugging information
540 796
797### Override result size per tool
798
799If you're building an MCP server, you can allow individual tools to return results larger than the default limit by setting `_meta["anthropic/maxResultSizeChars"]` in the tool's `tools/list` response entry. Claude Code uses this value as the maximum result size for that tool, up to a hard ceiling of 500,000 characters.
800
801This is useful for tools that return inherently large but necessary outputs, such as database schemas or full file trees. Without the annotation, results that exceed the default limit are persisted to disk and replaced with a file reference in the conversation.
802
803```json theme={null}
804{
805 "name": "get_schema",
806 "description": "Returns the full database schema",
807 "_meta": {
808 "anthropic/maxResultSizeChars": 500000
809 }
810}
811```
812
541<Warning>813<Warning>
542814 If you frequently encounter output warnings with specific MCP servers, consider increasing the limit or configuring the server to paginate or filter its responses. If you frequently encounter output warnings with specific MCP servers you don't control, consider increasing the `MAX_MCP_OUTPUT_TOKENS` limit or asking the server author to add the `anthropic/maxResultSizeChars` annotation.
543</Warning>815</Warning>
544 816
817## Respond to MCP elicitation requests
818
819MCP servers can request structured input from you mid-task using elicitation. When a server needs information it can't get on its own, Claude Code displays an interactive dialog and passes your response back to the server. No configuration is required on your side: elicitation dialogs appear automatically when a server requests them.
820
821Servers can request input in two ways:
822
823* **Form mode**: Claude Code shows a dialog with form fields defined by the server (for example, a username and password prompt). Fill in the fields and submit.
824* **URL mode**: Claude Code opens a browser URL for authentication or approval. Complete the flow in the browser, then confirm in the CLI.
825
826To auto-respond to elicitation requests without showing a dialog, use the [`Elicitation` hook](/en/hooks#elicitation).
827
828If you're building an MCP server that uses elicitation, see the [MCP elicitation specification](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation) for protocol details and schema examples.
829
545## Use MCP resources830## Use MCP resources
546 831
547MCP servers can expose resources that you can reference using @ mentions, similar to how you reference files.832MCP servers can expose resources that you can reference using @ mentions, similar to how you reference files.
556 <Step title="Reference a specific resource">841 <Step title="Reference a specific resource">
557 Use the format `@server:protocol://resource/path` to reference a resource:842 Use the format `@server:protocol://resource/path` to reference a resource:
558 843
559844 ``` ```text theme={null}
560845 > Can you analyze @github:issue://123 and suggest a fix? Can you analyze @github:issue://123 and suggest a fix?
561 ```846 ```
562 847
563848 ``` ```text theme={null}
564849 > Please review the API documentation at @docs:file://api/authentication Please review the API documentation at @docs:file://api/authentication
565 ```850 ```
566 </Step>851 </Step>
567 852
568 <Step title="Multiple resource references">853 <Step title="Multiple resource references">
569 You can reference multiple resources in a single prompt:854 You can reference multiple resources in a single prompt:
570 855
571856 ``` ```text theme={null}
572857 > Compare @postgres:schema://users with @docs:file://database/user-model Compare @postgres:schema://users with @docs:file://database/user-model
573 ```858 ```
574 </Step>859 </Step>
575</Steps>860</Steps>
583 * Resources can contain any type of content that the MCP server provides (text, JSON, structured data, etc.)868 * Resources can contain any type of content that the MCP server provides (text, JSON, structured data, etc.)
584</Tip>869</Tip>
585 870
586871## Use MCP prompts as slash commands## Scale with MCP Tool Search
587 872
588873MCP servers can expose prompts that become available as slash commands in Claude Code.Tool search keeps MCP context usage low by deferring tool definitions until Claude needs them. Only tool names load at session start, so adding more MCP servers has minimal impact on your context window.
874
875### How it works
876
877Tool search is enabled by default. MCP tools are deferred rather than loaded into context upfront, and Claude uses a search tool to discover relevant ones when a task needs them. Only the tools Claude actually uses enter context. From your perspective, MCP tools work exactly as before.
878
879If you prefer threshold-based loading, set `ENABLE_TOOL_SEARCH=auto` to load schemas upfront when they fit within 10% of the context window and defer only the overflow. See [Configure tool search](#configure-tool-search) for all options.
880
881### For MCP server authors
882
883If you're building an MCP server, the server instructions field becomes more useful with Tool Search enabled. Server instructions help Claude understand when to search for your tools, similar to how [skills](/en/skills) work.
884
885Add clear, descriptive server instructions that explain:
886
887* What category of tasks your tools handle
888* When Claude should search for your tools
889* Key capabilities your server provides
890
891Claude Code truncates tool descriptions and server instructions at 2KB each. Keep them concise to avoid truncation, and put critical details near the start.
892
893### Configure tool search
894
895Tool search is enabled by default: MCP tools are deferred and discovered on demand. When `ANTHROPIC_BASE_URL` points to a non-first-party host, tool search is disabled by default because most proxies do not forward `tool_reference` blocks. Set `ENABLE_TOOL_SEARCH` explicitly if your proxy does. This feature requires models that support `tool_reference` blocks: Sonnet 4 and later, or Opus 4 and later. Haiku models do not support tool search.
896
897Control tool search behavior with the `ENABLE_TOOL_SEARCH` environment variable:
898
899| Value | Behavior |
900| :--------- | :----------------------------------------------------------------------------------------------------------------------------- |
901| (unset) | All MCP tools deferred and loaded on demand. Falls back to loading upfront when `ANTHROPIC_BASE_URL` is a non-first-party host |
902| `true` | All MCP tools deferred, including for non-first-party `ANTHROPIC_BASE_URL` |
903| `auto` | Threshold mode: tools load upfront if they fit within 10% of the context window, deferred otherwise |
904| `auto:<N>` | Threshold mode with a custom percentage, where `<N>` is 0-100 (e.g., `auto:5` for 5%) |
905| `false` | All MCP tools loaded upfront, no deferral |
906
907```bash theme={null}
908# Use a custom 5% threshold
909ENABLE_TOOL_SEARCH=auto:5 claude
910
911# Disable tool search entirely
912ENABLE_TOOL_SEARCH=false claude
913```
914
915Or set the value in your [settings.json `env` field](/en/settings#available-settings).
916
917You can also disable the `ToolSearch` tool specifically:
918
919```json theme={null}
920{
921 "permissions": {
922 "deny": ["ToolSearch"]
923 }
924}
925```
926
927## Use MCP prompts as commands
928
929MCP servers can expose prompts that become available as commands in Claude Code.
589 930
590### Execute MCP prompts931### Execute MCP prompts
591 932
595 </Step>936 </Step>
596 937
597 <Step title="Execute a prompt without arguments">938 <Step title="Execute a prompt without arguments">
598939 ``` ```text theme={null}
599940 > /mcp__github__list_prs /mcp__github__list_prs
600 ```941 ```
601 </Step>942 </Step>
602 943
603 <Step title="Execute a prompt with arguments">944 <Step title="Execute a prompt with arguments">
604 Many prompts accept arguments. Pass them space-separated after the command:945 Many prompts accept arguments. Pass them space-separated after the command:
605 946
606947 ``` ```text theme={null}
607948 > /mcp__github__pr_review 456 /mcp__github__pr_review 456
608 ```949 ```
609 950
610951 ``` ```text theme={null}
611952 > /mcp__jira__create_issue "Bug in login flow" high /mcp__jira__create_issue "Bug in login flow" high
612 ```953 ```
613 </Step>954 </Step>
614</Steps>955</Steps>
622 * Server and prompt names are normalized (spaces become underscores)963 * Server and prompt names are normalized (spaces become underscores)
623</Tip>964</Tip>
624 965
625966## Enterprise MCP configuration## Managed MCP configuration
967
968For organizations that need centralized control over MCP servers, Claude Code supports two configuration options:
626 969
627970For organizations that need centralized control over MCP servers, Claude Code supports enterprise-managed MCP configurations. This allows IT administrators to:1. **Exclusive control with `managed-mcp.json`**: Deploy a fixed set of MCP servers that users cannot modify or extend
9712. **Policy-based control with allowlists/denylists**: Allow users to add their own servers, but restrict which ones are permitted
972
973These options allow IT administrators to:
628 974
629* **Control which MCP servers employees can access**: Deploy a standardized set of approved MCP servers across the organization975* **Control which MCP servers employees can access**: Deploy a standardized set of approved MCP servers across the organization
630976* **Prevent unauthorized MCP servers**: Optionally restrict users from adding their own MCP servers* **Prevent unauthorized MCP servers**: Restrict users from adding unapproved MCP servers
631* **Disable MCP entirely**: Remove MCP functionality completely if needed977* **Disable MCP entirely**: Remove MCP functionality completely if needed
632 978
633979### Setting up enterprise MCP configuration### Option 1: Exclusive control with managed-mcp.json
980
981When you deploy a `managed-mcp.json` file, it takes **exclusive control** over all MCP servers. Users cannot add, modify, or use any MCP servers other than those defined in this file. This is the simplest approach for organizations that want complete control.
634 982
635983System administrators can deploy an enterprise MCP configuration file alongside the managed settings file:System administrators deploy the configuration file to a system-wide directory:
636 984
637985* **macOS**: `/Library/Application Support/ClaudeCode/managed-mcp.json`* macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json`
638986* **Windows**: `C:\ProgramData\ClaudeCode\managed-mcp.json`* Linux and WSL: `/etc/claude-code/managed-mcp.json`
639987* **Linux**: `/etc/claude-code/managed-mcp.json`* Windows: `C:\Program Files\ClaudeCode\managed-mcp.json`
988
989<Note>
990 These are system-wide paths (not user home directories like `~/Library/...`) that require administrator privileges. They are designed to be deployed by IT administrators.
991</Note>
640 992
641The `managed-mcp.json` file uses the same format as a standard `.mcp.json` file:993The `managed-mcp.json` file uses the same format as a standard `.mcp.json` file:
642 994
663}1015}
664```1016```
665 1017
6661018### Restricting MCP servers with allowlists and denylists### Option 2: Policy-based control with allowlists and denylists
1019
1020Instead of taking exclusive control, administrators can allow users to configure their own MCP servers while enforcing restrictions on which servers are permitted. This approach uses `allowedMcpServers` and `deniedMcpServers` in the [managed settings file](/en/settings#settings-files).
1021
1022<Note>
1023 **Choosing between options**: Use Option 1 (`managed-mcp.json`) when you want to deploy a fixed set of servers with no user customization. Use Option 2 (allowlists/denylists) when you want to allow users to add their own servers within policy constraints.
1024</Note>
1025
1026#### Restriction options
1027
1028Each entry in the allowlist or denylist can restrict servers in three ways:
667 1029
6681030In addition to providing enterprise-managed servers, administrators can control which MCP servers users are allowed to configure using `allowedMcpServers` and `deniedMcpServers` in the `managed-settings.json` file:1. **By server name** (`serverName`): Matches the configured name of the server
10312. **By command** (`serverCommand`): Matches the exact command and arguments used to start stdio servers
10323. **By URL pattern** (`serverUrl`): Matches remote server URLs with wildcard support
669 1033
6701034* **macOS**: `/Library/Application Support/ClaudeCode/managed-settings.json`**Important**: Each entry must have exactly one of `serverName`, `serverCommand`, or `serverUrl`.
6711035* **Windows**: `C:\ProgramData\ClaudeCode\managed-settings.json`
6721036* **Linux**: `/etc/claude-code/managed-settings.json`#### Example configuration
673 1037
674```json theme={null}1038```json theme={null}
675{1039{
676 "allowedMcpServers": [1040 "allowedMcpServers": [
1041 // Allow by server name
677 { "serverName": "github" },1042 { "serverName": "github" },
678 { "serverName": "sentry" },1043 { "serverName": "sentry" },
6791044 { "serverName": "company-internal" }
1045 // Allow by exact command (for stdio servers)
1046 { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
1047 { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },
1048
1049 // Allow by URL pattern (for remote servers)
1050 { "serverUrl": "https://mcp.company.com/*" },
1051 { "serverUrl": "https://*.internal.corp/*" }
680 ],1052 ],
681 "deniedMcpServers": [1053 "deniedMcpServers": [
6821054 { "serverName": "filesystem" } // Block by server name
1055 { "serverName": "dangerous-server" },
1056
1057 // Block by exact command (for stdio servers)
1058 { "serverCommand": ["npx", "-y", "unapproved-package"] },
1059
1060 // Block by URL pattern (for remote servers)
1061 { "serverUrl": "https://*.untrusted.com/*" }
683 ]1062 ]
684}1063}
685```1064```
686 1065
6871066**Allowlist behavior (`allowedMcpServers`)**:#### How command-based restrictions work
1067
1068**Exact matching**:
1069
1070* Command arrays must match **exactly** - both the command and all arguments in the correct order
1071* Example: `["npx", "-y", "server"]` will NOT match `["npx", "server"]` or `["npx", "-y", "server", "--flag"]`
1072
1073**Stdio server behavior**:
1074
1075* When the allowlist contains **any** `serverCommand` entries, stdio servers **must** match one of those commands
1076* Stdio servers cannot pass by name alone when command restrictions are present
1077* This ensures administrators can enforce which commands are allowed to run
1078
1079**Non-stdio server behavior**:
1080
1081* Remote servers (HTTP, SSE, WebSocket) use URL-based matching when `serverUrl` entries exist in the allowlist
1082* If no URL entries exist, remote servers fall back to name-based matching
1083* Command restrictions do not apply to remote servers
1084
1085#### How URL-based restrictions work
1086
1087URL patterns support wildcards using `*` to match any sequence of characters. This is useful for allowing entire domains or subdomains.
1088
1089**Wildcard examples**:
1090
1091* `https://mcp.company.com/*` - Allow all paths on a specific domain
1092* `https://*.example.com/*` - Allow any subdomain of example.com
1093* `http://localhost:*/*` - Allow any port on localhost
1094
1095**Remote server behavior**:
1096
1097* When the allowlist contains **any** `serverUrl` entries, remote servers **must** match one of those URL patterns
1098* Remote servers cannot pass by name alone when URL restrictions are present
1099* This ensures administrators can enforce which remote endpoints are allowed
1100
1101<Accordion title="Example: URL-only allowlist">
1102 ```json theme={null}
1103 {
1104 "allowedMcpServers": [
1105 { "serverUrl": "https://mcp.company.com/*" },
1106 { "serverUrl": "https://*.internal.corp/*" }
1107 ]
1108 }
1109 ```
1110
1111 **Result**:
1112
1113 * HTTP server at `https://mcp.company.com/api`: ✅ Allowed (matches URL pattern)
1114 * HTTP server at `https://api.internal.corp/mcp`: ✅ Allowed (matches wildcard subdomain)
1115 * HTTP server at `https://external.com/mcp`: ❌ Blocked (doesn't match any URL pattern)
1116 * Stdio server with any command: ❌ Blocked (no name or command entries to match)
1117</Accordion>
1118
1119<Accordion title="Example: Command-only allowlist">
1120 ```json theme={null}
1121 {
1122 "allowedMcpServers": [
1123 { "serverCommand": ["npx", "-y", "approved-package"] }
1124 ]
1125 }
1126 ```
1127
1128 **Result**:
1129
1130 * Stdio server with `["npx", "-y", "approved-package"]`: ✅ Allowed (matches command)
1131 * Stdio server with `["node", "server.js"]`: ❌ Blocked (doesn't match command)
1132 * HTTP server named "my-api": ❌ Blocked (no name entries to match)
1133</Accordion>
1134
1135<Accordion title="Example: Mixed name and command allowlist">
1136 ```json theme={null}
1137 {
1138 "allowedMcpServers": [
1139 { "serverName": "github" },
1140 { "serverCommand": ["npx", "-y", "approved-package"] }
1141 ]
1142 }
1143 ```
1144
1145 **Result**:
1146
1147 * Stdio server named "local-tool" with `["npx", "-y", "approved-package"]`: ✅ Allowed (matches command)
1148 * Stdio server named "local-tool" with `["node", "server.js"]`: ❌ Blocked (command entries exist but doesn't match)
1149 * Stdio server named "github" with `["node", "server.js"]`: ❌ Blocked (stdio servers must match commands when command entries exist)
1150 * HTTP server named "github": ✅ Allowed (matches name)
1151 * HTTP server named "other-api": ❌ Blocked (name doesn't match)
1152</Accordion>
1153
1154<Accordion title="Example: Name-only allowlist">
1155 ```json theme={null}
1156 {
1157 "allowedMcpServers": [
1158 { "serverName": "github" },
1159 { "serverName": "internal-tool" }
1160 ]
1161 }
1162 ```
1163
1164 **Result**:
1165
1166 * Stdio server named "github" with any command: ✅ Allowed (no command restrictions)
1167 * Stdio server named "internal-tool" with any command: ✅ Allowed (no command restrictions)
1168 * HTTP server named "github": ✅ Allowed (matches name)
1169 * Any server named "other": ❌ Blocked (name doesn't match)
1170</Accordion>
1171
1172#### Allowlist behavior (`allowedMcpServers`)
688 1173
689* `undefined` (default): No restrictions - users can configure any MCP server1174* `undefined` (default): No restrictions - users can configure any MCP server
690* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers1175* Empty array `[]`: Complete lockdown - users cannot configure any MCP servers
6911176* List of server names: Users can only configure the specified servers* List of entries: Users can only configure servers that match by name, command, or URL pattern
692 1177
6931178**Denylist behavior (`deniedMcpServers`)**:#### Denylist behavior (`deniedMcpServers`)
694 1179
695* `undefined` (default): No servers are blocked1180* `undefined` (default): No servers are blocked
696* Empty array `[]`: No servers are blocked1181* Empty array `[]`: No servers are blocked
6971182* List of server names: Specified servers are explicitly blocked across all scopes* List of entries: Specified servers are explicitly blocked across all scopes
698 1183
6991184**Important notes**:#### Important notes
700 1185
7011186* These restrictions apply to all scopes: user, project, local, and even enterprise servers from `managed-mcp.json`* **Option 1 and Option 2 can be combined**: If `managed-mcp.json` exists, it has exclusive control and users cannot add servers. Allowlists/denylists still apply to the managed servers themselves.
7021187* **Denylist takes absolute precedence**: If a server appears in both lists, it will be blocked* **Denylist takes absolute precedence**: If a server matches a denylist entry (by name, command, or URL), it will be blocked even if it's on the allowlist
1188* Name-based, command-based, and URL-based restrictions work together: a server passes if it matches **either** a name entry, a command entry, or a URL pattern (unless blocked by denylist)
703 1189
704<Note>1190<Note>
7051191 **Enterprise configuration precedence**: The enterprise MCP configuration has the highest precedence and cannot be overridden by user, local, or project configurations. **When using `managed-mcp.json`**: Users cannot add MCP servers through `claude mcp add` or configuration files. The `allowedMcpServers` and `deniedMcpServers` settings still apply to filter which managed servers are actually loaded.
706</Note>1192</Note>