One read of Model Context Protocolmcp-20261022T203719Z
295 pages moved out of 357 read.
Pages moved
295
significant first
Pages read
357
in this capture
Captured
20:37 UTC
Corpus hash
3ef457b31340
full-sweep
What this read moved
101-125 of 295, page 5 of 12This capture is too large to show at once. Changes 101-125 of 295 are below, significant first; the rest are on the following screens.
docs/draft/getting-started/intro Changed · +6 / -6 lines
from line 29
2929
3030## Start Building
3131
32> **[Build servers](/docs/draft/develop/build-server)**
32> **[Build servers](/docs/draft/develop/build-server.md)**
3333>
3434> Create MCP servers to expose your data and tools
3535
36> **[Build clients](/docs/draft/develop/build-client)**
36> **[Build clients](/docs/draft/develop/build-client.md)**
3737>
3838> Develop applications that connect to MCP servers
3939
40> **[Build MCP Apps](/extensions/apps/overview)**
40> **[Build MCP Apps](/extensions/apps/overview.md)**
4141>
4242> Build interactive apps that run inside AI clients
4343
4444## Learn more
4545
46> **[Architecture](/docs/draft/learn/architecture)**
46> **[Architecture](/docs/draft/learn/architecture.md)**
4747>
4848> Learn the core concepts and architecture of MCP
4949
50> **[Security](/docs/draft/tutorials/security/security_best_practices)**
50> **[Security](/docs/draft/tutorials/security/security_best_practices.md)**
5151>
5252> Understand the security considerations and best practices for MCP
5353
5454## Community
5555
56> **[Contributing](/community/contributing)**
56> **[Contributing](/community/contributing.md)**
5757>
5858> Learn how to get involved and contribute to MCP
5959
docs/draft/learn/architecture Changed · +13 / -13 lines
from line 4
44
55Because MCP SDKs abstract away many concerns, most developers will likely find the [data layer protocol](#data-layer-protocol) section to be the most useful. It discusses how MCP servers can provide context to an AI application.
66
7For specific implementation details, please refer to the documentation for your [language-specific SDK](/docs/draft/sdk).
7For specific implementation details, please refer to the documentation for your [language-specific SDK](/docs/draft/sdk.md).
88
99## Scope
1010
1111The Model Context Protocol includes the following projects:
1212
13* [MCP Specification](https://modelcontextprotocol.io/specification/latest): A specification of MCP that outlines the implementation requirements for clients and servers.
14* [MCP SDKs](/docs/draft/sdk): SDKs for different programming languages that implement MCP.
13* [MCP Specification](https://modelcontextprotocol.io/specification/latest.md): A specification of MCP that outlines the implementation requirements for clients and servers.
14* [MCP SDKs](/docs/draft/sdk.md): SDKs for different programming languages that implement MCP.
1515* **MCP Development Tools**: Tools for developing MCP servers and clients, including the [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
1616* [MCP Reference Server Implementations](https://github.com/modelcontextprotocol/servers): Reference implementations of MCP servers.
1717
from line 82
8282
8383* **Discovery**: Lets clients query a server's supported protocol versions, capabilities, and identity through the `server/discover` request
8484* **Server features**: Enables servers to provide core functionality including tools for AI actions, resources for context data, and prompts for interaction templates from and to the client
85* **Client features**: Enables servers to elicit input from the user. Sampling is [deprecated](/specification/draft/deprecated) as of protocol version `2026-07-28`.
85* **Client features**: Enables servers to elicit input from the user. Sampling is [deprecated](/specification/draft/deprecated.md) as of protocol version `2026-07-28`.
8686* **Utility features**: Supports additional capabilities like notifications for real-time updates and progress tracking for long-running operations
8787
8888#### Transport layer
from line 104
104104
105105#### Statelessness and discovery
106106
107MCP is a stateless protocol (Every request contains all the information needed to process it, so servers infer nothing from previous requests). Every request carries the protocol version and the capabilities (Features and operations that a client or server supports, such as tools, resources, or prompts) relevant to that request in its `_meta` field, so the server can process each request on its own. Clients should also identify themselves in the same field unless configured not to. Servers advertise their supported versions and capabilities through the mandatory [`server/discover`](/specification/draft/server/discover) request, which clients may send before any other request. Detailed information can be found in the [specification](/specification/draft/basic/index#statelessness), and the [example](#example) showcases the per-request metadata and the discovery sequence.
107MCP is a stateless protocol (Every request contains all the information needed to process it, so servers infer nothing from previous requests). Every request carries the protocol version and the capabilities (Features and operations that a client or server supports, such as tools, resources, or prompts) relevant to that request in its `_meta` field, so the server can process each request on its own. Clients should also identify themselves in the same field unless configured not to. Servers advertise their supported versions and capabilities through the mandatory [`server/discover`](/specification/draft/server/discover) request, which clients may send before any other request. Detailed information can be found in the [specification](/specification/draft/basic/index.md#statelessness), and the [example](#example) showcases the per-request metadata and the discovery sequence.
108108
109109#### Primitives
110110
from line 121
121121
122122As a concrete example, consider an MCP server that provides context about a database. It can expose tools for querying the database, a resource that contains the schema of the database, and a prompt that includes few-shot examples for interacting with the tools.
123123
124For more details about server primitives see [server concepts](./server-concepts).
124For more details about server primitives see [server concepts](/docs/draft/learn/server-concepts.md).
125125
126126MCP also defines primitives that *clients* can expose. These primitives allow MCP server authors to build richer interactions.
127127
128128* **Elicitation**: Allows servers to request additional information from users. This is useful when server authors want to get more information from the user, or ask for confirmation of an action. Servers request user input with the `elicitation/create` method.
129129
130Elicitation requests are delivered through the [Multi Round-Trip Requests](/specification/draft/basic/patterns/mrtr) pattern, explained in the [elicitation overview](/docs/draft/learn/client-concepts#elicitation).
130Elicitation requests are delivered through the [Multi Round-Trip Requests](/specification/draft/basic/patterns/mrtr.md) pattern, explained in the [elicitation overview](/docs/draft/learn/client-concepts.md#elicitation).
131131
132132**Deprecated**: The following client primitives are deprecated as of protocol version `2026-07-28`.
133133
from line 134
134134* **Sampling**: Allows servers to request language model completions from the client's AI application. This is useful when server authors want access to a language model, but want to stay model-independent and not include a language model SDK in their MCP server. Servers request completions with the `sampling/createMessage` method, also delivered through the Multi Round-Trip Requests pattern. New implementations should integrate directly with LLM provider APIs.
135135* **Logging**: Enables servers to send log messages to clients for debugging and monitoring purposes. New implementations should log to `stderr` (stdio transport) or use OpenTelemetry.
136136
137For more details about client primitives see [client concepts](./client-concepts).
137For more details about client primitives see [client concepts](/docs/draft/learn/client-concepts.md).
138138
139Besides server and client primitives, the protocol supports optional [extensions](/extensions/overview) that build on the core protocol. For example, the [Tasks extension](/extensions/tasks/overview) lets servers return a durable handle for long-running requests, so clients can poll for status and retrieve the result later.
139Besides server and client primitives, the protocol supports optional [extensions](/extensions/overview.md) that build on the core protocol. For example, the [Tasks extension](/extensions/tasks/overview.md) lets servers return a durable handle for long-running requests, so clients can poll for status and retrieve the result later.
140140
141141#### Notifications
142142
from line 308
308308
309309#### Understanding the Tool Discovery Request
310310
311The `tools/list` request requires no parameters beyond the standard `_meta` fields that accompany every MCP request. It also accepts an optional `cursor` parameter for [pagination](/specification/draft/server/utilities/pagination), which the example above omits.
311The `tools/list` request requires no parameters beyond the standard `_meta` fields that accompany every MCP request. It also accepts an optional `cursor` parameter for [pagination](/specification/draft/server/utilities/pagination.md), which the example above omits.
312312
313313#### Understanding the Tool Discovery Response
314314
from line 321
321321* **`description`**: Detailed explanation of what the tool does and when to use it
322322* **`inputSchema`**: A JSON Schema that defines the expected input parameters, enabling type validation and providing clear documentation about required and optional parameters
323323
324The result is marked `"resultType": "complete"` and carries two caching fields. `ttlMs` is a freshness hint in milliseconds, so this tool list can be cached for five minutes. `cacheScope` indicates who may reuse the response. The specification's [caching utility](/specification/draft/server/utilities/caching) defines the full rules.
324The result is marked `"resultType": "complete"` and carries two caching fields. `ttlMs` is a freshness hint in milliseconds, so this tool list can be cached for five minutes. `cacheScope` indicates who may reuse the response. The specification's [caching utility](/specification/draft/server/utilities/caching.md) defines the full rules.
325325
326326#### How This Works in AI Applications
327327
from line 336
336336conversation.register_available_tools(available_tools)
337337```
338338
339Clients that federate many servers can use [progressive tool discovery](/docs/draft/develop/clients/client-best-practices#progressive-tool-discovery) rather than loading every tool upfront.
339Clients that federate many servers can use [progressive tool discovery](/docs/draft/develop/clients/client-best-practices.md#progressive-tool-discovery) rather than loading every tool upfront.
340340
341341**3. Tool Execution (Primitives)**
342342
docs/draft/learn/client-concepts Changed · +7 / -7 lines
from line 11
1111| Feature | Explanation | Example |
1212| - | - | - |
1313| **Elicitation** | Elicitation enables servers to request specific information from users during interactions, providing a structured way for servers to gather information on demand. | A server booking travel may ask for the user's preferences on airplane seats, room type or their contact number to finalize a booking. |
14| **Roots** | Roots allow clients to specify which directories servers should focus on, communicating intended scope through a coordination mechanism. Roots are [deprecated](/specification/draft/deprecated) as of protocol version `2026-07-28`. | A server for booking travel may be given access to a specific directory, from which it can read a user's calendar. |
14| **Roots** | Roots allow clients to specify which directories servers should focus on, communicating intended scope through a coordination mechanism. Roots are [deprecated](/specification/draft/deprecated.md) as of protocol version `2026-07-28`. | A server for booking travel may be given access to a specific directory, from which it can read a user's calendar. |
1515| **Sampling** | Sampling allows servers to request LLM completions through the client, enabling an agentic workflow. This approach puts the client in complete control of user permissions and security measures. Sampling is deprecated as of protocol version `2026-07-28`. | A server for booking travel may send a list of flights to an LLM and request that the LLM pick the best flight for the user. |
1616
1717### Elicitation
from line 27
2727* **Form mode**: The server asks the client to collect structured data from the user. The request includes a schema that the client uses to build an input form and validate the response.
2828* **URL mode**: The server provides a URL for the user to open. The interaction happens out of band and its data never passes through the client, which makes this mode suitable for sensitive flows such as credential entry or third-party OAuth authorization.
2929
30Elicitation follows the [Multi Round-Trip Requests](/specification/draft/basic/patterns/mrtr) (MRTR) pattern. When a server needs user input while processing a request such as `tools/call`, it responds with an `InputRequiredResult` whose `inputRequests` field carries one or more `elicitation/create` requests. The client gathers the input and retries the original request, attaching the collected `inputResponses` and echoing back any `requestState` the server included.
30Elicitation follows the [Multi Round-Trip Requests](/specification/draft/basic/patterns/mrtr.md) (MRTR) pattern. When a server needs user input while processing a request such as `tools/call`, it responds with an `InputRequiredResult` whose `inputRequests` field carries one or more `elicitation/create` requests. The client gathers the input and retries the original request, attaching the collected `inputResponses` and echoing back any `requestState` the server included.
3131
3232**Elicitation flow:**
3333
from line 115
115115
116116> [!WARNING]
117117>
118> Roots are [deprecated](/specification/draft/deprecated) as of protocol version
118> Roots are [deprecated](/specification/draft/deprecated.md) as of protocol version
119119> `2026-07-28` and scheduled for removal. New implementations should pass
120120> directories or files via tool parameters, resource URIs, or server
121121> configuration instead.
from line 171
171171
172172> [!WARNING]
173173>
174> Sampling is [deprecated](/specification/draft/deprecated) as of protocol
174> Sampling is [deprecated](/specification/draft/deprecated.md) as of protocol
175175> version `2026-07-28` and scheduled for removal. New implementations should
176176> integrate directly with LLM provider APIs instead.
177177
from line 181
181181
182182Sampling enables servers to perform AI-dependent tasks without directly integrating with or paying for AI models. Instead, servers can request that the client—which already has AI model access—handle these tasks on their behalf. This approach puts the client in complete control of user permissions and security measures. Because sampling requests occur within the context of other operations—like a tool analyzing data—and are processed as separate model calls, they maintain clear boundaries between different contexts, allowing for more efficient use of the context window.
183183
184Sampling follows the same [Multi Round-Trip Requests](/specification/draft/basic/patterns/mrtr) flow described under [elicitation](#elicitation), with the `InputRequiredResult` carrying a `sampling/createMessage` request.
184Sampling follows the same [Multi Round-Trip Requests](/specification/draft/basic/patterns/mrtr.md) flow described under [elicitation](#elicitation), with the `InputRequiredResult` carrying a `sampling/createMessage` request.
185185
186Servers can also request tool use during sampling by including a `tools` array and an optional `toolChoice` field in the request. The tool definitions are scoped to that sampling request and do not need to correspond to tools the server exposes. Clients declare support through the `sampling.tools` capability, and servers must not send tool-enabled sampling requests to clients that have not declared it. See [sampling](/specification/draft/client/sampling#tools-in-sampling) in the specification for details.
186Servers can also request tool use during sampling by including a `tools` array and an optional `toolChoice` field in the request. The tool definitions are scoped to that sampling request and do not need to correspond to tools the server exposes. Clients declare support through the `sampling.tools` capability, and servers must not send tool-enabled sampling requests to clients that have not declared it. See [sampling](/specification/draft/client/sampling.md#tools-in-sampling) in the specification for details.
187187
188188**Sampling flow:**
189189
docs/draft/learn/versioning Changed · +5 / -5 lines
from line 18
1818 receive backwards compatible changes.
1919* **Final**: past, complete specifications that will not be changed.
2020
21The **current** protocol version is [**2026-07-28**](/specification/2026-07-28/).
21The **current** protocol version is [**2026-07-28**](/specification/2026-07-28.md).
2222
2323## Feature States
2424
2525Individual features of the specification may additionally be marked as
2626**Deprecated** under the
27[feature lifecycle and deprecation policy](/community/feature-lifecycle):
27[feature lifecycle and deprecation policy](/community/feature-lifecycle.md):
2828the feature remains part of the specification, but is scheduled for removal.
2929Deprecated features document a migration path (or state that none is required)
3030and remain in the specification for at least twelve months, or at least
3131ninety days under the policy's
32[expedited-removal exception](/community/feature-lifecycle#expedited-removal),
32[expedited-removal exception](/community/feature-lifecycle.md#expedited-removal),
3333before they become eligible for removal, after which they may be **Removed**
3434in a future revision.
3535
3636Features that are currently Deprecated are listed in the
37[deprecated features registry](/specification/draft/deprecated).
37[deprecated features registry](/specification/draft/deprecated.md).
3838
3939## Negotiation
4040
from line 59
5959
6060For interoperability with servers and clients that implement the
6161handshake-based protocol revisions (`2025-11-25` and earlier), see
62[Backward Compatibility](/specification/draft/basic/versioning#backward-compatibility-with-initialization-based-versions).
62[Backward Compatibility](/specification/draft/basic/versioning.md#backward-compatibility-with-initialization-based-versions).
6363
docs/draft/sdk Changed · +4 / -4 lines
from line 2
22
33> Official SDKs for building with Model Context Protocol
44
5Build MCP servers and clients using our official SDKs. SDKs are classified into tiers based on feature completeness, protocol support, and maintenance commitment. Learn more about [SDK tiers](/community/sdk-tiers).
5Build MCP servers and clients using our official SDKs. SDKs are classified into tiers based on feature completeness, protocol support, and maintenance commitment. Learn more about [SDK tiers](/community/sdk-tiers.md).
66
77## Available SDKs
88
from line 19
1919| [PHP](https://php.sdk.modelcontextprotocol.io) | [modelcontextprotocol/php-sdk](https://github.com/modelcontextprotocol/php-sdk) | Tier 3 |
2020| [Kotlin](https://kotlin.sdk.modelcontextprotocol.io) | [modelcontextprotocol/kotlin-sdk](https://github.com/modelcontextprotocol/kotlin-sdk) | Tier 3 |
2121
22See [SDK Tiering System](/community/sdk-tiers) for details on what each tier means.
22See [SDK Tiering System](/community/sdk-tiers.md) for details on what each tier means.
2323
2424## Getting Started
2525
from line 36
3636
3737Ready to start building with MCP? Choose your path:
3838
39> **[Build a Server](/docs/draft/develop/build-server)**
39> **[Build a Server](/docs/draft/develop/build-server.md)**
4040>
4141> Learn how to create your first MCP server
4242
43> **[Build a Client](/docs/draft/develop/build-client)**
43> **[Build a Client](/docs/draft/develop/build-client.md)**
4444>
4545> Create applications that connect to MCP servers
4646
docs/draft/tools/debugging Changed · +19 / -19 lines
from line 10
1010
1111MCP provides several tools for debugging at different levels:
1212
131. **[MCP Inspector](/docs/draft/tools/inspector)**: interactive, transport-agnostic
131. **[MCP Inspector](/docs/draft/tools/inspector.md)**: interactive, transport-agnostic
1414 testing UI. Connect to stdio or Streamable HTTP servers, invoke
15 [tools](/specification/latest/server/tools),
16 [prompts](/specification/latest/server/prompts), and
17 [resources](/specification/latest/server/resources), and watch the
15 [tools](/specification/latest/server/tools.md),
16 [prompts](/specification/latest/server/prompts.md), and
17 [resources](/specification/latest/server/resources.md), and watch the
1818 notification stream. This should be your first stop.
19192. **Server logging**: structured logs to stderr (stdio transport) or via
2020 [OpenTelemetry](https://opentelemetry.io/) (all transports).
21 [Logging](/specification/draft/server/utilities/logging) over the protocol
21 [Logging](/specification/draft/server/utilities/logging.md) over the protocol
2222 (`notifications/message`) is deprecated as of protocol version `2026-07-28`.
23233. **Client developer tools**: most MCP clients expose logs and connection
2424 state. See [Debugging in Claude Desktop](#debugging-in-claude-desktop)
from line 29
2929### Server-side logging
3030
3131When building a server that uses the local
32[stdio transport](/specification/draft/basic/transports/stdio), all messages
32[stdio transport](/specification/draft/basic/transports/stdio.md), all messages
3333logged to stderr (standard error) will be captured by the host application
3434automatically.
3535
from line 39
3939> will interfere with protocol operation.
4040
4141For servers using the
42[Streamable HTTP transport](/specification/draft/basic/transports/streamable-http),
42[Streamable HTTP transport](/specification/draft/basic/transports/streamable-http.md),
4343stderr is not captured by the client. Use your own server-side log aggregation
4444or [OpenTelemetry](https://opentelemetry.io/) for logs, and standard HTTP
4545tooling (curl, browser DevTools Network panel) to inspect requests and SSE
from line 50
5050> The `notifications/message` mechanism below is deprecated as of protocol
5151> version `2026-07-28`. It remains available during the deprecation window.
5252
53For all [transports](/specification/latest/basic/transports), record what the
53For all [transports](/specification/latest/basic/transports.md), record what the
5454server is doing as it runs:
5555
5656```python Python theme={null}
from line 78
7878```
7979
8080MCP defines eight
81[RFC 5424 severity levels](/specification/latest/server/utilities/logging#log-levels)
81[RFC 5424 severity levels](/specification/latest/server/utilities/logging.md#log-levels)
8282(`debug` through `emergency`). Clients opt in to log messages per request by
8383setting the
8484[`io.modelcontextprotocol/logLevel`](/specification/draft/server/utilities/logging#per-request-log-level)
from line 177
177177
1781781. Check client logs
1791792. Verify server process is running
1803. Test standalone with [Inspector](/docs/draft/tools/inspector)
1803. Test standalone with [Inspector](/docs/draft/tools/inspector.md)
1811814. Verify
182 [protocol compatibility](/docs/draft/learn/versioning#negotiation): call
182 [protocol compatibility](/docs/draft/learn/versioning.md#negotiation): call
183183 [`server/discover`](/specification/draft/server/discover) to see which
184184 protocol versions the server supports. An
185185 `UnsupportedProtocolVersionError` (`-32022`) lists the server's supported
from line 192
192192 required field is rejected with error `-32602` (Invalid params), the same
193193 code returned for many other malformed inputs. If the server needs a
194194 capability the request's `clientCapabilities` did not declare, such as
195 [elicitation](/specification/draft/client/elicitation), it returns a
195 [elicitation](/specification/draft/client/elicitation.md), it returns a
196196 `MissingRequiredClientCapabilityError` (`-32021`) naming the missing
197197 capabilities. Inspect the request's `_meta` and the
198198 [`server/discover`](/specification/draft/server/discover) response to
from line 267
267267### Development cycle
268268
2692691. Initial Development
270 * Use [Inspector](/docs/draft/tools/inspector) for basic testing
270 * Use [Inspector](/docs/draft/tools/inspector.md) for basic testing
271271 * Implement core functionality
272272 * Add logging points
273273
from line 283
283283* **Configuration changes**: Restart the MCP client
284284* **Server code changes**: Restart the client (for Claude Desktop, fully quit
285285 and reopen; closing the window is not enough)
286* **Quick iteration**: Use [Inspector](/docs/draft/tools/inspector) during
286* **Quick iteration**: Use [Inspector](/docs/draft/tools/inspector.md) during
287287 development
288288
289289## Best practices
from line 323
323323 * Monitor access patterns
324324
325325For a full treatment of MCP attack vectors and mitigations, see
326[Security Best Practices](/docs/draft/tutorials/security/security_best_practices).
326[Security Best Practices](/docs/draft/tutorials/security/security_best_practices.md).
327327
328328## Getting help
329329
from line 331
331331
3323321. **First Steps**
333333 * Check server logs
334 * Test with [Inspector](/docs/draft/tools/inspector)
334 * Test with [Inspector](/docs/draft/tools/inspector.md)
335335 * Review configuration
336336 * Verify environment
337337
from line 347
347347
348348## Next steps
349349
350> **[MCP Inspector](/docs/draft/tools/inspector)**
350> **[MCP Inspector](/docs/draft/tools/inspector.md)**
351351>
352352> Learn to use the MCP Inspector
353353
354> **[Build an MCP server](/docs/draft/develop/build-server)**
354> **[Build an MCP server](/docs/draft/develop/build-server.md)**
355355>
356356> Walk through building a server from scratch
357357
358> **[Connect local servers](/docs/draft/develop/connect-local-servers)**
358> **[Connect local servers](/docs/draft/develop/connect-local-servers.md)**
359359>
360360> Full claude\_desktop\_config.json reference and troubleshooting
361361
docs/draft/tools/inspector Changed · +20 / -18 lines
from line 2
22
33> Interactive developer tooling for testing and debugging MCP servers, in the browser, on the command line, and in the terminal
44
5The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is the reference developer tool for testing and debugging [MCP servers](/docs/draft/learn/server-concepts). It ships as a single package, `@modelcontextprotocol/inspector`, providing **three clients behind one binary**:
5The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is the reference developer tool for testing and debugging [MCP servers](/docs/draft/learn/server-concepts.md). It ships as a single package, `@modelcontextprotocol/inspector`, providing **three clients behind one binary**:
66
77| Client | Invocation | What it's for |
88| - | - | - |
from line 10
1010| **CLI** | `npx @modelcontextprotocol/inspector --cli` | A scriptable, machine-readable client for CI, shell pipelines, and coding agents. |
1111| **TUI** | `npx @modelcontextprotocol/inspector --tui` | An interactive terminal UI, for when a browser isn't available or wanted. |
1212
13All three are built on the same shared core, so a connection behaves identically across them: the same transports, the same configuration files, the same OAuth state on disk, and the same [protocol-era](/docs/draft/tools/inspector/protocol-eras) negotiation (legacy vs. modern 2026-07-28).
13All three are built on the same shared core, so a connection behaves identically across them: the same transports, the same configuration files, the same OAuth state on disk, and the same [protocol-era](/docs/draft/tools/inspector/protocol-eras.md) negotiation (legacy vs. modern 2026-07-28).
1414
15The package also installs **`mcpdo`**, an experimental [connection client](/docs/draft/tools/inspector/mcpdo) that connects to a server once and keeps it open across many commands, on the same core.
15The package also installs **`mcpdo`**, an experimental [connection client](/docs/draft/tools/inspector/mcpdo.md) that connects to a server once and keeps it open across many commands, on the same core.
1616
1717
1818
19The MCP Inspector web client after a tool call, with the monitoring sidebar pinned and widened so the JSON-RPC exchange stays readable while you work.
20
1921## Quickstart
2022
2123The Inspector requires **Node 22.19.0 or newer** and runs directly through `npx`. No installation is required:
from line 32
3032npx @modelcontextprotocol/inspector
3133```
3234
33The command prints a URL carrying a per-launch API token and opens it in your browser (set `MCP_AUTO_OPEN_ENABLED=false` to stop it opening). See [Web client](/docs/draft/tools/inspector/web).
35The command prints a URL carrying a per-launch API token and opens it in your browser (set `MCP_AUTO_OPEN_ENABLED=false` to stop it opening). See [Web client](/docs/draft/tools/inspector/web.md).
3436
3537**CLI**
3638
from line 45
4345 --method tools/call --tool-name get_weather --tool-arg city=Boston --format json | jq .result
4446```
4547
46See [CLI client](/docs/draft/tools/inspector/cli).
48See [CLI client](/docs/draft/tools/inspector/cli.md).
4749
4850**TUI**
4951
from line 53
5153npx @modelcontextprotocol/inspector --tui node path/to/server/index.js
5254```
5355
54See [TUI client](/docs/draft/tools/inspector/tui).
56See [TUI client](/docs/draft/tools/inspector/tui.md).
5557
5658### Inspecting published servers
5759
from line 87
8587> sessions, Termux, and containers with a mounted volume) they are saved to
8688> `~/.mcp-inspector/secrets.json` instead, **unencrypted unless you supply a
8789> key**. See [Where secrets are
88> stored](/docs/draft/tools/inspector/configuration#where-secrets-are-stored)
90> stored](/docs/draft/tools/inspector/configuration.md#where-secrets-are-stored)
8991> for how to get a keychain back, encrypt the file, or keep secrets in memory
9092> only.
9193
from line 98
96981. **The mode flag:** `--web` (default), `--cli`, or `--tui`. At most one; passing two errors with `Specify at most one of --web, --cli, or --tui.`
97992. **`-h` / `--help`.**
98100
99Everything else (`--catalog`, `--config`, `--server-url`, `--transport`, `--method`, the OAuth flags) is defined by the *client*, not the launcher, and the clients do not all define the same set. The [Configuration and flags](/docs/draft/tools/inspector/configuration) page is organized that way, by owner.
101Everything else (`--catalog`, `--config`, `--server-url`, `--transport`, `--method`, the OAuth flags) is defined by the *client*, not the launcher, and the clients do not all define the same set. The [Configuration and flags](/docs/draft/tools/inspector/configuration.md) page is organized that way, by owner.
100102
101103> [!NOTE]
102104>
from line 117
115117
116118## Where to go next
117119
118> **[Web client](/docs/draft/tools/inspector/web)**
120> **[Web client](/docs/draft/tools/inspector/web.md)**
119121>
120122> A tab-by-tab walkthrough of the graphical inspector.
121123
122> **[CLI client](/docs/draft/tools/inspector/cli)**
124> **[CLI client](/docs/draft/tools/inspector/cli.md)**
123125>
124126> Method reference, output formats, exit codes, and CI recipes.
125127
126> **[TUI client](/docs/draft/tools/inspector/tui)**
128> **[TUI client](/docs/draft/tools/inspector/tui.md)**
127129>
128130> Terminal navigation and keyboard reference.
129131
130> **[Configuration and flags](/docs/draft/tools/inspector/configuration)**
132> **[Configuration and flags](/docs/draft/tools/inspector/configuration.md)**
131133>
132134> Catalog vs. config files, the full per-client flag reference, and
133135> environment variables.
134136
135> **[Authorization](/docs/draft/tools/inspector/authorization)**
137> **[Authorization](/docs/draft/tools/inspector/authorization.md)**
136138>
137139> The OAuth flow end to end, mid-session re-authorization, and loopback
138140> callbacks.
139141
140> **[Protocol eras](/docs/draft/tools/inspector/protocol-eras)**
142> **[Protocol eras](/docs/draft/tools/inspector/protocol-eras.md)**
141143>
142144> Legacy vs. modern (2026-07-28) operation, and how every tab changes between
143145> protocol eras.
144146
145> **[mcpdo connection client](/docs/draft/tools/inspector/mcpdo)**
147> **[mcpdo connection client](/docs/draft/tools/inspector/mcpdo.md)**
146148>
147149> Connect once, then run many commands against a named connection.
148150
149> **[Security](/docs/draft/tools/inspector/security)**
151> **[Security](/docs/draft/tools/inspector/security.md)**
150152>
151153> The threat model: the web backend's token, Docker, secret storage, stdio
152154> servers, and the mcpdo daemon.
153155
154> **[Recipes](/docs/draft/tools/inspector/recipes)**
156> **[Recipes](/docs/draft/tools/inspector/recipes.md)**
155157>
156158> Importing client configs, reviewing MCP Apps, Docker, and network hosting.
157159
158> **[Debugging guide](/docs/draft/tools/debugging)**
160> **[Debugging guide](/docs/draft/tools/debugging.md)**
159161>
160162> Broader debugging strategies beyond the Inspector.
161163
docs/draft/tools/inspector/authorization Changed · +11 / -9 lines
from line 2
22
33> How the MCP Inspector performs OAuth, re-authorizes mid-session, and shares tokens between its clients
44
5Remote MCP servers usually require authorization. The Inspector implements the full [authorization](/specification/latest/basic/authorization) flow in all three clients, sharing the resulting tokens on disk so a login done once is usable everywhere.
5Remote MCP servers usually require authorization. The Inspector implements the full [authorization](/specification/latest/basic/authorization.md) flow in all three clients, sharing the resulting tokens on disk so a login done once is usable everywhere.
66
77## The flow, end to end
88
from line 17
1717
1818The Inspector fetches the server's [protected-resource and
1919authorization-server
20metadata](/specification/latest/basic/authorization/authorization-server-discovery)
20metadata](/specification/latest/basic/authorization/authorization-server-discovery.md)
2121to learn the endpoints and the supported grants.
2222
2323**3. Register or identify the client**
from line 24
2424
2525The Inspector identifies itself to the authorization server through
2626whichever mechanism is configured: [dynamic client
27registration](/specification/latest/basic/authorization/client-registration#dynamic-client-registration),
27registration](/specification/latest/basic/authorization/client-registration.md#dynamic-client-registration),
2828a pre-registered static client (`--client-id` / `--client-secret`), a
2929[Client ID Metadata
30Document](/specification/latest/basic/authorization/client-registration#client-id-metadata-documents)
30Document](/specification/latest/basic/authorization/client-registration.md#client-id-metadata-documents)
3131(`--client-metadata-url`), or an [enterprise-managed
32IdP](/extensions/auth/enterprise-managed-authorization).
32IdP](/extensions/auth/enterprise-managed-authorization.md).
3333
3434**4. Authorize in the browser**
3535
from line 49
4949
5050
5151
52Connection Info after a completed OAuth flow: the authorization status, the dynamically registered client, and the granted scopes.
53
5254## Callback URLs
5355
5456The web app listens for the OAuth callback on its own URL, while the CLI and TUI deliberately share a second one:
from line 87
8587| - | - |
8688| `~/.mcp-inspector/storage/oauth.json` | Non-secret OAuth state (discovery metadata, PKCE verifiers, granted scope, public client ids), keyed by canonicalized server URL. Written owner-only. |
8789| `~/.mcp-inspector/storage/client.json` | Install-level client settings (client metadata URL, enterprise IdP). The same file the web client's **Client Settings** dialog writes. |
88| The server's `oauth` block in the [catalog file](/docs/draft/tools/inspector/configuration#catalog-file-format) | Per-server client id/secret, scopes, the enterprise-managed flag, and the [step-up](#mid-session-re-authorization) policy. |
90| The server's `oauth` block in the [catalog file](/docs/draft/tools/inspector/configuration.md#catalog-file-format) | Per-server client id/secret, scopes, the enterprise-managed flag, and the [step-up](#mid-session-re-authorization) policy. |
8991
90The path to `oauth.json` is resolved in order: `MCP_INSPECTOR_OAUTH_STATE_PATH`, then `<MCP_STORAGE_DIR>/oauth.json` (see [Environment variables](/docs/draft/tools/inspector/configuration#environment-variables)), then the default above. All three clients resolve it the same way. Command-line `--client-id` / `--client-secret` / `--client-metadata-url` override `client.json`.
92The path to `oauth.json` is resolved in order: `MCP_INSPECTOR_OAUTH_STATE_PATH`, then `<MCP_STORAGE_DIR>/oauth.json` (see [Environment variables](/docs/draft/tools/inspector/configuration.md#environment-variables)), then the default above. All three clients resolve it the same way. Command-line `--client-id` / `--client-secret` / `--client-metadata-url` override `client.json`.
9193
92The secrets themselves (access and refresh tokens, client secrets, registration access tokens, and IdP session tokens) are not in `oauth.json`. They go to the [secret store](/docs/draft/tools/inspector/configuration#where-secrets-are-stored), which is the OS keychain when one is reachable. `MCP_INSPECTOR_PERSIST_TOKENS` limits which acquired tokens are kept: `all` (default), `access` (no refresh tokens), or `none` (re-authorize every run). See [Secret store variables](/docs/draft/tools/inspector/configuration#secret-store-variables).
94The secrets themselves (access and refresh tokens, client secrets, registration access tokens, and IdP session tokens) are not in `oauth.json`. They go to the [secret store](/docs/draft/tools/inspector/configuration.md#where-secrets-are-stored), which is the OS keychain when one is reachable. `MCP_INSPECTOR_PERSIST_TOKENS` limits which acquired tokens are kept: `all` (default), `access` (no refresh tokens), or `none` (re-authorize every run). See [Secret store variables](/docs/draft/tools/inspector/configuration.md#secret-store-variables).
9395
9496## Mid-session re-authorization
9597
from line 143
141143 --wait-for-auth 120 --method tools/list
142144```
143145
144The `deepLink` in the handoff block navigates a browser straight to a *connected* Inspector; see [Deep links](/docs/draft/tools/inspector/web#deep-links).
146The `deepLink` in the handoff block navigates a browser straight to a *connected* Inspector; see [Deep links](/docs/draft/tools/inspector/web.md#deep-links).
145147
146148> [!NOTE]
147149>
docs/draft/tools/inspector/cli Changed · +7 / -7 lines
from line 12
1212>
1313> Running several commands against the same server, or a flow that spans one
1414> session (tasks, subscriptions, elicitation)? The [mcpdo connection
15> client](/docs/draft/tools/inspector/mcpdo) connects once and keeps the
15> client](/docs/draft/tools/inspector/mcpdo.md) connects once and keeps the
1616> connection open between commands.
1717
1818The examples below use the installed `mcp-inspector` binary. Without a global install, prefix each command with `npx @modelcontextprotocol/inspector` instead, as above.
from line 32
3232mcp-inspector --cli --config ./mcp.json --server myserver --method tools/list
3333```
3434
35When the server comes from a file, its per-server settings (headers, timeouts, OAuth, [protocol era](/docs/draft/tools/inspector/protocol-eras), and roots) apply to the connection, resolved exactly as the TUI and web client resolve them. A `--header` flag overrides the file's headers for that run while leaving its timeouts and OAuth in place.
35When the server comes from a file, its per-server settings (headers, timeouts, OAuth, [protocol era](/docs/draft/tools/inspector/protocol-eras.md), and roots) apply to the connection, resolved exactly as the TUI and web client resolve them. A `--header` flag overrides the file's headers for that run while leaving its timeouts and OAuth in place.
3636
3737Later examples abbreviate whichever of these forms you use, along with its `--transport` or `--config`/`--server` flags, as `<server>`.
3838
from line 39
3939> [!NOTE]
4040>
4141> **The config file is the only durable way to give a run its
42> [roots](/specification/draft/client/roots):** there is no roots flag, and the
42> [roots](/specification/draft/client/roots.md):** there is no roots flag, and the
4343> CLI has no `roots/set` method. Roots configured for a server are advertised at
4444> connect, so a server that calls `roots/list` (as
4545> `@modelcontextprotocol/server-filesystem` does, to learn its allowed
4646> directories) gets them.
4747
48See [Configuration and flags](/docs/draft/tools/inspector/configuration) for `--catalog` vs. `--config`, the `--` separator, and the shared server-selection flags.
48See [Configuration and flags](/docs/draft/tools/inspector/configuration.md) for `--catalog` vs. `--config`, the `--` separator, and the shared server-selection flags.
4949
5050## Methods
5151
from line 97
9797
9898## Probing MCP Apps
9999
100`--app-info` reports whether a tool ships an [MCP App](/extensions/apps/overview) UI (its `ui://` resource, CSP, and permissions) **without calling the tool**, so a pipeline can decide whether it needs a browser before invoking anything:
100`--app-info` reports whether a tool ships an [MCP App](/extensions/apps/overview.md) UI (its `ui://` resource, CSP, and permissions) **without calling the tool**, so a pipeline can decide whether it needs a browser before invoking anything:
101101
102102```bash theme={null}
103103# One tool -> one JSON line
from line 163
163163
164164Without either, and with no TTY on stdin or stderr, the CLI fails fast with `auth_required` rather than hanging for fifteen minutes on a callback nobody will complete.
165165
166See [Authorization](/docs/draft/tools/inspector/authorization) for the full flow, the web-to-CLI handoff, and `--print-handoff`.
166See [Authorization](/docs/draft/tools/inspector/authorization.md) for the full flow, the web-to-CLI handoff, and `--print-handoff`.
167167
168168## Recipes
169169
from line 228
228228
229229### Editing the catalog
230230
231`servers/add`, `servers/edit`, and `servers/remove` write the catalog without connecting to anything. They go through the same code as the web client's server list, so `env` values and client secrets land in the [secret store](/docs/draft/tools/inspector/configuration#where-secrets-are-stored) exactly as they would from the UI, and a running web client picks up the change.
231`servers/add`, `servers/edit`, and `servers/remove` write the catalog without connecting to anything. They go through the same code as the web client's server list, so `env` values and client secrets land in the [secret store](/docs/draft/tools/inspector/configuration.md#where-secrets-are-stored) exactly as they would from the UI, and a running web client picks up the change.
232232
233233```bash theme={null}
234234# Add: the positional target or --server-url describes the entry, not a server to connect to
docs/draft/tools/inspector/configuration Changed · +13 / -13 lines
from line 16
1616> [!NOTE]
1717>
1818> The package also installs a second, separate bin, `mcpdo`, the experimental
19> [connection client](/docs/draft/tools/inspector/mcpdo). It is not reached
19> [connection client](/docs/draft/tools/inspector/mcpdo.md). It is not reached
2020> through the launcher and takes no mode flag.
2121
2222## Choosing servers
from line 93
9393| `--cwd <path>` | Working directory for a stdio server process. | None |
9494| `-e <KEY=VALUE>` | Environment variables for a stdio server. Repeatable. | None |
9595| `--header "Name: Value"` | HTTP headers for an HTTP/SSE server. Repeatable. | Requires an ad-hoc HTTP/SSE server on the web client. |
96| `--protocol-era <era>` | `legacy`, `auto`, or `modern`: the [protocol era](/docs/draft/tools/inspector/protocol-eras) to negotiate. | Requires an ad-hoc target on the web client. The CLI and TUI also let it override a file's `protocolEra`. |
96| `--protocol-era <era>` | `legacy`, `auto`, or `modern`: the [protocol era](/docs/draft/tools/inspector/protocol-eras.md) to negotiate. | Requires an ad-hoc target on the web client. The CLI and TUI also let it override a file's `protocolEra`. |
9797| `--skill-catalog-max-skills <n>` / `--skill-catalog-max-bytes <n>` | Budget for a skills verification run (most skills, most bytes read). | **CLI and TUI only.** Overrides the file's `skillCatalogMaxSkills` / `skillCatalogMaxBytes`. |
9898| `[target...]` | Positional command/URL for one ad-hoc server. | None |
9999
from line 133
133133
134134## CLI-only flags
135135
136The whole scripting surface belongs to the CLI. See [CLI client](/docs/draft/tools/inspector/cli) for usage.
136The whole scripting surface belongs to the CLI. See [CLI client](/docs/draft/tools/inspector/cli.md) for usage.
137137
138138| Group | Flags |
139139| - | - |
from line 149
149149
150150| Variable | Effect |
151151| - | - |
152| `MCP_DEBUG` | Append the error stack to a top-level `--web` or `--tui` failure (a `--cli` failure always prints its [JSON error envelope](/docs/draft/tools/inspector/cli#exit-codes-and-error-envelopes) instead). Only when set to a meaningful value: `0`, `false`, and empty read as off. |
152| `MCP_DEBUG` | Append the error stack to a top-level `--web` or `--tui` failure (a `--cli` failure always prints its [JSON error envelope](/docs/draft/tools/inspector/cli.md#exit-codes-and-error-envelopes) instead). Only when set to a meaningful value: `0`, `false`, and empty read as off. |
153153| `DEBUG` | Same, with the same meaningful-value rule, so a stray `DEBUG=0` doesn't turn stack traces on and `DEBUG` still works as the npm `debug` package's namespace filter. |
154154
155155### CLI and TUI
from line 169
169169
170170| Variable | Effect |
171171| - | - |
172| `MCP_INSPECTOR_API_TOKEN` | Pin the [session token](/docs/draft/tools/inspector/web#the-session-token) instead of generating a random one per launch. |
172| `MCP_INSPECTOR_API_TOKEN` | Pin the [session token](/docs/draft/tools/inspector/web.md#the-session-token) instead of generating a random one per launch. |
173173| `DANGEROUSLY_OMIT_AUTH` | Disable the `/api/*` token check entirely. Only `true` or `1` turn it off. |
174174| `HOST` | Bind host. Defaults to `127.0.0.1`. |
175175| `CLIENT_PORT` | Web UI port. Defaults to `6274`. |
from line 192
192192> The web backend spawns processes and holds OAuth tokens, so anyone who can
193193> reach it can drive it.
194194
195What the token does and does not protect is laid out under [The web backend and its API token](/docs/draft/tools/inspector/security#the-web-backend-and-its-api-token).
195What the token does and does not protect is laid out under [The web backend and its API token](/docs/draft/tools/inspector/security.md#the-web-backend-and-its-api-token).
196196
197197### Secret store variables
198198
199Read by **every** client: web, CLI, TUI, and [mcpdo](/docs/draft/tools/inspector/mcpdo). How they combine is described under [Where secrets are stored](#where-secrets-are-stored).
199Read by **every** client: web, CLI, TUI, and [mcpdo](/docs/draft/tools/inspector/mcpdo.md). How they combine is described under [Where secrets are stored](#where-secrets-are-stored).
200200
201201| Variable | Effect |
202202| - | - |
from line 245
245245> * **Encrypt the file:** supply a generated key with `MCP_INSPECTOR_SECRET_KEY_FILE` (preferred) or `MCP_INSPECTOR_SECRET_KEY`.
246246> * **Don't write secrets to disk at all:** `MCP_INSPECTOR_SECRET_STORE=memory`, and re-enter them each session.
247247>
248> Even encrypted, secrets on disk carry moderate risk. See [what the file store protects against](/docs/draft/tools/inspector/security#what-the-file-store-protects-against).
248> Even encrypted, secrets on disk carry moderate risk. See [what the file store protects against](/docs/draft/tools/inspector/security.md#what-the-file-store-protects-against).
249249
250[mcpdo](/docs/draft/tools/inspector/mcpdo) never falls back to `memory`: its commands and its daemon are separate processes, so it uses the file store instead.
250[mcpdo](/docs/draft/tools/inspector/mcpdo.md) never falls back to `memory`: its commands and its daemon are separate processes, so it uses the file store instead.
251251
252252### The file store
253253
from line 292
292292}
293293```
294294
295Fields that equal their default are omitted when the Inspector writes the file back, keeping diffs minimal. `protocolEra` (see [Protocol eras](/docs/draft/tools/inspector/protocol-eras)) defaults to `legacy` and `modernLogLevel` to `debug`.
295Fields that equal their default are omitted when the Inspector writes the file back, keeping diffs minimal. `protocolEra` (see [Protocol eras](/docs/draft/tools/inspector/protocol-eras.md)) defaults to `legacy` and `modernLogLevel` to `debug`.
296296
297You do not have to hand-write these; the web client can [import an existing client config](/docs/draft/tools/inspector/recipes#importing-an-existing-client-config) from Claude Desktop, Cursor, Cline, or VS Code, or a registry `server.json`.
297You do not have to hand-write these; the web client can [import an existing client config](/docs/draft/tools/inspector/recipes.md#importing-an-existing-client-config) from Claude Desktop, Cursor, Cline, or VS Code, or a registry `server.json`.
298298
docs/draft/tools/inspector/mcpdo Changed · +6 / -6 lines
from line 2
22
33> Connect to an MCP server once, then run many commands against that named connection
44
5`mcpdo` is an **experimental** command-line client that ships in the `@modelcontextprotocol/inspector` package alongside `mcp-inspector`. Where the [CLI client](/docs/draft/tools/inspector/cli) connects, runs one `--method` and disconnects, `mcpdo` **connects once** and keeps the connection open, so you can run many commands against it from any shell, the way `ssh-agent` keeps keys loaded.
5`mcpdo` is an **experimental** command-line client that ships in the `@modelcontextprotocol/inspector` package alongside `mcp-inspector`. Where the [CLI client](/docs/draft/tools/inspector/cli.md) connects, runs one `--method` and disconnects, `mcpdo` **connects once** and keeps the connection open, so you can run many commands against it from any shell, the way `ssh-agent` keeps keys loaded.
66
77| | `mcp-inspector --cli` | `mcpdo` |
88| - | - | - |
from line 10
1010| **State** | None between runs | Named connections held by a daemon |
1111| **Best for** | CI assertions, one JSON blob per run | Exploring a server, agent tool use, multi-step flows over one session (tasks, subscriptions, elicitation) |
1212
13Connections are held by a local background daemon, `mcpdod`, which `mcpdo` starts on demand and stops after its last connection closes. You never start it by hand. What it exposes, and how it is protected, is described under [The mcpdo connection daemon](/docs/draft/tools/inspector/security#the-mcpdo-connection-daemon).
13Connections are held by a local background daemon, `mcpdod`, which `mcpdo` starts on demand and stops after its last connection closes. You never start it by hand. What it exposes, and how it is protected, is described under [The mcpdo connection daemon](/docs/draft/tools/inspector/security.md#the-mcpdo-connection-daemon).
1414
1515Watch the [mcpdo tutorial video](https://www.youtube.com/watch?v=_a6eG0y156k).
1616
from line 51
5151mcpdo connect node build/index.js # ad-hoc stdio server
5252```
5353
54The catalog and `--config` behave exactly as for the other clients (see [Configuration and flags](/docs/draft/tools/inspector/configuration#choosing-servers)): the default catalog is `~/.mcp-inspector/mcp.json`, overridable with `--catalog` or `MCP_CATALOG_PATH`. `servers/list` and `servers/show <name>` read entries from disk. `connections/*` shows what the daemon currently holds. There are no commands to edit the catalog; edit the file directly.
54The catalog and `--config` behave exactly as for the other clients (see [Configuration and flags](/docs/draft/tools/inspector/configuration.md#choosing-servers)): the default catalog is `~/.mcp-inspector/mcp.json`, overridable with `--catalog` or `MCP_CATALOG_PATH`. `servers/list` and `servers/show <name>` read entries from disk. `connections/*` shows what the daemon currently holds. There are no commands to edit the catalog; edit the file directly.
5555
5656A stdio server runs with the working directory and command resolution of the shell that ran `connect`, not of the daemon, so relative paths and bare command names mean what you would expect.
5757
from line 111
111111
112112When a browser sign-in is needed and neither stdin nor stderr is a TTY (and `MCP_AUTO_OPEN_ENABLED` is not forced on), `connect` exits `0` immediately with `pendingAuth: true` and an `authUrl`. Relay that URL to whoever will sign in. The connection completes on its own once they do: the next real command against it finishes the connection, and `connections/list` reports `pendingAuthSignedIn` in the meantime. Don't reconnect to fix a pending sign-in.
113113
114On a host with no OS keychain, `mcpdo` stores tokens in the shared `secrets.json` file, never in memory, because its commands and the daemon are separate processes. That file is plaintext unless you supply a key; see [Where secrets are stored](/docs/draft/tools/inspector/configuration#where-secrets-are-stored).
114On a host with no OS keychain, `mcpdo` stores tokens in the shared `secrets.json` file, never in memory, because its commands and the daemon are separate processes. That file is plaintext unless you supply a key; see [Where secrets are stored](/docs/draft/tools/inspector/configuration.md#where-secrets-are-stored).
115115
116116## Elicitation
117117
from line 131
131131
132132## Protocol eras
133133
134`mcpdo` negotiates the same [protocol eras](/docs/draft/tools/inspector/protocol-eras) as the other clients. `connect --era legacy|auto|modern` overrides a catalog entry's `protocolEra`, and is the only way to set it for an ad-hoc target. `connections/list` tags each connection `[legacy]` or `[modern]`, and `connections/show <name>` gives the negotiated version, server info, capabilities, and the supported-versions list when the server was probed.
134`mcpdo` negotiates the same [protocol eras](/docs/draft/tools/inspector/protocol-eras.md) as the other clients. `connect --era legacy|auto|modern` overrides a catalog entry's `protocolEra`, and is the only way to set it for an ad-hoc target. `connections/list` tags each connection `[legacy]` or `[modern]`, and `connections/show <name>` gives the negotiated version, server info, capabilities, and the supported-versions list when the server was probed.
135135
136136## The daemon
137137
from line 159
159159
160160## Environment variables
161161
162`mcpdo` reads the same catalog, storage and secret-store variables as the other clients (see [Environment variables](/docs/draft/tools/inspector/configuration#environment-variables)), plus these:
162`mcpdo` reads the same catalog, storage and secret-store variables as the other clients (see [Environment variables](/docs/draft/tools/inspector/configuration.md#environment-variables)), plus these:
163163
164164| Variable | Effect |
165165| - | - |
docs/draft/tools/inspector/protocol-eras Changed · +27 / -5 lines
from line 27
2727
2828
2929
30Server Settings: the Protocol Era selector, with all three choices.
31
3032## Reproducing each era locally
3133
3234Every section below ends with a **Reproduce with ...** pointer to a JSON config for one of the **composable test servers** shipped in the Inspector repository. Clone the repo and build the test servers:
from line 73
7173
7274
7375
76Legacy: the Logs tab offers a session-scoped Set Active Level control, and a log arrives after calling send\_notification.
77
7478
7579
80Modern: the same tab instead offers Log Level per Request. The level is stamped on every outgoing request, and the log rides that request's stream.
81
7682***
7783
7884## Resource subscriptions
from line 99
9399
94100
95101
102A modern subscription: the Subscriptions section carries a LISTENING stream-status badge that a legacy subscription has no need for.
103
96104***
97105
98106## Tasks
from line 115
107115
108116**Modern**
109117
110Tasks are an **extension** (`io.modelcontextprotocol/tasks`, [SEP-2663](/seps/2663-tasks-extension)), so the tab is gated on the server *advertising that extension* rather than on `capabilities.tasks`.
118Tasks are an **extension** (`io.modelcontextprotocol/tasks`, [SEP-2663](/seps/2663-tasks-extension.md)), so the tab is gated on the server *advertising that extension* rather than on `capabilities.tasks`.
111119
112120Run a tool as a task and `tools/call` returns a `CreateTaskResult` (`resultType: "task"`, visible in the Protocol and Network tabs). The Inspector polls **`tasks/get`** only; there is no `tasks/list`, so **Refresh** re-polls the handles the client already knows about. A completed task **inlines its result**, with no blocking `tasks/result` call.
113121
114A task that needs more information moves to `input_required` and surfaces an embedded [elicitation](/specification/draft/client/elicitation) in the pending-request modal (the dialog the web client opens whenever a request is waiting on you). Answering it sends **`tasks/update`** carrying the `inputResponses`, and the next poll completes.
122A task that needs more information moves to `input_required` and surfaces an embedded [elicitation](/specification/draft/client/elicitation.md) in the pending-request modal (the dialog the web client opens whenever a request is waiting on you). Answering it sends **`tasks/update`** carrying the `inputResponses`, and the next poll completes.
115123
116124Reproduce with `test-servers/configs/tasks-modern-http.json` (tools `modern_task` and `modern_input_task`).
117125
118126
119127
128Legacy: the Tasks tab is populated from tasks/list, and the payload is fetched with a blocking tasks/result.
129
120130
121131
132Modern: the client polls tasks/get on handles it already holds, and the completed task inlines its result; note resultType: complete in the full task object.
133
122134***
123135
124136## Multi-round tool results (MRTR)
125137
126On the modern era a tool can return `input_required` instead of a final result, embedding an [elicitation](/specification/draft/client/elicitation), a [sampling](/specification/draft/client/sampling) request, or a [`roots/list`](/specification/draft/client/roots) request. The client answers that embedded request and retries the `tools/call` under a fresh JSON-RPC id until the call reaches `complete`.
138On the modern era a tool can return `input_required` instead of a final result, embedding an [elicitation](/specification/draft/client/elicitation.md), a [sampling](/specification/draft/client/sampling.md) request, or a [`roots/list`](/specification/draft/client/roots) request. The client answers that embedded request and retries the `tools/call` under a fresh JSON-RPC id until the call reaches `complete`.
127139
128140The Inspector drives MRTR **manually**, so each round pauses at the **pending-request modal**, tagged `input_required`, for you to answer. The Protocol view groups the whole exchange as one MRTR conversation rather than as unrelated calls.
129141
from line 160
148160
149161
150162
163An MRTR round paused at the pending-request modal, tagged input\_required. Answering it retries the original request.
164
151165
152166
167The monitoring sidebar's Protocol tab after mrtr\_confirm completes. Both tools/call rounds sit inside one MRTR conversation, Round 1 tagged input\_required and Round 2 complete, while unrelated traffic stays outside it.
168
153169***
154170
155171## Tools: mirrored headers and excluded tools
156172
157[SEP-2243](/seps/2243-http-standardization) lets a tool annotate an argument with `x-mcp-header`, asking a Streamable HTTP client to mirror that argument's value into an `Mcp-Param-*` request header.
173[SEP-2243](/seps/2243-http-standardization.md) lets a tool annotate an argument with `x-mcp-header`, asking a Streamable HTTP client to mirror that argument's value into an `Mcp-Param-*` request header.
158174
159175The Inspector surfaces both halves of that contract in the **Tools** tab:
160176
from line 188
172188
173189
174190
191get\_weather shows its mirrored city -> Mcp-Param-City header, and the Network sidebar confirms the call carried mcp-param-city: Boston. invalid\_header\_tool is struck through under the Excluded (SEP-2243) divider.
192
175193### `-32602` error panels
176194
177195A `tools/call` that rejects with `-32602` renders as a distinct **error panel**, on either era:
from line 203
185203
186204## Network and Protocol: headers and the error taxonomy
187205
188The modern era standardizes a set of `Mcp-*` HTTP headers and introduces a richer JSON-RPC error taxonomy ([SEP-2243](/seps/2243-http-standardization) / [SEP-2575](/seps/2575-stateless-mcp)). The two monitoring tabs divide the work:
206The modern era standardizes a set of `Mcp-*` HTTP headers and introduces a richer JSON-RPC error taxonomy ([SEP-2243](/seps/2243-http-standardization.md) / [SEP-2575](/seps/2575-stateless-mcp.md)). The two monitoring tabs divide the work:
189207
190208* The **Network** tab is the HTTP view: mirrored `Mcp-*` headers are highlighted and sentinel values decoded.
191209* The **Protocol** tab is the JSON-RPC view: each spec error renders distinctly rather than as a generic failure.
from line 219
201219
202220
203221
222The Network tab shows the HTTP layer; here, the 400 Bad Request the strict server answered with.
223
204224
225
226The Protocol tab renders the same failure as a typed spec error: -32022 UnsupportedProtocolVersion, with the versions the server does support.
205227
206228***
207229
docs/draft/tools/inspector/recipes Changed · +19 / -17 lines
from line 31
3131 --header "X-Tenant: acme"
3232```
3333
34`--transport` accepts `http` (Streamable HTTP) and `sse`. If the server is protected, see [Authorization](/docs/draft/tools/inspector/authorization): no setup is needed in advance, because when the server answers `401` the Inspector runs the OAuth flow described there and retries the connection.
34`--transport` accepts `http` (Streamable HTTP) and `sse`. If the server is protected, see [Authorization](/docs/draft/tools/inspector/authorization.md): no setup is needed in advance, because when the server answers `401` the Inspector runs the OAuth flow described there and retries the connection.
3535
36For an HTTP server, also decide its [protocol era](/docs/draft/tools/inspector/protocol-eras). The default is `legacy`; set `modern` or `auto` in Server Settings (or `protocolEra` in the catalog file) to exercise the 2026-07-28 behavior. For an ad-hoc target, pass it at launch with `--protocol-era legacy|auto|modern`.
36For an HTTP server, also decide its [protocol era](/docs/draft/tools/inspector/protocol-eras.md). The default is `legacy`; set `modern` or `auto` in Server Settings (or `protocolEra` in the catalog file) to exercise the 2026-07-28 behavior. For an ad-hoc target, pass it at launch with `--protocol-era legacy|auto|modern`.
3737
3838## Importing an existing client config
3939
4040On the Servers screen, **Add Servers** can import MCP servers you have already configured
4141elsewhere instead of retyping them. It parses Claude Desktop, Cursor, Cline, and VS Code client
42configs directly, and it also reads a server's own [MCP Registry](/registry/about) `server.json`.
42configs directly, and it also reads a server's own [MCP Registry](/registry/about.md) `server.json`.
4343
44Import merges into the active [catalog](/docs/draft/tools/inspector/configuration#choosing-servers)
44Import merges into the active [catalog](/docs/draft/tools/inspector/configuration.md#choosing-servers)
4545(the Inspector's writable server list). When an imported server's id is already taken, you
4646choose whether to overwrite, skip or rename it. If you'd rather
4747not touch your catalog at all, launch against the foreign file read-only instead:
from line 54
5454
5555
5656
57Add Servers offers import from an existing client config or from a registry server.json.
58
5759## Reviewing an MCP App
5860
59[MCP Apps](/extensions/apps/overview) are tools that carry a UI widget. For an automated reviewer (CI or an agent), use the CLI for every check that returns JSON, and open a browser only to inspect the rendered widget.
61[MCP Apps](/extensions/apps/overview.md) are tools that carry a UI widget. For an automated reviewer (CI or an agent), use the CLI for every check that returns JSON, and open a browser only to inspect the rendered widget.
6062
6163**1. Probe the security posture without calling the tool**
6264
from line 109
107109http://127.0.0.1:6274/?serverUrl=<encoded url>&transport=http&autoConnect=<TOKEN>&openApp=<tool>&appArgs=<base64url(JSON)>&autoOpen=<TOKEN>
108110```
109111
110`appArgs` is the tool's arguments as base64url-encoded JSON, and every deep-link parameter is described under [Deep links](/docs/draft/tools/inspector/web#deep-links). `autoConnect` and `autoOpen` must both equal the session token, since `autoOpen` fires a tool call straight from the URL and needs the same gate as `autoConnect`.
112`appArgs` is the tool's arguments as base64url-encoded JSON, and every deep-link parameter is described under [Deep links](/docs/draft/tools/inspector/web.md#deep-links). `autoConnect` and `autoOpen` must both equal the session token, since `autoOpen` fires a tool call straight from the URL and needs the same gate as `autoConnect`.
111113
112114**5. Wait on a deterministic signal instead of sleeping**
113115
from line 129
127129docker run --rm -p 127.0.0.1:6274:6274 ghcr.io/modelcontextprotocol/inspector
128130```
129131
130Read the [session token](/docs/draft/tools/inspector/web#the-session-token) from the container logs, or pin it with `-e MCP_INSPECTOR_API_TOKEN=<value>`.
132Read the [session token](/docs/draft/tools/inspector/web.md#the-session-token) from the container logs, or pin it with `-e MCP_INSPECTOR_API_TOKEN=<value>`.
131133
132134The image defaults to `--web`, bound to `0.0.0.0:6274` with browser auto-open off, and runs as the non-root `node` user (uid `1000`). It sets `DANGEROUSLY_BIND_ALL_INTERFACES=true` because a container must bind the wildcard address to be reachable through `-p`.
133135
from line 140
138140> processes, and the page that discloses its token, on your local network. The
139141> image's `DANGEROUSLY_BIND_ALL_INTERFACES` covers the container's interfaces,
140142> not the host's. See [Publish the port on loopback
141> only](/docs/draft/tools/inspector/security#publish-the-port-on-loopback-only).
143> only](/docs/draft/tools/inspector/security.md#publish-the-port-on-loopback-only).
142144
143145To use the **Apps** tab, also publish the MCP Apps sandbox port, `6275`, and `6278` for an app that declares `_meta.ui.domain`. Publish each on the same port number inside and out, since the browser is handed the in-container port:
144146
from line 179
177179> (umask 077 && openssl rand -base64 32 > ~/.config/mcp-inspector/secret-key)
178180> ```
179181>
180> Even encrypted, secrets on disk carry moderate risk. See [what the file store protects against](/docs/draft/tools/inspector/security#what-the-file-store-protects-against).
182> Even encrypted, secrets on disk carry moderate risk. See [what the file store protects against](/docs/draft/tools/inspector/security.md#what-the-file-store-protects-against).
181183
182184Hand the key to the container **as a file** with `MCP_INSPECTOR_SECRET_KEY_FILE`, not as an environment variable. A key passed with `-e MCP_INSPECTOR_SECRET_KEY=…` is readable by anyone who can run `docker inspect` or `docker exec`.
183185
from line 213
211213
212214Without Swarm, Compose secrets are bind mounts that keep the host file's owner and mode, so the `0600` key file must be owned by uid `1000`. On a Linux host where your uid is different, run `sudo chown 1000 ~/.config/mcp-inspector/secret-key` rather than loosening its mode. Supply the **same** key on every run.
213215
214If the key file is missing, unreadable or empty, or both key variables are set, the Inspector **refuses to read or write the secrets file** rather than falling back to plaintext, and says why in the log and in the settings dialogs' footer. Everything else about the store (selection order, location, permissions) is under [Where secrets are stored](/docs/draft/tools/inspector/configuration#where-secrets-are-stored).
216If the key file is missing, unreadable or empty, or both key variables are set, the Inspector **refuses to read or write the secrets file** rather than falling back to plaintext, and says why in the log and in the settings dialogs' footer. Everything else about the store (selection order, location, permissions) is under [Where secrets are stored](/docs/draft/tools/inspector/configuration.md#where-secrets-are-stored).
215217
216218### Health checks and other modes
217219
218220The image's `HEALTHCHECK` probes the web UI at the address `HOST` binds. `--cli` and `--tui` have no web server, so the probe detects those modes from the container's arguments and reports healthy while they run. An external orchestrator (a Kubernetes probe, a Compose `healthcheck`) can call `GET /healthz` on the web port, which needs no token and returns only `{"status":"ok"}`.
219221
220`<target>` below is an [ad-hoc target](/docs/draft/tools/inspector/configuration#ad-hoc-targets): a positional stdio command, or `--server-url <url> --transport http`.
222`<target>` below is an [ad-hoc target](/docs/draft/tools/inspector/configuration.md#ad-hoc-targets): a positional stdio command, or `--server-url <url> --transport http`.
221223
222224```bash theme={null}
223225docker run --rm ghcr.io/modelcontextprotocol/inspector --cli <target> --method tools/list
from line 261
259261* **Behind TLS or a reverse proxy, give MCP Apps their public addresses.** By default the sandbox is advertised as `http://<bind host>:6275`, which an `https://` page blocks as mixed content. Set `MCP_SANDBOX_FULL_ADDRESS` (for example `https://inspector-sandbox.example.com/sandbox`) and, for apps that declare `_meta.ui.domain`, `MCP_APP_ORIGIN_FULL_ADDRESS` (for example `https://inspector-apps.example.com`). Each needs its own hostname or port; an address that shares the Inspector's origin is refused.
260262* **MCP Apps can't render at a bare IPv6 literal.** A bracketed IPv6 literal isn't a valid CSP host-source, so browse at a name or an IPv4 address.
261263
262Whatever the shape: keep authentication on. Do not set `DANGEROUSLY_OMIT_AUTH` on anything reachable by anyone but you. The reasoning is under [Security](/docs/draft/tools/inspector/security#the-web-backend-and-its-api-token).
264Whatever the shape: keep authentication on. Do not set `DANGEROUSLY_OMIT_AUTH` on anything reachable by anyone but you. The reasoning is under [Security](/docs/draft/tools/inspector/security.md#the-web-backend-and-its-api-token).
263265
264266## Keeping a connection open with mcpdo
265267
266When an exploration spans many calls (a multi-step flow over one session, a log you watch, an agent using a server's tools mid-session), reconnecting for every `--cli` invocation gets in the way. [mcpdo](/docs/draft/tools/inspector/mcpdo) holds the connection for you:
268When an exploration spans many calls (a multi-step flow over one session, a log you watch, an agent using a server's tools mid-session), reconnecting for every `--cli` invocation gets in the way. [mcpdo](/docs/draft/tools/inspector/mcpdo.md) holds the connection for you:
267269
268270```bash theme={null}
269271mcpdo connect my-server
from line 277
275277
276278A connection runs one call at a time, so commands against the same connection from other shells wait their turn.
277279
278The daemon that holds the connection starts automatically and exits about a minute after the last connection closes. Read [The mcpdo connection daemon](/docs/draft/tools/inspector/security#the-mcpdo-connection-daemon) before using it on a shared machine.
280The daemon that holds the connection starts automatically and exits about a minute after the last connection closes. Read [The mcpdo connection daemon](/docs/draft/tools/inspector/security.md#the-mcpdo-connection-daemon) before using it on a shared machine.
279281
280282## Development workflow
281283
from line 305
303305Turn what you found into a CI assertion: pipe the CLI's `--format json`
304306output to `jq -e` with `--stored-auth-only`, so a missing token fails fast
305307instead of starting interactive OAuth. See [Verify a server in
306CI](/docs/draft/tools/inspector/cli#verify-a-server-in-ci) for the full
308CI](/docs/draft/tools/inspector/cli.md#verify-a-server-in-ci) for the full
307309command.
308310
docs/draft/tools/inspector/security Changed · +5 / -5 lines
from line 13
1313
1414## The web backend and its API token
1515
16The web client is a browser app backed by a Node server that owns the MCP connections. That server can start stdio processes on request, so every `/api/*` route requires a per-launch bearer token (`x-mcp-remote-auth: Bearer <token>`). How the browser obtains it is described under [The session token](/docs/draft/tools/inspector/web#the-session-token).
16The web client is a browser app backed by a Node server that owns the MCP connections. That server can start stdio processes on request, so every `/api/*` route requires a per-launch bearer token (`x-mcp-remote-auth: Bearer <token>`). How the browser obtains it is described under [The session token](/docs/draft/tools/inspector/web.md#the-session-token).
1717
1818What the token does and does not protect:
1919
from line 24
2424
2525### Where the backend listens
2626
27The backend binds `127.0.0.1` by default. Binding every interface (`0.0.0.0`, `::` and equivalent spellings) is refused unless you set `DANGEROUSLY_BIND_ALL_INTERFACES=true`. Binding one specific address is allowed without that opt-in, because it is one deliberate exposure rather than all of them at once. See [Hosting on a network](/docs/draft/tools/inspector/recipes#hosting-on-a-network).
27The backend binds `127.0.0.1` by default. Binding every interface (`0.0.0.0`, `::` and equivalent spellings) is refused unless you set `DANGEROUSLY_BIND_ALL_INTERFACES=true`. Binding one specific address is allowed without that opt-in, because it is one deliberate exposure rather than all of them at once. See [Hosting on a network](/docs/draft/tools/inspector/recipes.md#hosting-on-a-network).
2828
2929> [!WARNING]
3030>
from line 34
3434
3535## Docker
3636
37The [Docker image](/docs/draft/tools/inspector/recipes#docker) changes two things about the picture above.
37The [Docker image](/docs/draft/tools/inspector/recipes.md#docker) changes two things about the picture above.
3838
3939### Publish the port on loopback only
4040
from line 64
6464
6565**`headers` are not secrets.** They are saved in `mcp.json` exactly as written, so a header that carries a credential (an API key, a static `Authorization` value) stays in the file.
6666
67How the store is selected, and how to change it, is under [Where secrets are stored](/docs/draft/tools/inspector/configuration#where-secrets-are-stored). This section covers the risks.
67How the store is selected, and how to change it, is under [Where secrets are stored](/docs/draft/tools/inspector/configuration.md#where-secrets-are-stored). This section covers the risks.
6868
6969### The automatic plaintext fallback
7070
from line 123
123123
124124## The mcpdo connection daemon
125125
126[mcpdo](/docs/draft/tools/inspector/mcpdo) keeps connections open between commands by handing them to a background daemon, `mcpdod`. It is started **automatically** the first time a command needs it (`mcpdo connect`, or any command against a connection). There is no separate "start the daemon" step to opt into. This section describes what that process exposes.
126[mcpdo](/docs/draft/tools/inspector/mcpdo.md) keeps connections open between commands by handing them to a background daemon, `mcpdod`. It is started **automatically** the first time a command needs it (`mcpdo connect`, or any command against a connection). There is no separate "start the daemon" step to opt into. This section describes what that process exposes.
127127
128128### How clients reach it, and who else can
129129
docs/draft/tools/inspector/tui Changed · +10 / -6 lines
from line 10
1010
1111
1212
13The TUI connected to a server, on the Tools tab, showing a tool's input schema.
14
1315## Choosing servers
1416
1517Unlike the CLI, the TUI has no `--server <name>` flag for picking one entry: it reads its servers from a catalog or config file, loads every server in it, and lets you pick from an on-screen list:
from line 21
1921mcp-inspector --tui --config mcp.json # read-only session, errors if absent
2022```
2123
22With neither `--catalog` nor `--config`, and no [ad-hoc target](/docs/draft/tools/inspector/configuration#ad-hoc-targets), it uses the default writable catalog `~/.mcp-inspector/mcp.json`. See [Configuration and flags](/docs/draft/tools/inspector/configuration).
24With neither `--catalog` nor `--config`, and no [ad-hoc target](/docs/draft/tools/inspector/configuration.md#ad-hoc-targets), it uses the default writable catalog `~/.mcp-inspector/mcp.json`. See [Configuration and flags](/docs/draft/tools/inspector/configuration.md).
2325
24The TUI also takes the [shared server-selection flags](/docs/draft/tools/inspector/configuration#shared-server-selection-flags) (`--server-url`, `--transport`, `--header`, `-e`, `--cwd`) plus `--protocol-era` for an ad-hoc server, and the [OAuth client flags](/docs/draft/tools/inspector/configuration#cli-and-tui-oauth-client-flags) (`--client-id`, `--client-secret`, `--client-metadata-url`, `--client-config`, `--callback-url`).
26The TUI also takes the [shared server-selection flags](/docs/draft/tools/inspector/configuration.md#shared-server-selection-flags) (`--server-url`, `--transport`, `--header`, `-e`, `--cwd`) plus `--protocol-era` for an ad-hoc server, and the [OAuth client flags](/docs/draft/tools/inspector/configuration.md#cli-and-tui-oauth-client-flags) (`--client-id`, `--client-secret`, `--client-metadata-url`, `--client-config`, `--callback-url`).
2527
2628## Tabs
2729
from line 38
3638| **Tools** | `t` | View tools and execute them with form-like inputs. |
3739| **Tasks** | `s` | List tasks, fetch their results, cancel them, and clear finished ones (servers that support Tasks). |
3840| **Protocol** | `p` | JSON-RPC request/response/notification history. |
39| **Network** | `n` | HTTP traffic for SSE and [Streamable HTTP](/specification/latest/basic/transports) servers. |
41| **Network** | `n` | HTTP traffic for SSE and [Streamable HTTP](/specification/latest/basic/transports.md) servers. |
4042| **Console** | `o` | `stderr` from a connected stdio server process. |
4143
4244The accelerators avoid collisions rather than always taking the first letter: **P**rotocol takes `p` so Pro**m**pts takes `m`, and **C**onsole takes `o` because `c` is the global Connect action. Ta**s**ks takes `s`, its only free letter, so Subscriptions takes `u` and Skills takes `k`.
from line 70
68703. When the browser redirect lands on the TUI's loopback listener, the connection finishes on its own, with no second **`c`**.
69714. Use the **Auth** tab to inspect the resulting OAuth state, or to clear it.
7072
71The TUI's callback listener defaults to `http://127.0.0.1:6276/oauth/callback`. The port is fixed on purpose: a pre-registered (static) OAuth client, a [Client ID Metadata Document (CIMD)](/specification/latest/basic/authorization/client-registration#client-id-metadata-documents), or an enterprise-managed IdP all need a redirect URI known in advance. Register that URI once and it works across sessions. On a remote host where your browser is on another machine, forward the callback port so the redirect reaches this listener; see [Callback URLs](/docs/draft/tools/inspector/authorization#callback-urls).
73The TUI's callback listener defaults to `http://127.0.0.1:6276/oauth/callback`. The port is fixed on purpose: a pre-registered (static) OAuth client, a [Client ID Metadata Document (CIMD)](/specification/latest/basic/authorization/client-registration.md#client-id-metadata-documents), or an enterprise-managed IdP all need a redirect URI known in advance. Register that URI once and it works across sessions. On a remote host where your browser is on another machine, forward the callback port so the redirect reaches this listener; see [Callback URLs](/docs/draft/tools/inspector/authorization.md#callback-urls).
7274
7375The trade-off is that only one TUI OAuth flow can hold the port at a time; a second concurrent flow fails with `EADDRINUSE`. To override it, pass `--callback-url` or set `MCP_OAUTH_CALLBACK_URL`: use a different fixed port per instance, or `http://127.0.0.1:0/oauth/callback` for an OS-assigned ephemeral port when your authorization server registers redirect URIs dynamically.
7476
from line 81
7981
8082Per-server OAuth fields in the catalog (static client id/secret, scopes, the enterprise-managed flag) are applied automatically. Install-wide settings (CIMD, enterprise IdP) come from `~/.mcp-inspector/storage/client.json`, the same file the web client's **Client Settings** dialog writes. Point at a different one with `--client-config` or `MCP_CLIENT_CONFIG_PATH`.
8183
82See [Authorization](/docs/draft/tools/inspector/authorization) for the full picture.
84See [Authorization](/docs/draft/tools/inspector/authorization.md) for the full picture.
8385
8486
8587
88The Auth tab. It shows the same OAuth fields as the web client's Connection Info or, before any authorization has happened, says there is no OAuth information yet.
89
8690## Requirements
8791
88The TUI needs a real TTY with raw-mode support. It will not run usefully in a headless CI job; use the [CLI](/docs/draft/tools/inspector/cli) there.
92The TUI needs a real TTY with raw-mode support. It will not run usefully in a headless CI job; use the [CLI](/docs/draft/tools/inspector/cli.md) there.
8993
docs/draft/tools/inspector/web Changed · +30 / -14 lines
from line 20
20202. A `?MCP_INSPECTOR_API_TOKEN=...` query string, the form used in that printed URL.
21213. `sessionStorage`, as a backstop.
2222
23Set the `MCP_INSPECTOR_API_TOKEN` environment variable to pin a known token (useful for scripted launches), or set `DANGEROUSLY_OMIT_AUTH=true` to disable the check entirely, but only on a machine where nothing else can reach the port. Both are described under [Web backend environment variables](/docs/draft/tools/inspector/configuration#web-backend-environment-variables). What the token does and does not protect is described under [Security](/docs/draft/tools/inspector/security#the-web-backend-and-its-api-token).
23Set the `MCP_INSPECTOR_API_TOKEN` environment variable to pin a known token (useful for scripted launches), or set `DANGEROUSLY_OMIT_AUTH=true` to disable the check entirely, but only on a machine where nothing else can reach the port. Both are described under [Web backend environment variables](/docs/draft/tools/inspector/configuration.md#web-backend-environment-variables). What the token does and does not protect is described under [Security](/docs/draft/tools/inspector/security.md#the-web-backend-and-its-api-token).
2424
2525## Dev mode
2626
from line 48
4848| **Network** | HTTP / SSE servers | The raw HTTP view: status, headers, bodies. |
4949| **Console** | stdio servers | The server process's `stderr`. |
5050
51**Network** and **Console** never appear together. Legacy and modern eras are described in [Protocol eras](/docs/draft/tools/inspector/protocol-eras).
51**Network** and **Console** never appear together. Legacy and modern eras are described in [Protocol eras](/docs/draft/tools/inspector/protocol-eras.md).
5252
5353
5454
55The tab bar on a connected server. Which tabs appear depends on the capabilities the server reported.
56
5557### The monitoring sidebar
5658
5759**Tasks**, **Logs**, **Protocol**, **Network**, and **Console** form a *monitor group*. Pin the group and they leave the tab bar and move into a resizable right-hand column, so you can watch traffic while working in Tools or Resources. Drag the column's edge to resize it, from 320 to 720 pixels wide. The column width and the selected monitor tab persist across reloads.
from line 60
5860
5961
6062
63The monitoring sidebar pinned beside the Tools screen and dragged to its full width, with the tool call's request and response expanded in the Protocol stream.
64
6165## Servers
6266
6367The Servers screen is the entry point. A server row carries its transport, its connection state, and a control that opens its per-server settings.
from line 75
7175| `--config <path>` | That file, read-only (never written or seeded) | No |
7276| `--server-url <url>` or a positional command | One ad-hoc server, held in memory | No |
7377
74On a first launch the web client seeds the catalog with three sample servers: a filesystem server scoped to `/tmp`, the canonical "everything" reference server, and the MCP org's hosted example server (Streamable HTTP, with OAuth via dynamic client registration). See [Configuration and flags](/docs/draft/tools/inspector/configuration) for the full rules, including why the CLI and TUI seed an empty catalog instead.
78On a first launch the web client seeds the catalog with three sample servers: a filesystem server scoped to `/tmp`, the canonical "everything" reference server, and the MCP org's hosted example server (Streamable HTTP, with OAuth via dynamic client registration). See [Configuration and flags](/docs/draft/tools/inspector/configuration.md) for the full rules, including why the CLI and TUI seed an empty catalog instead.
7579
7680### Server Settings
7781
78* **Protocol Era**: `legacy` / `auto` / `modern`. See [Protocol eras](/docs/draft/tools/inspector/protocol-eras).
79* **Log Level per Request**: the level a modern-era connection stamps on each outgoing request by default, or `off` to opt out (see [Logging](/docs/draft/tools/inspector/protocol-eras#logging)).
80* **Advertised Extensions**: which extensions the Inspector declares in `capabilities.extensions`. A debugging knob: a server may legitimately change what it registers based on what you advertise. Uncheck the Tasks extension and reconnect against the `test-servers/configs/advertised-extensions-http.json` fixture (setup in [Reproducing each era locally](/docs/draft/tools/inspector/protocol-eras#reproducing-each-era-locally)) to watch a tool disappear.
82* **Protocol Era**: `legacy` / `auto` / `modern`. See [Protocol eras](/docs/draft/tools/inspector/protocol-eras.md).
83* **Log Level per Request**: the level a modern-era connection stamps on each outgoing request by default, or `off` to opt out (see [Logging](/docs/draft/tools/inspector/protocol-eras.md#logging)).
84* **Advertised Extensions**: which extensions the Inspector declares in `capabilities.extensions`. A debugging knob: a server may legitimately change what it registers based on what you advertise. Uncheck the Tasks extension and reconnect against the `test-servers/configs/advertised-extensions-http.json` fixture (setup in [Reproducing each era locally](/docs/draft/tools/inspector/protocol-eras.md#reproducing-each-era-locally)) to watch a tool disappear.
8185* **Roots**: the roots advertised via the `roots` client capability. `@modelcontextprotocol/server-filesystem`, for instance, calls `roots/list` to learn its allowed directories.
82* **Headers**, **timeouts**, and **OAuth** fields. Headers are saved in the catalog as written; OAuth client secrets and stdio `env:` values go to the [secret store](/docs/draft/tools/inspector/configuration#where-secrets-are-stored).
83* **OAuth Settings**: client ID and secret, a read-only **Redirect URI** to copy into a pre-registered client (it follows the origin you opened the Inspector at), **Scopes** (space-separated), **Request refresh token**, **Revoke tokens on clear**, additional authorization parameters, authorization and token URL overrides, and **Insufficient-scope response**, which decides whether a `403 insufficient_scope` triggers [step-up](/docs/draft/tools/inspector/authorization#mid-session-re-authorization) or surfaces the error.
86* **Headers**, **timeouts**, and **OAuth** fields. Headers are saved in the catalog as written; OAuth client secrets and stdio `env:` values go to the [secret store](/docs/draft/tools/inspector/configuration.md#where-secrets-are-stored).
87* **OAuth Settings**: client ID and secret, a read-only **Redirect URI** to copy into a pre-registered client (it follows the origin you opened the Inspector at), **Scopes** (space-separated), **Request refresh token**, **Revoke tokens on clear**, additional authorization parameters, authorization and token URL overrides, and **Insufficient-scope response**, which decides whether a `403 insufficient_scope` triggers [step-up](/docs/draft/tools/inspector/authorization.md#mid-session-re-authorization) or surfaces the error.
8488* **Fetch Lists One Page at a Time**: when off, list results are auto-aggregated across pages on connect; when on, each list loads page 1 only with a **Load next page** control and an *N pages loaded* status. Reproduce with `test-servers/configs/pagination-http.json`, which paginates 12 tools, resources, and prompts into three pages each.
8589
8690A footer at the bottom of **Server Settings**, **Client Settings** and the **Add / Edit / Clone server** dialogs names the secret store in use, so you see it where you type a secret. It turns into a warning when secrets are memory-only (lost on restart), in an unencrypted file, in a file with loose permissions, or in a file that can't be read.
from line 91
8791
8892
8993
94Server Settings with Advertised Extensions expanded. Unchecking one changes what the Inspector declares at connect.
95
9096## Tools
9197
9298Select a tool to see its description, its input schema rendered as a form, and its annotations. Fill the form and call it; the result renders below with structured content, embedded resources, and images handled natively.
9399
94On modern-era servers this screen also shows mirrored `Mcp-Param-*` headers, excluded tools, and distinct `-32602` error panels, all covered in [Protocol eras](/docs/draft/tools/inspector/protocol-eras#tools-mirrored-headers-and-excluded-tools).
100On modern-era servers this screen also shows mirrored `Mcp-Param-*` headers, excluded tools, and distinct `-32602` error panels, all covered in [Protocol eras](/docs/draft/tools/inspector/protocol-eras.md#tools-mirrored-headers-and-excluded-tools).
95101
96102
97103
104A tool call and its rendered result. The argument form collapses into the result panel once the call returns.
105
98106## Resources
99107
100Lists resources and resource templates with their MIME types and descriptions, reads content on selection, and offers **Subscribe** on servers that support subscriptions. The subscription mechanics differ by era; see [Resource subscriptions](/docs/draft/tools/inspector/protocol-eras#resource-subscriptions).
108Lists resources and resource templates with their MIME types and descriptions, reads content on selection, and offers **Subscribe** on servers that support subscriptions. The subscription mechanics differ by era; see [Resource subscriptions](/docs/draft/tools/inspector/protocol-eras.md#resource-subscriptions).
101109
102110
103111
112A resource read, with an active subscription listed below the resource list.
113
104114## Prompts
105115
106116Lists prompt templates with their arguments, and renders the generated messages for the arguments you supply, which is the fastest way to confirm a prompt produces what you intended.
from line 117
107117
108118
109119
120A prompt rendered with the arguments supplied.
121
110122## Apps
111123
112[MCP Apps](/extensions/apps/overview) are tools that carry UI. The Apps tab renders one in a sandboxed iframe served from a **separate port**, exercises the `ui/*` bridge, and shows the view's `ui/message` submissions and its `notifications/message` logs in panels below the frame.
124[MCP Apps](/extensions/apps/overview.md) are tools that carry UI. The Apps tab renders one in a sandboxed iframe served from a **separate port**, exercises the `ui/*` bridge, and shows the view's `ui/message` submissions and its `notifications/message` logs in panels below the frame.
113125
114126* The sandbox listens on its own port, `6275` by default (set it with `MCP_SANDBOX_PORT`). An app whose UI resource declares `_meta.ui.domain` has its document served from a third listener, the app origin, on `6278` by default (`MCP_APP_ORIGIN_PORT`). Expose or forward both along with the web port.
115127* The sandbox is gated by a `frame-ancestors` CSP, and a bracketed IPv6 literal is not a valid CSP host-source, so browse the Inspector at `localhost`, `127.0.0.1`, a hostname, or a LAN IPv4, **not** at a bare `http://[::1]:...`.
116128* By default the sandbox URL is plain `http` on the bind address, so an `https://` Inspector page blocks the frame as mixed content. Behind a TLS reverse proxy, set `MCP_SANDBOX_FULL_ADDRESS` (and `MCP_APP_ORIGIN_FULL_ADDRESS`) to the public `https://` address the browser reaches each listener at. Neither may share an origin with the Inspector UI; a value that does is ignored with a warning.
117129
118See [Recipes](/docs/draft/tools/inspector/recipes#reviewing-an-mcp-app) for the CLI-first automated review flow.
130See [Recipes](/docs/draft/tools/inspector/recipes.md#reviewing-an-mcp-app) for the CLI-first automated review flow.
119131
120132
121133
134An MCP App rendered in its sandboxed frame, with the app's own logs below it.
135
122136## Protocol, Network, and Console
123137
124138The three tabs show the same traffic at different levels of detail:
125139
126* **Protocol**: the JSON-RPC transcript. Requests paired with responses, notifications inline, [MRTR](/docs/draft/tools/inspector/protocol-eras#multi-round-tool-results-mrtr) rounds grouped as one conversation, and spec errors rendered by class.
140* **Protocol**: the JSON-RPC transcript. Requests paired with responses, notifications inline, [MRTR](/docs/draft/tools/inspector/protocol-eras.md#multi-round-tool-results-mrtr) rounds grouped as one conversation, and spec errors rendered by class.
127141* **Network**: the HTTP layer, for SSE and Streamable HTTP servers. Status codes, request and response headers, and bodies. On modern connections the standardized `Mcp-*` headers are highlighted and sentinel values decoded.
128142* **Console**: the connected stdio server process's `stderr`, which is where most stdio servers put their own diagnostics.
129143
from line 145
131145
132146
133147
148The Protocol tab with an entry expanded, showing the full JSON-RPC exchange.
149
134150## Deep links
135151
136152A driver (a script, a CI harness, or the CLI's [`--print-handoff`](/docs/draft/tools/inspector/authorization#handing-off-from-the-web-client-to-the-cli)) can reach a *connected* Inspector with a single navigation:
from line 169
153169
154170Binding all interfaces (`HOST=0.0.0.0`) is **refused** unless you set `DANGEROUSLY_BIND_ALL_INTERFACES=true`. Binding a *specific* non-loopback address is allowed with no opt-in, since that's a single deliberate exposure rather than every interface at once.
155171
156See the [Hosting on a network](/docs/draft/tools/inspector/recipes#hosting-on-a-network) recipe for the full matrix, and [Configuration](/docs/draft/tools/inspector/configuration#web-backend-environment-variables) for the variables.
172See the [Hosting on a network](/docs/draft/tools/inspector/recipes.md#hosting-on-a-network) recipe for the full matrix, and [Configuration](/docs/draft/tools/inspector/configuration.md#web-backend-environment-variables) for the variables.
157173
docs/draft/tutorials/security/authorization Changed · +7 / -7 lines
from line 4
44
55Authorization in the Model Context Protocol (MCP) secures access to sensitive resources and operations exposed by MCP servers. If your MCP server handles user data or administrative actions, authorization ensures only permitted users can access its endpoints.
66
7MCP uses standardized authorization flows to build trust between MCP clients and MCP servers. Its design doesn't focus on one specific authorization or identity system, but rather follows the conventions outlined for [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13). For detailed information, see the [Authorization specification](/specification/latest/basic/authorization).
7MCP uses standardized authorization flows to build trust between MCP clients and MCP servers. Its design doesn't focus on one specific authorization or identity system, but rather follows the conventions outlined for [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13). For detailed information, see the [Authorization specification](/specification/latest/basic/authorization.md).
88
99## When Should You Use Authorization?
1010
from line 20
2020>
2121> **Authorization for Local MCP Servers**
2222>
23> For MCP servers using the [STDIO transport](/specification/latest/basic/transports#stdio), you can use environment-based credentials or credentials provided by third-party libraries embedded directly in the MCP server instead. Because a STDIO-built MCP server runs locally, it has access to a range of flexible options when it comes to acquiring user credentials that may or may not rely on in-browser authentication and authorization flows.
23> For MCP servers using the [STDIO transport](/specification/latest/basic/transports.md#stdio), you can use environment-based credentials or credentials provided by third-party libraries embedded directly in the MCP server instead. Because a STDIO-built MCP server runs locally, it has access to a range of flexible options when it comes to acquiring user credentials that may or may not rely on in-browser authentication and authorization flows.
2424>
2525> OAuth flows, in turn, are designed for HTTP-based transports where the MCP server is remotely-hosted and the client uses OAuth to establish that a user is authorized to access said remote server.
2626
from line 242
242242
243243### MCP Server Setup
244244
245We will now set up our MCP server to use the locally-running Keycloak authorization server. Depending on your programming language preference, you can use one of the supported [MCP SDKs](/docs/draft/sdk).
245We will now set up our MCP server to use the locally-running Keycloak authorization server. Depending on your programming language preference, you can use one of the supported [MCP SDKs](/docs/draft/sdk.md).
246246
247247For our testing purposes, we will create an extremely simple MCP server that exposes two tools - one for addition and another for multiplication. The server will require authorization to access these.
248248
from line 1042
10421042
10431043## Common Pitfalls and How to Avoid Them
10441044
1045For comprehensive security guidance, including attack vectors, mitigation strategies, and implementation best practices, make sure to read through [Security Best Practices](/specification/draft/basic/security_best_practices). A few key issues are called out below.
1045For comprehensive security guidance, including attack vectors, mitigation strategies, and implementation best practices, make sure to read through [Security Best Practices](/specification/draft/basic/security_best_practices.md). A few key issues are called out below.
10461046
10471047* **Do not implement token validation or authorization logic by yourself**. Use off-the-shelf, well-tested, and secure libraries for things like token validation or authorization decisions. Doing everything from scratch means that you're more likely to implement things incorrectly unless you are a security expert.
10481048* **Use short-lived access tokens**. Depending on the authorization server used, this setting might be customizable. We recommend to not use long-lived tokens - if a malicious actor steals them, they will be able to maintain their access for longer periods.
from line 1071
10711071
10721072For additional details, refer to:
10731073
1074* [Authorization Specification](/specification/draft/basic/authorization)
1075* [Security Best Practices](/specification/draft/basic/security_best_practices)
1076* [Available MCP SDKs](/docs/draft/sdk)
1074* [Authorization Specification](/specification/draft/basic/authorization.md)
1075* [Security Best Practices](/specification/draft/basic/security_best_practices.md)
1076* [Available MCP SDKs](/docs/draft/sdk.md)
10771077
10781078Understanding these standards will help you implement authorization correctly and troubleshoot issues when they arise.
10791079
docs/draft/tutorials/security/local-server-security Changed · +9 / -9 lines
from line 4
44
55Most MCP security documentation covers the protocol threat model: OAuth flows,
66token handling, session hijacking, and confused deputy attacks. For those, see
7[Authorization](/docs/draft/tutorials/security/authorization) and
8[Security Best Practices](/docs/draft/tutorials/security/security_best_practices).
7[Authorization](/docs/draft/tutorials/security/authorization.md) and
8[Security Best Practices](/docs/draft/tutorials/security/security_best_practices.md).
99
1010This guide covers a different threat model: **your machine**. When you run an
1111MCP server locally, you download code from the internet and run it as a child
from line 46
4646
4747Clients that offer one-click installation are required to show you the exact
4848command before it runs
49([SEP-1024](/seps/1024-mcp-client-security-requirements-for-local-server-)),
49([SEP-1024](/seps/1024-mcp-client-security-requirements-for-local-server-.md)),
5050but a consent dialog only helps if you know what to look for. That is what
5151the rest of this guide is about.
5252
from line 131
131131your laptop, while you take on everything else in this guide for no benefit.
132132
133133* **Prefer the remote version where one exists.** A server offered over
134 [Streamable HTTP](/specification/draft/basic/transports/streamable-http)
134 [Streamable HTTP](/specification/draft/basic/transports/streamable-http.md)
135135 runs no code on your machine, uses the protocol's authorization flow
136136 instead of a token in a local config file, and is patched in one place.
137137 The protocol threat model (linked above) applies to it instead of this
from line 197
197197
198198* **Read the tool list before you rely on a server.** Most clients can show
199199 each tool's description, and the
200 [MCP Inspector](/docs/draft/tools/inspector) lists every tool a
200 [MCP Inspector](/docs/draft/tools/inspector.md) lists every tool a
201201 server exposes without a model in the loop. If a description contains
202202 instructions that have nothing to do with the tool's job, remove the
203203 server.
from line 419
419419
420420## Next Steps
421421
422> **[Security Best Practices](/docs/draft/tutorials/security/security_best_practices)**
422> **[Security Best Practices](/docs/draft/tutorials/security/security_best_practices.md)**
423423>
424424> The protocol threat model: confused deputy, token passthrough, and session
425425> hijacking
426426
427> **[Authorization](/docs/draft/tutorials/security/authorization)**
427> **[Authorization](/docs/draft/tutorials/security/authorization.md)**
428428>
429429> How OAuth-based authorization works for remote MCP servers
430430
431> **[SEP-1024](/seps/1024-mcp-client-security-requirements-for-local-server-)**
431> **[SEP-1024](/seps/1024-mcp-client-security-requirements-for-local-server-.md)**
432432>
433433> Client security requirements for local server installation consent
434434
435> **[Connect to local servers](/docs/draft/develop/connect-local-servers)**
435> **[Connect to local servers](/docs/draft/develop/connect-local-servers.md)**
436436>
437437> Set up local servers in your client — the workflow this guide secures
438438
docs/draft/tutorials/security/security_best_practices Changed · +13 / -13 lines
from line 8
88
99This document provides security considerations for the Model Context
1010Protocol (MCP), complementing the
11[MCP Authorization](/specification/latest/basic/authorization)
11[MCP Authorization](/specification/latest/basic/authorization.md)
1212specification. This document identifies security risks, attack vectors,
1313and best practices specific to MCP implementations.
1414
from line 148
148148 consent screen
1491496. The MCP authorization code is redirected to the attacker's server
150150 (specified in the malicious `redirect_uri` parameter during
151 [dynamic client registration](/specification/latest/basic/authorization#dynamic-client-registration))
151 [dynamic client registration](/specification/latest/basic/authorization.md#dynamic-client-registration))
1521527. The attacker exchanges the stolen authorization code for access
153153 tokens for the MCP server without the user's explicit approval
1541548. The attacker now has access to the third-party API as the compromised
from line 303
303303#### Risks
304304
305305Token passthrough is explicitly forbidden in the
306[authorization specification](/specification/latest/basic/authorization)
306[authorization specification](/specification/latest/basic/authorization.md)
307307as it introduces a number of security risks, that include:
308308
309309* **Security Control Circumvention**
from line 484
484484
485485SSRF risks are not limited to MCP clients. When an authorization
486486server supports
487[Client ID Metadata Documents](/specification/draft/basic/authorization/client-registration#client-id-metadata-documents),
487[Client ID Metadata Documents](/specification/draft/basic/authorization/client-registration.md#client-id-metadata-documents),
488488the authorization server takes a URL as input from an unknown client
489489and fetches that URL. A malicious client could use this to trigger
490490the authorization server to make requests to arbitrary URLs, such as
from line 514
514514
515515### State Handle Hijacking
516516
517MCP is [stateless](/specification/draft/basic/index#statelessness) and
517MCP is [stateless](/specification/draft/basic/index.md#statelessness) and
518518has no protocol-level sessions. Servers that need state spanning
519519multiple requests mint an explicit handle, such as a shopping cart ID
520520or a workflow ID, and receive it back as an ordinary tool argument on
from line 553
553553
554554For guidance on securing the server-assigned session IDs used by
555555protocol version `2025-11-25` and earlier, see
556[Session Hijacking in the 2025-11-25 version of this page](/docs/2025-11-25/tutorials/security/security_best_practices#session-hijacking).
556[Session Hijacking in the 2025-11-25 version of this page](/docs/2025-11-25/tutorials/security/security_best_practices.md#session-hijacking).
557557
558558### Local MCP Server Compromise
559559
from line 806
806806
807807#### Mitigation
808808
809[Authorization Response Validation](/specification/draft/basic/authorization#authorization-response-validation)
809[Authorization Response Validation](/specification/draft/basic/authorization.md#authorization-response-validation)
810810mitigates this by binding the response to the authorization server
811811the client recorded before redirecting, so the authorization code
812812cannot be redeemed at an unintended token endpoint. PKCE alone does
from line 821
821821
822822Native and locally-running MCP clients commonly use `localhost`
823823redirect URIs. When clients identify themselves with
824[Client ID Metadata Documents](/specification/draft/basic/authorization/client-registration#client-id-metadata-documents),
824[Client ID Metadata Documents](/specification/draft/basic/authorization/client-registration.md#client-id-metadata-documents),
825825the metadata document proves control of a domain, but it cannot prove
826826which local process is listening on a `localhost` redirect URI.
827827
from line 842
842842#### Mitigation
843843
844844See
845[Localhost Redirect URI Risks](/specification/draft/basic/authorization/security-considerations#localhost-redirect-uri-risks)
845[Localhost Redirect URI Risks](/specification/draft/basic/authorization/security-considerations.md#localhost-redirect-uri-risks)
846846in the authorization specification for the countermeasures expected
847847of authorization servers, including displaying additional warnings for
848848`localhost`-only redirect URIs and clearly displaying the redirect URI
from line 851
851851### CIMD Trust Policies
852852
853853Authorization servers that accept
854[Client ID Metadata Documents](/specification/draft/basic/authorization/client-registration#client-id-metadata-documents)
854[Client ID Metadata Documents](/specification/draft/basic/authorization/client-registration.md#client-id-metadata-documents)
855855can apply domain-based trust policies to decide which URL-based
856856client IDs to accept:
857857
from line 863
863863 to prevent phishing
864864
865865Servers maintain full control over their access policies. See
866[Trust Policies](/specification/draft/basic/authorization/security-considerations#trust-policies)
866[Trust Policies](/specification/draft/basic/authorization/security-considerations.md#trust-policies)
867867in the authorization specification, along with
868868[Section 6.4](https://www.ietf.org/archive/id/draft-ietf-oauth-client-id-metadata-document-00.html#section-6.4)
869869and
from line 936
936936
937937When the initial `WWW-Authenticate` challenge carries no `scope`
938938parameter, the
939[Scope Selection Strategy](/specification/draft/basic/authorization#scope-selection-strategy)
939[Scope Selection Strategy](/specification/draft/basic/authorization.md#scope-selection-strategy)
940940directs clients to fall back to requesting all scopes listed in
941941`scopes_supported`. This approach accommodates the general-purpose
942942nature of MCP clients, which typically lack domain-specific knowledge
from line 952
952952> **SHOULD** compute the union of previously requested scopes and newly
953953> challenged scopes when initiating re-authorization, as described in [Step-Up
954954> Authorization
955> Flow](/specification/draft/basic/authorization#step-up-authorization-flow).
955> Flow](/specification/draft/basic/authorization.md#step-up-authorization-flow).
956956> This allows servers to remain stateless with respect to client scope sets
957957> while ensuring clients do not lose previously granted permissions.
958958
extensions/apps/build Changed · +10 / -2 lines
from line 5
55## Prerequisites
66
77You'll need [Node.js](https://nodejs.org/en/download) 18 or higher. Familiarity
8with [MCP tools](/specification/latest/server/tools) and
9[resources](/specification/latest/server/resources) is recommended since MCP
8with [MCP tools](/specification/latest/server/tools.md) and
9[resources](/specification/latest/server/resources.md) is recommended since MCP
1010Apps combine both primitives. Experience with the
1111[MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
1212will help you better understand the server-side patterns.
from line 98
9898
9999
100100
101Creating a new MCP App with Claude Code
102
101103**3. Run your app**
102104
103105```bash macOS/Linux theme={null}
from line 120
118120
119121
120122
123Testing the color picker in Claude
124
121125### Manual setup
122126
123127If you're not using an AI coding agent, or prefer to understand the setup
from line 430
426430
427431
428432
433Adding a custom connector in Claude
434
429435### Testing with the basic-host
430436
431437The `ext-apps` repository includes a test host for development. Clone the repo and
from line 467
461467app and verify that tool calls work correctly.
462468
463469
470
471Testing the QR code MCP App with the basic host
464472
465473## Learn more
466474
extensions/apps/overview Changed · +5 / -3 lines
from line 12
1212
1313
1414
15Excalidraw MCP App, running in Claude
16
1517## Why not just build a web app?
1618
1719You could build a standalone web app and send users a link. However, MCP Apps
from line 167
165167
166168> [!NOTE]
167169>
168> MCP Apps is an extension to the [core MCP specification](/specification/latest). Host support varies by client.
170> MCP Apps is an extension to the [core MCP specification](/specification/latest.md). Host support varies by client.
169171
170172MCP Apps are currently supported by [Claude](https://claude.ai),
171173[Claude Desktop](https://claude.ai/download),
172174[VS Code GitHub Copilot](https://code.visualstudio.com/), [Microsoft 365 Copilot](https://www.microsoft.com/microsoft-365-copilot), [Goose](https://block.github.io/goose/), [Postman](https://postman.com), [MCPJam](https://www.mcpjam.com/), and [Archestra.AI](https://www.archestra.ai/). See the
173[client matrix](/extensions/client-matrix) for the full list of extension support across clients.
175[client matrix](/extensions/client-matrix.md) for the full list of extension support across clients.
174176
175177If you're building an MCP client and want to support MCP Apps, you have two options:
176178
from line 229
227229 [Solid](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-solid),
228230 [vanilla JavaScript](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)
229231
230To start building your own MCP App, see the [build guide](/extensions/apps/build).
232To start building your own MCP App, see the [build guide](/extensions/apps/build.md).
231233
extensions/auth/enterprise-managed-authorization Changed · +3 / -3 lines
from line 135
135135>
136136> Support for this extension varies by client. Extensions are opt-in and never active by default.
137137
138Check the [client matrix](/extensions/client-matrix) for current implementation status across MCP clients. Enterprise-Managed Authorization typically requires client-level support from the organization's IT team in addition to the MCP client application.
138Check the [client matrix](/extensions/client-matrix.md) for current implementation status across MCP clients. Enterprise-Managed Authorization typically requires client-level support from the organization's IT team in addition to the MCP client application.
139139
140140## Related resources
141141
from line 147
147147>
148148> Technical specification with normative requirements
149149
150> **[SEP-990](/seps/990-enable-enterprise-idp-policy-controls-during-mcp-o)**
150> **[SEP-990](/seps/990-enable-enterprise-idp-policy-controls-during-mcp-o.md)**
151151>
152152> Original proposal: Enable Enterprise IdP Policy Controls
153153
154> **[MCP Authorization](/specification/latest/basic/authorization)**
154> **[MCP Authorization](/specification/latest/basic/authorization.md)**
155155>
156156> Core MCP authorization specification
157157
extensions/auth/overview Changed · +10 / -10 lines
from line 11
1111
1212## Why authorization extensions?
1313
14The core MCP specification includes a robust [authorization framework](/specification/latest/basic/authorization) built on OAuth 2.0. That framework handles the common case well: a user interactively grants an MCP client permission to access a server on their behalf.
14The core MCP specification includes a robust [authorization framework](/specification/latest/basic/authorization.md) built on OAuth 2.0. That framework handles the common case well: a user interactively grants an MCP client permission to access a server on their behalf.
1515
1616But not every MCP deployment fits this pattern:
1717
from line 22
2222
2323## Available extensions
2424
25> **[OAuth Client Credentials](/extensions/auth/oauth-client-credentials)**
25> **[OAuth Client Credentials](/extensions/auth/oauth-client-credentials.md)**
2626>
2727> Machine-to-machine authentication using the OAuth 2.0 client credentials
2828> flow. No user interaction required.
2929
30> **[Enterprise-Managed Authorization](/extensions/auth/enterprise-managed-authorization)**
30> **[Enterprise-Managed Authorization](/extensions/auth/enterprise-managed-authorization.md)**
3131>
3232> Centralized access control via enterprise identity providers. Employees
3333> access MCP servers through their organization's IdP.
from line 36
3636
3737| Scenario | Recommended extension |
3838| - | - |
39| Background service or daemon accessing an MCP server | [OAuth Client Credentials](/extensions/auth/oauth-client-credentials) |
40| CI/CD pipeline calling MCP tools | [OAuth Client Credentials](/extensions/auth/oauth-client-credentials) |
41| Server-to-server API integration | [OAuth Client Credentials](/extensions/auth/oauth-client-credentials) |
42| Enterprise employees accessing MCP servers at work | [Enterprise-Managed Authorization](/extensions/auth/enterprise-managed-authorization) |
43| Organization-wide MCP access policy enforcement | [Enterprise-Managed Authorization](/extensions/auth/enterprise-managed-authorization) |
39| Background service or daemon accessing an MCP server | [OAuth Client Credentials](/extensions/auth/oauth-client-credentials.md) |
40| CI/CD pipeline calling MCP tools | [OAuth Client Credentials](/extensions/auth/oauth-client-credentials.md) |
41| Server-to-server API integration | [OAuth Client Credentials](/extensions/auth/oauth-client-credentials.md) |
42| Enterprise employees accessing MCP servers at work | [Enterprise-Managed Authorization](/extensions/auth/enterprise-managed-authorization.md) |
43| Organization-wide MCP access policy enforcement | [Enterprise-Managed Authorization](/extensions/auth/enterprise-managed-authorization.md) |
4444| Standard interactive user authorization | Core MCP spec (no extension needed) |
4545
4646## Client support
4747
48Authorization extension support varies by client. See the [client matrix](/extensions/client-matrix) for a full breakdown. Both extensions require explicit support from the MCP client — they are never active by default.
48Authorization extension support varies by client. See the [client matrix](/extensions/client-matrix.md) for a full breakdown. Both extensions require explicit support from the MCP client — they are never active by default.
4949
5050## Specification
5151
52Both extensions are specified in the [ext-auth repository](https://github.com/modelcontextprotocol/ext-auth/tree/main/specification/draft). They use the standard MCP [extension negotiation](/extensions/overview#negotiation) mechanism: clients declare support in the `extensions` field of the `io.modelcontextprotocol/clientCapabilities` they send in each request's `_meta`, and servers advertise theirs in the capabilities returned by [`server/discover`](/specification/draft/server/discover).
52Both extensions are specified in the [ext-auth repository](https://github.com/modelcontextprotocol/ext-auth/tree/main/specification/draft). They use the standard MCP [extension negotiation](/extensions/overview.md#negotiation) mechanism: clients declare support in the `extensions` field of the `io.modelcontextprotocol/clientCapabilities` they send in each request's `_meta`, and servers advertise theirs in the capabilities returned by [`server/discover`](/specification/draft/server/discover).
5353
extensions/client-matrix Changed · +7 / -7 lines
from line 2
22
33> Which MCP clients implement which official extensions
44
5This matrix shows which MCP clients support each [official extension](/extensions/overview). Extensions are always opt-in: a client only uses an extension if both client and server declare support in the `extensions` field of their [capabilities](/extensions/overview#negotiation).
5This matrix shows which MCP clients support each [official extension](/extensions/overview.md). Extensions are always opt-in: a client only uses an extension if both client and server declare support in the `extensions` field of their [capabilities](/extensions/overview.md#negotiation).
66
77> [!NOTE]
88>
from line 12
1212
1313| Extension | Identifier | Description |
1414| - | - | - |
15| [MCP Apps](/extensions/apps/overview) | `io.modelcontextprotocol/ui` | Interactive HTML interfaces rendered inline in the conversation |
16| [OAuth Client Credentials](/extensions/auth/oauth-client-credentials) | `io.modelcontextprotocol/oauth-client-credentials` | Machine-to-machine auth without interactive user login |
17| [Enterprise-Managed Authorization](/extensions/auth/enterprise-managed-authorization) | `io.modelcontextprotocol/enterprise-managed-authorization` | Centralized access control via enterprise IdP |
18| [Skills over MCP](/extensions/skills/overview) | `io.modelcontextprotocol/skills` | Discover skills and read their instructions and supporting files |
15| [MCP Apps](/extensions/apps/overview.md) | `io.modelcontextprotocol/ui` | Interactive HTML interfaces rendered inline in the conversation |
16| [OAuth Client Credentials](/extensions/auth/oauth-client-credentials.md) | `io.modelcontextprotocol/oauth-client-credentials` | Machine-to-machine auth without interactive user login |
17| [Enterprise-Managed Authorization](/extensions/auth/enterprise-managed-authorization.md) | `io.modelcontextprotocol/enterprise-managed-authorization` | Centralized access control via enterprise IdP |
18| [Skills over MCP](/extensions/skills/overview.md) | `io.modelcontextprotocol/skills` | Discover skills and read their instructions and supporting files |
1919
2020## Support matrix
2121
22| Client | [MCP Apps](/extensions/apps/overview) | [OAuth Client Credentials](/extensions/auth/oauth-client-credentials) | [Enterprise Auth](/extensions/auth/enterprise-managed-authorization) | [Skills](/extensions/skills/overview) |
22| Client | [MCP Apps](/extensions/apps/overview.md) | [OAuth Client Credentials](/extensions/auth/oauth-client-credentials.md) | [Enterprise Auth](/extensions/auth/enterprise-managed-authorization.md) | [Skills](/extensions/skills/overview.md) |
2323| - | :-: | :-: | :-: | :-: |
2424| [Claude (web)](https://claude.ai) | | | | |
2525| [Claude Desktop](https://claude.ai/download) | | | | |
from line 49
49493. Implement the extension's protocol requirements
50504. Submit a pull request to update this matrix
5151
52See [Extensions Overview](/extensions/overview#negotiation) for details on the capability negotiation mechanism.
52See [Extensions Overview](/extensions/overview.md#negotiation) for details on the capability negotiation mechanism.
5353
extensions/overview Changed · +13 / -13 lines
from line 25
2525
2626| Extension | Description |
2727| - | - |
28| [OAuth Client Credentials](/extensions/auth/oauth-client-credentials) | OAuth 2.0 client credentials flow for machine-to-machine authentication. |
29| [Enterprise-Managed Authorization](/extensions/auth/enterprise-managed-authorization) | Framework for enterprise environments requiring centralized access control. |
28| [OAuth Client Credentials](/extensions/auth/oauth-client-credentials.md) | OAuth 2.0 client credentials flow for machine-to-machine authentication. |
29| [Enterprise-Managed Authorization](/extensions/auth/enterprise-managed-authorization.md) | Framework for enterprise environments requiring centralized access control. |
3030
3131### MCP Apps
3232
from line 36
3636
3737| Extension | Description |
3838| - | - |
39| [MCP Apps](/extensions/apps/overview) | Allows MCP Servers to display interactive UI elements (charts, forms, video players) inline within conversations |
39| [MCP Apps](/extensions/apps/overview.md) | Allows MCP Servers to display interactive UI elements (charts, forms, video players) inline within conversations |
4040
41To get started building MCP Apps, see the [quickstart guide](/extensions/apps/build#getting-started) or read the full [MCP Apps documentation](https://apps.extensions.modelcontextprotocol.io/api/documents/Quickstart.html).
41To get started building MCP Apps, see the [quickstart guide](/extensions/apps/build.md#getting-started) or read the full [MCP Apps documentation](https://apps.extensions.modelcontextprotocol.io/api/documents/Quickstart.html).
4242
4343### MCP Tasks
4444
4545| Extension | Description |
4646| - | - |
47| [MCP Tasks](/extensions/tasks/overview) | Asynchronous task execution for long-running operations, with polling, mid-flight input, and durable handles. |
47| [MCP Tasks](/extensions/tasks/overview.md) | Asynchronous task execution for long-running operations, with polling, mid-flight input, and durable handles. |
4848
4949### Skills over MCP
5050
from line 54
5454
5555| Extension | Description |
5656| - | - |
57| [Skills over MCP](/extensions/skills/overview) | Discover workflow instructions and read supporting files through MCP resources. |
57| [Skills over MCP](/extensions/skills/overview.md) | Discover workflow instructions and read supporting files through MCP resources. |
5858
59See the [Skills overview](/extensions/skills/overview) to get started and the
60[client matrix](/extensions/client-matrix) for implementation support.
59See the [Skills overview](/extensions/skills/overview.md) to get started and the
60[client matrix](/extensions/client-matrix.md) for implementation support.
6161
6262## Experimental Extensions
6363
64Experimental extensions provide an incubation pathway for [Working Groups and Interest Groups](/community/working-interest-groups) to prototype ideas and collaborate on extension concepts before formal SEP submission.
64Experimental extensions provide an incubation pathway for [Working Groups and Interest Groups](/community/working-interest-groups.md) to prototype ideas and collaborate on extension concepts before formal SEP submission.
6565
6666Experimental extension repositories live within the MCP GitHub organization with the `experimental-ext-` prefix (e.g., `experimental-ext-interceptors`).
6767
from line 69
6969
7070* Every experimental extension needs to be associated with a Working Group or Interest Group
7171* Repositories and published packages need to clearly indicate their experimental status (e.g., in the README and package name)
72* [Core Maintainers](/community/contributor-ladder#core-maintainer) retain oversight of experimental extension repositories, including the ability to archive or remove them
72* [Core Maintainers](/community/contributor-ladder.md#core-maintainer) retain oversight of experimental extension repositories, including the ability to archive or remove them
7373
7474### Graduation to Official Status
7575
from line 77
7777
7878## Creating Extensions
7979
80The lifecycle for official extensions follows a SEP-based process. For full details, see [SEP-2133: Extensions](/seps/2133-extensions).
80The lifecycle for official extensions follows a SEP-based process. For full details, see [SEP-2133: Extensions](/seps/2133-extensions.md).
8181
821. **Propose**: Create a SEP in the main MCP repository using the [standard SEP guidelines](/community/sep-guidelines) with type **Extensions Track**.
821. **Propose**: Create a SEP in the main MCP repository using the [standard SEP guidelines](/community/sep-guidelines.md) with type **Extensions Track**.
83832. **Implement**: Build at least one reference implementation in an official SDK — this is required before the SEP can be reviewed.
843. **Review**: [Core Maintainers](/community/contributor-ladder#core-maintainer) review the SEP and have final authority over inclusion.
843. **Review**: [Core Maintainers](/community/contributor-ladder.md#core-maintainer) review the SEP and have final authority over inclusion.
85854. **Publish**: Once approved, open a PR to add the extension to the extension repository.
86865. **Adopt**: After that, other clients, servers, and SDKs can implement the extension too.
8787