diff --git a/docs/docs.json b/docs/docs.json index 21cbbe138..0c5e7ac3f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -428,6 +428,12 @@ "seps/2207-oidc-refresh-token-guidance", "seps/2260-Require-Server-requests-to-be-associated-with-Client-requests" ] + }, + { + "group": "Draft", + "pages": [ + "seps/2692-stdio-server-process-lifetime" + ] } ] }, diff --git a/docs/docs/develop/clients/client-best-practices.mdx b/docs/docs/develop/clients/client-best-practices.mdx index d976803ec..3718ebfa6 100644 --- a/docs/docs/develop/clients/client-best-practices.mdx +++ b/docs/docs/develop/clients/client-best-practices.mdx @@ -100,7 +100,12 @@ Progressive discovery extends beyond individual tools to entire servers. Rather 1. Maintain a registry of available servers and their high-level descriptions. 2. Connect to a server only when the model determines it needs that server's capabilities. -3. Disconnect servers that are no longer relevant to the current task, freeing context. +3. Disconnect servers when an explicit host policy determines they are no longer needed, + such as server disablement or application shutdown. + +For stdio servers, the end of a task or conversation should not by itself be the default +disconnect signal. A connected stdio server should generally remain available across +multiple conversations while the host application still needs it. ```mermaid sequenceDiagram diff --git a/docs/seps/2692-stdio-server-process-lifetime.mdx b/docs/seps/2692-stdio-server-process-lifetime.mdx new file mode 100644 index 000000000..5d925b62e --- /dev/null +++ b/docs/seps/2692-stdio-server-process-lifetime.mdx @@ -0,0 +1,110 @@ +--- +title: "SEP-2692: stdio Server Process Lifetime" +sidebarTitle: "SEP-2692: stdio Server Process Lifetime" +description: "stdio Server Process Lifetime" +--- + +
+ + Draft + + + Informational + +
+ +| Field | Value | +| ------------- | ------------------------------------------------------------------------------- | +| **SEP** | 2692 | +| **Title** | stdio Server Process Lifetime | +| **Status** | Draft | +| **Type** | Informational | +| **Created** | 2026-05-06 | +| **Author(s)** | Nick Cooper ([@nickcoai](https://github.com/nickcoai)) | +| **Sponsor** | Nick Cooper [@nickcoai](https://github.com/nickcoai) | +| **PR** | [#2692](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2692) | + +--- + +## Abstract + +This SEP documents the intended process lifetime for MCP servers using the stdio transport. +For stdio, the server process is expected to live approximately as long as the host +application instance that launched it, rather than being scoped to a single task, +thread, or conversation. A single stdio server process should therefore be able to +serve multiple conversations over its lifetime. + +This is a documentation-only clarification. It does not change the wire protocol, +schema, or lifecycle messages. + +## Motivation + +The stdio transport documentation states that the client launches the MCP server as a +subprocess, but it does not explicitly define the intended lifetime boundary for that +subprocess. In practice, this leaves room for implementations to treat a task, thread, +or conversation as the natural process boundary. + +That interpretation is undesirable: + +- It conflates application-level concepts such as tasks and conversations with the + transport-level lifetime of the server process. +- It can cause unnecessary process churn and repeated initialization work. +- It can lead server authors to assume that process-local state is discarded between + conversations, even though a stdio server may continue serving the host application + across many of them. + +Clients and server authors need an explicit statement of the intended model so that +stdio implementations converge on the same operational assumptions. + +## Specification + +The MCP documentation should clarify the following expectations for the stdio +transport: + +1. A stdio MCP server process is expected to have approximately the same lifetime as + the host application instance that launched it. +2. Stdio clients should not use an individual task, thread, or conversation as the + default lifetime boundary for the server process. +3. While a stdio server process remains connected to a host application, it should be + expected to handle requests associated with multiple tasks, threads, or + conversations. +4. Stdio server authors should design their servers with the expectation that a single + process can serve multiple conversations over its lifetime. +5. Host applications may still intentionally start, stop, or restart stdio servers for + application-level reasons such as configuration changes, explicit server disablement, + crash recovery, or application shutdown. This clarification does not require every + configured server to remain running forever. + +These statements should be added to the stdio transport documentation and reflected in +client- and server-facing documentation where stdio lifecycle expectations are +described. + +## Rationale + +The host application is the most natural owner of a stdio subprocess: it launches the +server, owns the pipes, and decides when the subprocess is no longer needed. Tasks, +threads, and conversations are application-level concepts that may come and go while +the same host application instance remains active, so they are poor default process +lifetime boundaries. + +A task-scoped or conversation-scoped process model can be useful as an intentional host +implementation choice, but documenting it as the default would make stdio behavior less +predictable and would encourage servers to assume a narrower lifetime than the transport +actually requires. + +This clarification also keeps stdio aligned with the transport documentation's existing +subprocess model while leaving host applications free to apply explicit resource +management policies when they choose to do so. + +## Backward Compatibility + +This SEP introduces no protocol or wire-format changes. It only clarifies the intended +documentation of existing stdio behavior. + +## Security Implications + +This SEP introduces no new security implications. + +## Reference Implementation + +Not applicable. This SEP proposes documentation-only clarification. diff --git a/docs/seps/index.mdx b/docs/seps/index.mdx index ad95db3bc..46c0812d0 100644 --- a/docs/seps/index.mdx +++ b/docs/seps/index.mdx @@ -12,6 +12,7 @@ Specification Enhancement Proposals (SEPs) are the primary mechanism for proposi ## Summary +- **Draft**: 1 - **Accepted**: 2 - **Final**: 28 @@ -19,6 +20,7 @@ Specification Enhancement Proposals (SEPs) are the primary mechanism for proposi | SEP | Title | Status | Type | Created | | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------- | ---------------- | ---------- | +| [SEP-2692](/seps/2692-stdio-server-process-lifetime) | stdio Server Process Lifetime | Draft | Informational | 2026-05-06 | | [SEP-2260](/seps/2260-Require-Server-requests-to-be-associated-with-Client-requests) | Require Server requests to be associated with a Client request. | Accepted | Standards Track | 2026-02-16 | | [SEP-2243](/seps/2243-http-standardization) | HTTP Header Standardization for Streamable HTTP Transport | Final | Standards Track | 2026-02-04 | | [SEP-2207](/seps/2207-oidc-refresh-token-guidance) | OIDC-Flavored Refresh Token Guidance | Accepted | Standards Track | 2026-02-04 | diff --git a/docs/specification/draft/basic/transports.mdx b/docs/specification/draft/basic/transports.mdx index 3f73b8663..8983c60e2 100644 --- a/docs/specification/draft/basic/transports.mdx +++ b/docs/specification/draft/basic/transports.mdx @@ -22,6 +22,12 @@ It is also possible for clients and servers to implement In the **stdio** transport: - The client launches the MCP server as a subprocess. +- The server process **SHOULD** have approximately the same lifetime as the host + application instance that launched it. +- Clients **SHOULD NOT** use an individual task, thread, or conversation as the default + lifetime boundary for the server process. +- While the server process remains connected to the host application, it **SHOULD** be + prepared to handle requests associated with multiple tasks, threads, or conversations. - The server reads JSON-RPC messages from its standard input (`stdin`) and sends messages to its standard output (`stdout`). - Messages are individual JSON-RPC requests, notifications, or responses. diff --git a/seps/2692-stdio-server-process-lifetime.md b/seps/2692-stdio-server-process-lifetime.md new file mode 100644 index 000000000..096cb7019 --- /dev/null +++ b/seps/2692-stdio-server-process-lifetime.md @@ -0,0 +1,91 @@ +# SEP-2692: stdio Server Process Lifetime + +- **Status**: Draft +- **Type**: Informational +- **Created**: 2026-05-06 +- **Author(s)**: Nick Cooper (@nickcoai) +- **Sponsor**: Nick Cooper @nickcoai +- **PR**: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/{2692} + +## Abstract + +This SEP documents the intended process lifetime for MCP servers using the stdio transport. +For stdio, the server process is expected to live approximately as long as the host +application instance that launched it, rather than being scoped to a single task, +thread, or conversation. A single stdio server process should therefore be able to +serve multiple conversations over its lifetime. + +This is a documentation-only clarification. It does not change the wire protocol, +schema, or lifecycle messages. + +## Motivation + +The stdio transport documentation states that the client launches the MCP server as a +subprocess, but it does not explicitly define the intended lifetime boundary for that +subprocess. In practice, this leaves room for implementations to treat a task, thread, +or conversation as the natural process boundary. + +That interpretation is undesirable: + +- It conflates application-level concepts such as tasks and conversations with the + transport-level lifetime of the server process. +- It can cause unnecessary process churn and repeated initialization work. +- It can lead server authors to assume that process-local state is discarded between + conversations, even though a stdio server may continue serving the host application + across many of them. + +Clients and server authors need an explicit statement of the intended model so that +stdio implementations converge on the same operational assumptions. + +## Specification + +The MCP documentation should clarify the following expectations for the stdio +transport: + +1. A stdio MCP server process is expected to have approximately the same lifetime as + the host application instance that launched it. +2. Stdio clients should not use an individual task, thread, or conversation as the + default lifetime boundary for the server process. +3. While a stdio server process remains connected to a host application, it should be + expected to handle requests associated with multiple tasks, threads, or + conversations. +4. Stdio server authors should design their servers with the expectation that a single + process can serve multiple conversations over its lifetime. +5. Host applications may still intentionally start, stop, or restart stdio servers for + application-level reasons such as configuration changes, explicit server disablement, + crash recovery, or application shutdown. This clarification does not require every + configured server to remain running forever. + +These statements should be added to the stdio transport documentation and reflected in +client- and server-facing documentation where stdio lifecycle expectations are +described. + +## Rationale + +The host application is the most natural owner of a stdio subprocess: it launches the +server, owns the pipes, and decides when the subprocess is no longer needed. Tasks, +threads, and conversations are application-level concepts that may come and go while +the same host application instance remains active, so they are poor default process +lifetime boundaries. + +A task-scoped or conversation-scoped process model can be useful as an intentional host +implementation choice, but documenting it as the default would make stdio behavior less +predictable and would encourage servers to assume a narrower lifetime than the transport +actually requires. + +This clarification also keeps stdio aligned with the transport documentation's existing +subprocess model while leaving host applications free to apply explicit resource +management policies when they choose to do so. + +## Backward Compatibility + +This SEP introduces no protocol or wire-format changes. It only clarifies the intended +documentation of existing stdio behavior. + +## Security Implications + +This SEP introduces no new security implications. + +## Reference Implementation + +Not applicable. This SEP proposes documentation-only clarification.