[mcp-2026] Align 2026 wire: drop ping, add -32021, discover _meta, MUST headers #24

Context

PR #21 merged 2026-07-28-shaped code that still speaks 2025 on the wire:

Sidecar handle_post currently intercepts discover/initialize/ping. WP0 must remove that. This issue is the handler-side wire: core/app.py _setup_handlers, protocol/discovery.py, protocol/errors.py, protocol/method_contract.py.

Handoff: #21 (comment)

Spec references (judge wire, not official SDK DX):

• https://blog.modelcontextprotocol.io/posts/2026-07-28/
• https://modelcontextprotocol.io/specification/2026-07-28/changelog

NitroStack may keep modules/DI/@tool. Do not copy official SDK internals.

Goal

After WP0, mcp 2.x owns /mcp. NitroStack handlers stamp 2026 fields. No ping. Modern POST fails closed on missing MUST headers. Discover _meta includes serverInfo.

Probe

rg -n "ping|build_ping_response|-32021|32021|serverInfo|resultType|requires_method_header" nitrostack/protocol nitrostack/core/app.py nitrostack/transports/dispatch.py

Read:

• nitrostack/protocol/errors.py
• nitrostack/protocol/method_contract.py — entire MODERN_METHOD_CONTRACTS and DEPRECATED_MODERN_METHODS
• nitrostack/protocol/discovery.py — build_discover_result, build_sessionless_initialize_result
• nitrostack/protocol/jsonrpc.py — header validators; parse_jsonrpc_request treats missing id as a request
• nitrostack/core/app.py — handle_server_discover, _setup_handlers, _to_call_tool_result
• nitrostack/runtime/stateless.py — comment that protocol version header is not required on modern

Confirm era auto still allows 2025 handshake via mcp 2.x, not via a NitroStack JSON-RPC middleware. Delete build_sessionless_initialize_result from any sidecar path. If mcp needs a NitroStack initialize payload, use NitroStackMcpServer.initialize_handler on the Server object only.

Implementation

1. Errors. Add -32021 to JsonRpcErrorCode + default message. Prefer mcp 2.x owning -32020/-32022 if it already emits them. If you keep a thin header check, it must not become a second method router.
2. Ping. Remove from contracts, production helpers, and public exports. ping → -32601.
3. Discover. One builder used by handle_server_discover and server.add_request_handler("server/discover", ...). Put serverInfo (name, version) on result _meta. Set resultType on discover. If era auto also exposes top-level serverInfo for old clients, modern must still satisfy 2026 _meta rules. Advertise io.modelcontextprotocol/tasks only if the tasks issue implements 2026 tasks (default: do not advertise).
4. Headers (modern). POST /mcp JSON-RPC MUST send MCP-Protocol-Version: 2026-07-28 and Mcp-Method matching body. tools/call, resources/read, prompts/get MUST send Mcp-Name matching name/uri. One validator: missing/mismatch → -32020. Delete the dual optional-vs-required helpers. Era auto: do not require 2026 headers on 2025 handshake; do require them on 2026 methods if mcp does.
5. resultType. Stamp in NitroStack handlers that already build mcp types: list tools/resources/prompts, tools/call, resources/read, prompts/get — not only discover/MRTR/task.
6. Retired methods on modern. Do not register (or register not-found): tasks/result, tasks/list, resources/subscribe, logging/setLevel, ping, initialize. Do not rely on a sidecar that return None so mcp still runs them. auto handshake is mcp’s job (WP0).
7. Method table. If it exists only for tests, delete it and test via HTTP. It must not list ping / tasks/result / tasks/list as live modern methods.

Do not implement tasks/update here (tasks issue). Do not add era aliases.

Test / verify

Prefer Starlette TestClient on McpApplication.get_combined_app() (same fixture style as tests/test_transport_http.py / lifecycle HTTP tests). Era via NITRO_MCP_PROTOCOL_VERSION / ServerConfig.protocol_era.

Do not restore header-only ping tests.

pytest on the new tests + tests/test_transport_http.py tests/test_lifecycle_http.py. Expect tests/test_mcp20_stateless_http.py to fail until the test-rewrite issue; do not expand that file.

Review

• Wire changes live in handlers / mcp registration, not a new ASGI JSON-RPC server.
• Discover _meta.serverInfo present on modern.
• rg ping nitrostack/ has no live RPC.

Success

• No production ping success path
• -32021 exists on JsonRpcErrorCode
• Discover result _meta contains serverInfo
• Modern POST without version/method headers fails closed
• resultType not limited to discover/MRTR
• Modern does not register retired 2025 methods

Related

Depends on WP0. Align subscribe flag with WP1. Tasks advertising is WP3.