René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Proposal: Add client state persistence API to allow MCP clients to survive restarts","articleBody":"# Motivation\n\n## Problem Statement\n\nThe **current Java MCP SDK provides no mechanism for persisting client runtime state**. Without SDK support, it is **impossible** for applications to resume a prior session, reuse an existing access token, or skip redundant protocol negotiation after a restart.\n\n## Example Failure Scenario\n\n1. **Startup** – An `McpClient` sends an `initialize` request to `https://example.com/mcp`.  \n2. **Session established** – The server responds with `Mcp-Session-Id: 1868a90c…`; the client continues issuing requests within that session. The server may create associated state (e.g., cached prompts, resources, intermediate results) tied to the session ID.  \n3. **Crash / redeploy** – The JVM crashes or the container restarts.  \n4. **Restart** – The new client instance knows nothing about the previous session ID, access token, or negotiated metadata. As a result, it must repeat the OAuth flow and send a new `initialize` request, forcing the server to discard prior state and degrading the user experience.\n\n## Impact\n\nIntroducing a **first-class SDK abstraction** for state persistence will deliver:\n\n* **Improve reliability** – Maintain continuity for long-running operations that depend on server-side session state\n* **Better user experience** – Seamless resumption without re-authentication delays\n* **Production readiness** – Essential for containerized environments with frequent deployments\n* **Operational simplicity** – Let the host application decide *where* and *how* to store this data (e.g., files, JDBC, Redis, secret vault) while keeping the SDK storage-agnostic\n\n## Use Cases\n\nThis feature is particularly valuable for:\n- **Long-running applications** that need to survive restarts without losing context\n- **Containerized environments** with frequent deployments and rolling updates\n- **Enterprise applications** where remote MCP servers are desirable because they are easier to manage across thousands of employees\n- **Batch processing systems** that require session continuity across job restarts\n\n\n# Proposed API\n\nHere is an example API to support discussions around this request. \n\n```java\npackage io.modelcontextprotocol.spec;\n\n/** Wraps the OAuth 2.1 access token used in Authorization headers. */\npublic record TokenInfo(String accessToken) { }\n\n/**\n* Negotiated protocol version and server capabilities returned by the server.\n*\n* @param protocolVersion the agreed MCP protocol version\n* @param capabilitiesJson server capabilities serialized as JSON (or any text format)\n*/\npublic record ServerMetadata(String protocolVersion, String capabilitiesJson) { }\n```\n\n```java\npackage io.modelcontextprotocol.spec;\n\nimport java.util.Optional;\n\n/**\n * Persists MCP client state so a Streamable-HTTP client can resume seamlessly\n * after a JVM restart. Implementations MUST be thread-safe.\n *\n * \u003cp\u003eHost applications remain in full control of where \u0026 how the data is stored.\n *\n * \u003cp\u003eExample usage:\n *\n * \u003cpre\u003e{@code\n * StreamableHttpClientStateStore myStateStore = new MyJdbcBackedStateStore(\"my-client-key\");\n * var transport = HttpClientStreamableHttpTransport.builder(\"https://example.com/mcp\")\n *         .clientStateStore(myStateStore)\n *         .build();\n *\n * McpSyncClient client = McpClient.sync(transport).build();\n * }\u003c/pre\u003e\n */\npublic interface StreamableHttpClientStateStore {\n\n    /* ------- Session ------- */\n\n    /**\n     * Called by the MCP client when a remote MCP server returns an MCP-Session-Id\n     * per the Streamable HTTP specification after an initialize request.\n     *\n     * @param the session ID returned by the server.\n     */\n    void setSessionId(String sessionId);\n\n    /**\n     * Called by the MCP client before sending any requests to the server.\n     * If a value is present, it will be included in the Mcp-Session-Id header.\n     *\n     * @return an Optional containing the stored session ID if one was previously stored.\n     */\n    Optional\u003cString\u003e getSessionId();\n\n    /**\n     * Called by the MCP client when the server indicates that the session has expired or is invalid,\n     * to clear the stored session ID.\n     */\n    void clearSessionId();\n\n    /* ------- Access Token ------- */\n\n    /**\n     * Called by the MCP client after obtaining a new OAuth 2.1 access token from the authorization server.\n     *\n     * @param token the TokenInfo containing the new access token.\n     */\n    void setAccessToken(TokenInfo token);\n\n    /**\n     * Called by the MCP client before sending any authorized requests to the server.\n     * If a value is present, it will be included in the Authorization header as a Bearer token.\n     *\n     * @return an Optional containing the stored access token if one was previously stored.\n     */\n    Optional\u003cTokenInfo\u003e getAccessToken();\n\n    /**\n     * Called by the MCP client when the access token is revoked, expires, or is no longer valid,\n     * to clear the stored token.\n     */\n    void clearAccessToken();\n\n    /* ------- Server Metadata ------- */\n\n    /**\n     * Called by the MCP client after initialization to store the negotiated\n     * protocol version and server capabilities for future reuse.\n     *\n     * @param metadata the ServerMetadata containing protocol version and capabilitiesJson.\n     */\n    void setServerMetadata(ServerMetadata metadata);\n\n    /**\n     * Called by the MCP client before initialization to retrieve any previously stored\n     * protocol version and server capabilities.\n     *\n     * @return an Optional containing the stored ServerMetadata if one was previously stored.\n     */\n    Optional\u003cServerMetadata\u003e getServerMetadata();\n\n    /**\n     * Called by the MCP client to clear any stored server metadata,\n     * for example if the protocol version becomes incompatible.\n     */\n    void clearServerMetadata();\n}\n```\n\n## Design Rationale\n\n| Aspect | Reasoning |\n| ------ | --------- |\n| **Atomic value objects** | strongly typed interfaces, ability to maybe add new fields if needed but we could drop these for just strings if we want to keep things super simple |\n| **`capabilitiesJson` as `String`** | Simplest for JDBC / key-value stores—no schema required. |\n| **Storage-agnostic** | Host application chooses file, DB, secret vault, etc.; SDK stays neutral. |\n\n## Implementation Details\n\n### Integration Point\nThe state store would be configured on the various transport builders for example  `HttpClientStreamableHttpTransport.Builder`:\n\n```java\nvar transport = HttpClientStreamableHttpTransport.builder(\"https://example.com/mcp\")\n    .clientStateStore(new FileBasedStateStore(\"./mcp-state.json\"))\n    .build();\n```","author":{"url":"https://github.com/asaikali","@type":"Person","name":"asaikali"},"datePublished":"2025-07-06T06:14:46.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":2},"url":"https://github.com/376/java-sdk/issues/376"}