mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents use apps through Paperclip's MCP client. The client calls each provider's remote (Streamable HTTP) or local (stdio) MCP server. > - The client spoke only protocol 2025-06-18. It always did the `initialize` handshake and it sent client capabilities only in that handshake. > - MCP 2026-07-28 removes the handshake and sessions. Every request carries its version, capabilities and client identity in `_meta`. Servers that only speak 2026-07-28 reject the old requests, and they never see that Paperclip renders MCP Apps views. > - Public servers already speak it: DeepWiki and Context7 answer `server/discover` with 2026-07-28 today. > - This pull request makes the client negotiate the version per server. It speaks stateless MCP to 2026-07-28 servers and keeps the handshake for 2025-11-25 and older servers. > - The benefit is that new and old providers both work, and a tool call to a stateless server is one HTTP request with no handshake. ## Linked Issues or Issue Description Refs #21119 (MCP Apps host). This PR sends its MCP Apps capability to stateless servers too. **Subsystem affected** Server: the MCP client in `server/src/services/mcp-http.ts`, catalog discovery, the tool gateway (`tools/call`, context reads, stdio), and the remote MCP OAuth flow. **Problem or motivation** The client used protocol 2025-06-18 only. MCP 2026-07-28 makes MCP stateless: no `initialize`, no `Mcp-Session-Id`, per-request `_meta`, `server/discover`, `resultType` with multi round-trip requests (MRTR), cacheable lists, required `Mcp-Method`/`Mcp-Name` headers, and RFC 9207 `iss` validation. Servers that speak only 2026-07-28 cannot be used. Paperclip advertised MCP Apps support only in `initialize`, so stateless servers never saw it. **Proposed solution** Probe each server once with `server/discover`, pick the newest mutually supported version, and save it on the connection. Send stateless requests to modern servers and keep the handshake for legacy servers. Tool calls use the saved version and never probe. The saved version is checked again only when a request built from it is refused. **Alternatives considered** Inline negotiation (send each request in modern shape first and fall back on `400`) adds a failed request to every call to a legacy session server. Probing on every tool call adds a round trip before each tool runs. Saving the negotiated version keeps tool calls at one request. **Roadmap alignment** MCP protocol currency for the Apps and connections substrate. It follows the MCP Apps host work in #21119. **Additional context** Spec: https://modelcontextprotocol.io/specification/2026-07-28/changelog. Out of scope (separate work): the Tasks extension, Skills over MCP, `subscriptions/listen`, progress and cancellation, icons, enterprise-managed authorization. ## What Changed - `mcp-http.ts`: `negotiateMcpProtocolVersion` probes with `server/discover`. A `DiscoverResult` or a modern error (`-32020`/`-32021`/`-32022`) means a modern server. Anything else means a legacy server, which gets `initialize`. A `401`/`403` keeps the challenge for OAuth discovery. The era is remembered per connection and endpoint. - `mcpHttpRequestInit` builds every request. It always sends `Mcp-Method` and `Mcp-Name` (Base64 sentinel when unsafe). For modern versions it adds `_meta` (`protocolVersion`, `clientCapabilities` with `extensions["io.modelcontextprotocol/ui"]` and URL elicitation, `clientInfo`) and `Mcp-Param-*` headers from `x-mcp-header`. - Legacy `initialize` now requests 2025-11-25 and advertises the MCP Apps extension. - Catalog refresh saves `config.mcpProtocolVersion`. It drops tools with invalid `x-mcp-header` annotations. It reuses a fresh `tools/list` result (`ttlMs`, `cacheScope`). It probes again when the saved version is refused, and it negotiates again after a credential refresh. - `tools/call`: a saved modern version is called directly (no probe, no handshake). A modern rejection of a legacy-shaped call, or `-32022`, gets one retry with a negotiated version. The server rejected the first request before it ran, so the retry cannot repeat a side effect. A remembered legacy server that refuses `initialize` is probed again. - MRTR: `input_required` with URL requests becomes the existing provider link flow (`provider_interaction_required`). The next identical call sends `requestState` and `inputResponses`. Form, sampling and roots requests stop with `provider_input_required` and a plain message. A missing `resultType` means `complete`. - Context reads (`resources/*`, `prompts/*`) use the saved version, cache fresh results, and stop on `input_required`. The error code is kept, so resource not found (`-32602` or `-32002`) is visible. - stdio: probe with `server/discover` (2 s limit). Restart a server that exits on the probe. Send `_meta` to modern servers. - OAuth: refuse a callback without `iss` when the server advertises `authorization_response_iss_parameter_supported`. Check `iss` before acting on a provider error. Send `application_type: "native"` for localhost callbacks and `web` otherwise. Issuer-bound clients and the CIMD-first order already existed. - Docs: `doc/connections/MCP-PROTOCOL-VERSIONS.md`, linked from `doc/connections/README.md`. ## Verification - New suite `server/src/__tests__/mcp-protocol-versions.test.ts` (19 tests) uses a fake 2026-07-28 server and a fake legacy session server. It covers discovery, `_meta`, headers, version fallback, `-32022`, `resultType`, MRTR link and retry, form stop, cache TTL, legacy flow, and recovery when a saved legacy server moves to 2026-07-28. Embedded Postgres runs the end-to-end cases. - New OAuth tests in `generic-mcp-connection.test.ts`: `iss` required when advertised, `iss` checked on provider errors, `native` for localhost, and a stateless server listed again after a revoked token. - Red/green: with the master service code, all 21 new protocol and OAuth tests fail. With this change they pass. The token-refresh regression test fails without its fix and passes with it. - Existing suites: 12 touched files, 1088 tests pass. `tsc --noEmit` passes for `server`. Updated expectations count the one-time `server/discover` probe, and the Calendly DCR test now expects `native` for its localhost callback. - `pnpm verify` exits 2 (a doc is a global CI input), so CI supplies the broad coverage. - Live check with the changed client, without credentials: - DeepWiki (`mcp.deepwiki.com/mcp`): discover 200 → 2026-07-28, no session, `tools/list` 200 (3 tools). - Context7 (`mcp.context7.com/mcp`): discover 200 → 2026-07-28, no session, `tools/list` 200 (2 tools). - GitMCP (`gitmcp.io/docs`): discover 400 → `initialize` (2025-03-26) → session → `tools/list` 200 (5 tools). - Circleback (`circleback.ai/api/mcp`): discover 401 with its `WWW-Authenticate` challenge kept for sign-in. ## Risks - A legacy server that is not saved as session-required gets one extra request (`server/discover`) the first time it is refreshed. Then the version is saved. Saved session-required connections are not probed. - DCR from a localhost callback now registers a `native` client. This is what the spec asks for. Existing registrations are reused. - An authorization server that advertises `iss` support but does not send `iss` now fails sign-in with a clear message. The spec requires this. - MRTR answers are kept in memory for 30 minutes. After a restart the server asks again, and the user sees the link again. - No schema change. `config.mcpProtocolVersion` is a new key in the existing JSON config. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used in Claude Code with tool use (shell, file edits, web fetch of the MCP spec), extended reasoning. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>