feat(server): support SEP-2575 stateless MCP (server/discover + Mcp-Method/Mcp-Name headers)

[inola-ww]

Summary

mcp-go has no implementation of SEP-2575 (Make MCP Stateless) or the companion SEP-2243 (HTTP Standardization) headers. As of v0.56.0, server/discover returns Method not found and the Mcp-Method / Mcp-Name headers are not validated. Both are mandatory in the 2026-07-28 spec release.

This blocks Go MCP server operators from migrating to the stateless core before support windows on the 2025-11-25 SDKs expire, and is the only required-check failure reported by mcp-spec-check against a stock mcp-go server today.

What's needed

1. server/discover RPC (SEP-2575 §"Discovery for Server Capabilities")

Add mcp.MethodDiscover = "server/discover" and the request/result types:

type DiscoverRequest struct{}

type DiscoverResult struct {
	SupportedVersions []string             `json:"supportedVersions"`
	Capabilities      ServerCapabilities   `json:"capabilities"`
	ServerInfo        Implementation       `json:"serverInfo"`
	Instructions      string               `json:"instructions,omitempty"`
}

Wire it in server/request_handler.go (regenerated from the template) and add a handleDiscover that returns s.capabilities and s.implementation — both already live on *MCPServer from NewMCPServer / WithInstructions.

2. Mcp-Method / Mcp-Name header validation (SEP-2243)

For HTTP transport: when a request includes Mcp-Method or Mcp-Name headers, validate that they match the body's method (and resource/tool name where applicable). Mismatch → 400 Bad Request with the appropriate JSON-RPC error. Requests without the headers continue to work (back-compat for legacy clients).

Reference implementation

The Python SDK merged the equivalent work across these PRs:

• #2884 — SEP-2575: Make MCP Stateless (merged)
• #3033 — Validate Mcp-Param-* headers server-side on the 2026-07-28 HTTP path (merged)
• #3040 — Harden the dual-era stream loop's era-lock and rejection semantics (merged)

The TypeScript SDK is following the same shape. The Go side would mirror those — the request/response types are largely identical across SDKs.

Scope notes

• Out of scope here: SEP-2322 (MRTR / resultType), SEP-2549 (cache hints), SEP-2567 (sessions). Those are response-shape changes that arguably deserve their own issues.
• Mcp-Session-Id removal is a deeper refactor (mcp-go's MCPServer keeps session state). Suggest we land discover + headers first as a minimal viable stateless surface; full session removal can follow once the kinks shake out.

Test plan

• TestServer_HandleDiscover — POST server/discover returns supportedVersions, live capabilities, serverInfo.name == <ctor arg>.
• TestServer_HTTPHeaderMismatch_McpMethod — POST with Mcp-Method: tools/list body but Mcp-Method: resources/list header → 400.
• TestServer_HTTPHeaderMismatch_Absent — POST with no Mcp-Method header → 200 (back-compat).
• Conformance: python-sdk's conformance suite against the new branch's reference server.

Offer

Happy to submit a PR if the maintainers are open to it.

[mark-iii-labs-huly]

Connected to Huly®: MCP_G-492