docs(rfc-003): standalone MCP surface spec, validated against upstream

Browse source

Rewrites the MCP RFC as a single self-contained specification, validated
against the live upstream surfaces it builds on:

- MCP protocol revision 2025-11-25 (Streamable HTTP transport requirements,
  authorization model, tool/resource shapes, SEP-1303 input-validation-as-
  tool-error, JSON Schema 2020-12 default).
- rmcp 1.7.0 (StreamableHttpServerConfig real defaults — stateful_mode
  defaults true and must be flipped; NeverSessionManager for stateless mode;
  the `local` feature must stay off; RequestContext.extensions carries the
  http::request::Parts passthrough; RPITIT ServerHandler).
- Tool/server best practice: domain-qualified tool names, explicit
  annotations, structured output + text mirror, and progressive disclosure
  (per_query vs meta projection modes) for large stored-query catalogs.

Adds a provider compatibility matrix (Claude Code/Desktop/web, Messages API
connector, OpenAI Responses API/ChatGPT, Cursor, VS Code, OpenCode) with a
phased static-bearer -> OAuth 2.1 + RFC 9728 auth plan and the Claude Code
PRM header-override caveat, and a code-mode compatibility section describing
the server-side properties that make the surface code-execution-friendly
without building client-side machinery.

...

This commit is contained in:

Ragnor Comerford 2026-06-13 16:08:59 +02:00

parent 61c18b67ba

commit 20233a34ae

No known key found for this signature in database

1 changed files with 530 additions and 741 deletions

Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL

Download patch file Download diff file Expand all files Collapse all files

1271

docs/dev/rfc-003-mcp-server-surface.md

View file

File diff suppressed because it is too large Load diff