Migrating to 3.x (draft)

[DaleSeo]

Upgrading to RMCP 3.x — Migration Guide

⚠️ Draft — v3 is not released yet. This guide tracks the changes merged so far for the upcoming 3.0 release (release PR #964). More changes will land before we cut v3. Maintainers and contributors: if you merge a breaking change, please edit this post to keep it current. Each section links to the PR that introduced it.

RMCP 3.x adds support for the upcoming MCP 2026-07-28 specification revision (currently draft): stateless discovery and protocol negotiation (SEP-2575), multi round-trip requests (SEP-2322), cache hints for list/read results (SEP-2549), standard HTTP headers (SEP-2243), and the SEP-2106 schema relaxations. To verify the new shapes, cross-check against the draft spec.

Why 3.0?

The 2026-07-28 revision changes the shape of server results: every server result now carries a resultType discriminator, and tools/call, prompts/get, and resources/read may return an intermediate input_required result instead of a final one. Modeling that faithfully requires widening handler return types and the ServerResult union, which is breaking at the Rust API level.

Unlike 2.0 (which was wire-compatible), 3.0 includes wire-visible changes — all of them additive or version-gated:

• Server results now always serialize "resultType": "complete" (per the spec's MUST; absent values still deserialize as "complete", so older peers interoperate).
• InputRequiredResult and the SEP-2243 headers are only emitted to peers that negotiated protocol version 2026-07-28 or newer.
• ttlMs / cacheScope are new optional fields.

Changes included so far

PR	SEP	Summary	Breaking?
#915	SEP-2322	MRTR model types, resultType on server results	Yes
#929	SEP-2322	MRTR behavior: handler response enums, client auto-retry	Yes
#907	SEP-2243	Mcp-Method / Mcp-Name / Mcp-Param-* HTTP headers	Yes
#889	SEP-2549	ttlMs / cacheScope cache hints on list/read results	Yes
#933	SEP-2106	ToolResultContent.structured_content accepts any JSON value	Yes
#956	—	Annotations.lastModified typed as a string	Yes
#895	SEP-2106	outputSchema accepts non-object JSON Schema root types	No
#993	— (spec #2038, spec #2889)	Meta split into MetaObject / RequestMetaObject / NotificationMetaObject	Yes
#973	SEP-2575	Server discovery (server/discover) and inline version negotiation; protocol union enums #[non_exhaustive]	Yes
#995	SEP-2575	Modern client lifecycle modes (ClientLifecycleMode::{Initialize, Discover, Auto}) with per-request metadata and legacy fallback	No
#888	SEP-2350	Client-side scope accumulation on step-up authorization	No
#996	SEP-2468	Validate discovered authorization server metadata issuer	No

Remaining work before v3

Tracked in the conformance epic #977 and the 2026-07-28 spec milestone. Conformance snapshot (2026-07-16, main 2e2c791, suite 0.2.0-alpha.9): server 37/40, client 15/32 scenarios passing. The client number dropped from the 2026-07-13 baseline (24/32) because of conformance harness gaps, not library regressions: ten auth scenarios lost their dispatch mapping in #991 (#1001) and the legacy-lifecycle scenarios die on a missing MCP-Protocol-Version header (#1002) — this also means the suite cannot currently verify the merged #888 and #996 fixes end-to-end. See #977 for the full matrix.

Work	SEP / conformance scenario	Tracking	Breaking?
Remaining server-stateless gaps: capability declaration in discover, ping 404, missing diagnostic fixtures	SEP-2575 · server-stateless (18/25)	#1004 (follow-up to #869)	No
Modern per-request path returns progress notification as JSON body (regressed by #973; fixed for the legacy path in #990)	tools-call-with-progress	#980 (reopened)	No (bug fix)
Bind credentials to AS issuer, re-register on change	SEP-2352 · auth/authorization-server-migration	#879 (PR #965 closed unmerged)	No
Custom HTTP headers — client side	SEP-2243 · http-custom-headers, http-standard-headers, http-invalid-tool-headers	#978	TBD
Pre-registration auth flow	auth/pre-registration	#984	No
Client-side TTL-honoring cache	SEP-2549 follow-up	#974	TBD
Conformance client: restore auth scenario dispatch removed in #991 (blocks verifying #996 / SEP-2352)	auth/iss-*, auth/offline-access-*, auth/authorization-server-migration, auth/metadata-issuer-mismatch	#1001	—
Conformance client: legacy lifecycle fails -32020 at 2026-07-28 (blocks verifying #888)	tools_call, auth/scope-step-up, http-standard-headers	#1002	—
Conformance server: SEP-2106 keyword-preservation fixtures	json-schema-2020-12 (4/7)	#1003	—
CI: run full 2026-07-28 conformance suites	—	#985	—

---

TL;DR

Area	Old (2.x)	New (3.0)
ServerHandler::call_tool	Result<CallToolResult, ErrorData>	Result<CallToolResponse, ErrorData>
ServerHandler::get_prompt	Result<GetPromptResult, ErrorData>	Result<GetPromptResponse, ErrorData>
ServerHandler::read_resource	Result<ReadResourceResult, ErrorData>	Result<ReadResourceResponse, ErrorData>
ServerResult union	no InputRequiredResult	new variant — add a match arm
Server results	no discriminator	result_type: ResultType, always serialized
Client RunningService::call_tool / get_prompt / read_resource	one round trip	automatically drives MRTR rounds; use *_once to opt out
List results + ReadResourceResult	—	new ttl_ms: Option<u64>, cache_scope: Option<CacheScope> fields
StreamableHttpService<S, M>	S: Service<RoleServer>	S: ServerHandler
Annotations.last_modified	Option<DateTime<Utc>>	Option<String>
ToolResultContent.structured_content	Option<JsonObject>	Option<Value>
ProtocolVersion	up to V_2025_11_25	adds V_2026_07_28 (LATEST stays 2025-11-25 until the spec is final)
Server discovery	no server/discover RPC	DiscoverRequest / DiscoverResult; default ServerHandler::discover and configurable supported versions
Client startup	legacy initialize handshake only	serve() unchanged; opt into ClientServiceExt::serve_with_lifecycle with ClientLifecycleMode::{Initialize, Discover, Auto} (non-breaking)
Protocol message unions	exhaustive enums	#[non_exhaustive]; downstream matches need a wildcard arm
Tool outputSchema	root must be type: "object"	any JSON Schema root type accepted (non-breaking)
Metadata types	single Meta for every _meta	MetaObject / RequestMetaObject / NotificationMetaObject; Meta stays as a deprecated alias

If you use the #[tool_router] + #[tool_handler] / #[prompt_router] + #[prompt_handler] macros, the return-type changes are handled for you — your individual #[tool] / #[prompt] methods keep compiling unchanged. Manual ServerHandler implementations need the signature updates below.

---

1. Multi round-trip requests — MRTR (SEP-2322)

A server may now respond to tools/call, prompts/get, or resources/read with an InputRequiredResult (carrying inputRequests and/or an opaque requestState) instead of a final result. The client fulfills the requests and retries. This replaces the previous URLElicitationRequiredError (-32042) approach.

1.1 Server: handler return types widened

ServerHandler::call_tool, get_prompt, and read_resource now return MRTR-aware response enums. From impls are provided, so wrap your existing result with .into():

// 2.x
async fn call_tool(
    &self,
    request: CallToolRequestParams,
    context: RequestContext<RoleServer>,
) -> Result<CallToolResult, ErrorData> {
    Ok(CallToolResult::success(vec![ContentBlock::text("done")]))
}

// 3.0
async fn call_tool(
    &self,
    request: CallToolRequestParams,
    context: RequestContext<RoleServer>,
) -> Result<CallToolResponse, ErrorData> {
    Ok(CallToolResult::success(vec![ContentBlock::text("done")]).into())
}

The response enums are:

Method	Response enum	Variants
tools/call	CallToolResponse	Complete(CallToolResult) | InputRequired(InputRequiredResult)
prompts/get	GetPromptResponse	Complete(GetPromptResult) | InputRequired(InputRequiredResult)
resources/read	ReadResourceResponse	Complete(ReadResourceResult) | InputRequired(InputRequiredResult)

To request input, return an InputRequiredResult (tool methods under #[tool_router] can return it directly — IntoCallToolResult is implemented for it):

let mut requests = InputRequests::new();
requests.insert(
    "confirm".to_string(),
    InputRequest::Elicitation(elicit_request),
);
Ok(InputRequiredResult::new(Some(requests), Some(state)).into())
// or: InputRequiredResult::from_input_requests(requests)
// or: InputRequiredResult::from_request_state(state)

The SDK only lets an InputRequiredResult reach a peer that negotiated protocol version 2026-07-28 or newer; older peers get a protocol error instead. Task-based tool calls (#[task_handler]) reject input_required with an internal error.

1.2 Client: high-level calls drive MRTR automatically

RunningService::call_tool, get_prompt, and read_resource now automatically fulfill each input_required round through your registered ClientHandler (sampling, elicitation, roots) and retry, up to DEFAULT_MRTR_MAX_ROUNDS (10). Your call sites don't change.

New APIs:

• call_tool_once / get_prompt_once / read_resource_once (on Peer<RoleClient> and RunningService) — send one request and get the response enum back, so you can drive the rounds yourself.
• call_tool_with_mrtr_max_rounds (and get_prompt / read_resource variants) — explicit round cap.
• ServiceError::InputRequiredRoundsExceeded { max_rounds } — returned when the peer keeps responding input_required beyond the cap.

Note: the low-level Peer::call_tool / get_prompt / read_resource still return the final result types and fail with ServiceError::UnexpectedResponse if the server returns input_required. Prefer the RunningService helpers or the *_once variants.

1.3 ServerResult gained a variant

ServerResult now includes InputRequiredResult. If you match exhaustively on ServerResult, add an arm.

1.4 requestState is untrusted

The client echoes requestState back verbatim, so a stateless server MUST verify its integrity before trusting the echoed value. The new opt-in request-state feature provides RequestStateCodec (HMAC-SHA256) with associated-data and TTL bindings:

rmcp = { version = "3", features = ["server", "request-state"] }

let codec = RequestStateCodec::new(b"a-32-byte-or-longer-secret-key!!!");
let sealed = codec.seal_with(b"step=2", &SealOptions::new().associated_data(context));
let opened = codec.open_with(&sealed, context)?;

See the servers_mrtr example for a complete walkthrough.

2. resultType on server results (SEP-2322)

All server result types that carry resultType in the schema gained a result_type: ResultType field: CallToolResult, GetPromptResult, ReadResourceResult, CompleteResult, ListToolsResult, ListPromptsResult, ListResourcesResult, and ListResourceTemplatesResult.

• ResultType is an open string type (ResultType::COMPLETE, ResultType::INPUT_REQUIRED, unknown values preserved) with is_complete() / is_input_required() accessors.
• It is always serialized ("resultType": "complete"), per the spec's MUST. Absent values deserialize as "complete", so older peers are unaffected.
• Constructors (::new(..), ::success(..), with_all_items(..), Default) initialize it for you — since these types are #[non_exhaustive] you were already using constructors, so most code needs no change. Only code that reads all fields or constructs results inside forks of the crate is affected.

3. Cache hints (SEP-2549)

ListToolsResult, ListPromptsResult, ListResourcesResult, ListResourceTemplatesResult, and ReadResourceResult gained two optional fields:

• ttl_ms: Option<u64> — how long the result may be treated as fresh, in milliseconds. Negative wire values are clamped to 0 on deserialization, per the SEP.
• cache_scope: Option<CacheScope> — who may cache it. CacheScope is a new #[non_exhaustive] enum: Public (default) or Private.

Set them with the new builders:

ListToolsResult::with_all_items(tools)
    .with_ttl_ms(60_000)
    .with_cache_scope(CacheScope::Private)

Both fields are optional on the wire for compatibility with older spec versions (the 2026-07-28 spec makes them required in these results).

4. Standard HTTP headers (SEP-2243)

Streamable HTTP requests now carry routing metadata in headers so proxies, gateways, and load balancers can route without parsing the JSON-RPC body. Everything is gated on a negotiated protocol version of 2026-07-28 or newer (ProtocolVersion::STANDARD_HEADERS), so older peers are unaffected.

• The client automatically sends Mcp-Method (e.g. tools/call), Mcp-Name (from params.name or params.uri), and Mcp-Param-* headers.
• Tool authors opt specific arguments into Mcp-Param-* promotion by annotating top-level, primitive-typed input-schema properties with x-mcp-header:

{
  "type": "object",
  "properties": {
    "region": { "type": "string", "x-mcp-header": "Region" }
  }
}

Header-unsafe values are Base64-wrapped automatically.

• The server validates these headers against the body and rejects mismatches with HTTP 400 and JSON-RPC error -32020.

Breaking: StreamableHttpService<S, M> now requires S: ServerHandler instead of S: Service<RoleServer>, so the server can read tool schemas for Mcp-Param-* validation. If you were plugging a hand-rolled Service<RoleServer> into StreamableHttpService, implement ServerHandler instead.

New constants: ProtocolVersion::V_2026_07_28 and ProtocolVersion::STANDARD_HEADERS. ProtocolVersion::LATEST remains V_2025_11_25 until the 2026-07-28 spec is finalized.

5. Annotations.lastModified is now a string

The spec types lastModified as a plain string, and schema-valid values (date-only, offset-less date-times) are not strict RFC 3339 — previously they could fail deserialization of a whole message. The field now preserves the raw string:

// 2.x
pub last_modified: Option<DateTime<Utc>>

// 3.0
pub last_modified: Option<String>

• Writers are unchanged: Annotations::for_resource(priority, ts), .with_timestamp(ts), and .with_timestamp_now() still take DateTime<Utc> and serialize RFC 3339 strings.
• Readers that need a typed value should parse explicitly, e.g. annotations.last_modified.as_deref().and_then(|s| DateTime::parse_from_rfc3339(s).ok()), and decide how to handle non-RFC-3339 values.

This matches how Task.createdAt / Task.lastUpdatedAt were already represented, and keeps proxying/forwarding lossless.

6. ToolResultContent.structured_content accepts any JSON value (SEP-2106)

// 2.x
pub structured_content: Option<JsonObject>

// 3.0
pub structured_content: Option<Value>

This matches CallToolResult.structured_content (already Option<Value>) and the SEP-2106 relaxation of outputSchema. If you consumed the field as an object, use value.as_object(). (Note that ToolUseContent / ToolResultContent are deprecated by SEP-2577 and will be removed in a future release.)

7. outputSchema accepts non-object root types (non-breaking)

schema_for_output (used by Json<T> tool returns and Tool::with_output_schema) now accepts any JSON Schema 2020-12 root type — primitives, arrays, and compositions like Option<T>. Input schemas still require type: "object". Types previously rejected are now accepted; nothing to migrate, but tools can now declare e.g. Json<Vec<String>> outputs.

8. Metadata models: Meta split into MetaObject / RequestMetaObject / NotificationMetaObject (#993)

The 2026-07-28 revision names the _meta shapes — no released spec version has these types (spec #2038, spec #2889). rmcp's single Meta type predates them; 3.0 mirrors the spec hierarchy (#993):

• MetaObject — general _meta on results, content blocks, and descriptors (tools, prompts, resources, roots). Carries the SEP-414 trace-context helpers.
• RequestMetaObject — request _meta: progressToken plus typed accessors for the SEP-2575 io.modelcontextprotocol/* keys. The keys the draft marks as required stay optional at runtime and in the generated schema; validate against a negotiated version with missing_required_keys(&ProtocolVersion).
• NotificationMetaObject — notification _meta: io.modelcontextprotocol/subscriptionId accessors (previously unimplemented).

All three are transparent wrappers over the JSON map, so arbitrary extension keys still round-trip and the map APIs remain available through Deref. Meta stays as a deprecated re-export of MetaObject, so existing Meta(...) construction keeps compiling with a warning.

API	Old (2.x)	New (3.0)
RequestParamsMeta	Option<&Meta> / &mut Option<Meta>	Option<&RequestMetaObject> / &mut Option<RequestMetaObject>
RequestContext.meta	Meta	RequestMetaObject
NotificationContext.meta	Meta	NotificationMetaObject
PeerRequestOptions.meta	Option<Meta>	Option<RequestMetaObject>
GetMeta	fn get_meta(&self) -> &Meta	associated type Metadata (RequestMetaObject for requests, NotificationMetaObject for notifications)
Handler extractor	crate::model::Meta	crate::model::RequestMetaObject
Result / content / descriptor meta fields	Option<Meta>	Option<MetaObject> (the alias keeps this code compiling)

Wire compatibility is unchanged: unknown _meta keys round-trip untouched, requests with absent or partial _meta still deserialize, and legacy MetaObject extensions inserted under the deprecated name are still merged into outgoing _meta. Generated JSON schemas now expose the three named definitions. This change also fixed a 2.x bug where no-param requests and notifications (ping, notifications/initialized) dropped params._meta during (de)serialization.

---

9. Server discovery and protocol negotiation (SEP-2575, #973 + #995)

#973 adds the server-side discovery and inline version-negotiation foundation for stateless MCP; #995 adds the client-side lifecycle modes on top of it.

New protocol models and APIs:

• DiscoverRequest / DiscoverResult model server/discover, including supported_versions, capabilities, server identity, instructions, and cache fields.
• ServerHandler::discover has a default implementation derived from get_info(); override supported_protocol_versions() or discover() to customize the advertised versions or result.
• Peer<RoleClient>::discover(RequestMetaObject) sends a typed discovery request on an already-running peer.
• select_protocol_version(client_preferences, server_supported) selects the first mutually supported client-preferred version and returns None when there is no overlap.
• UnsupportedProtocolVersionError (-32022) carries { requested, supported }; missing client capability errors use -32021.
• Modern Streamable HTTP requests validate the version header against request _meta and map modern protocol errors to HTTP 400 / 404, while legacy requests retain their existing HTTP 200 JSON-RPC-error behavior.

9.1 Client lifecycle modes (#995, non-breaking)

serve() keeps the legacy lifecycle (initialize → notifications/initialized) unchanged. To start with server/discover instead, select a lifecycle explicitly via ClientServiceExt::serve_with_lifecycle:

use rmcp::{ClientInfo, ClientLifecycleMode, ClientServiceExt, ProtocolVersion};

// Start directly with server/discover; every request carries self-contained
// client metadata (protocol version, client info, capabilities) in `_meta`.
let client = ClientInfo::default()
    .serve_with_lifecycle(
        transport,
        ClientLifecycleMode::Discover {
            preferred_versions: vec![ProtocolVersion::V_2026_07_28],
        },
    )
    .await?;

// Or probe with server/discover and fall back to the legacy initialize
// handshake when the peer proves it is a legacy server.
let client = ClientInfo::default()
    .serve_with_lifecycle(
        transport,
        ClientLifecycleMode::Auto {
            preferred_versions: vec![ProtocolVersion::V_2026_07_28],
            legacy_version: Some(ProtocolVersion::V_2025_11_25),
        },
    )
    .await?;

ClientLifecycleMode::Initialize is equivalent to serve(). Discover startup does not send notifications/initialized — discovery completes startup, and each subsequent request carries its protocol version, client information, and capabilities in _meta. Bounded version retry and per-request metadata injection are handled for you. Peer<RoleClient>::discover(RequestMetaObject) remains available for typed discovery on an already-running peer.

Breaking enum changes

DiscoverRequest adds a ClientRequest variant and DiscoverResult adds a ServerResult variant. The six protocol union enums are now #[non_exhaustive] so future protocol additions do not repeatedly break exhaustive downstream matches:

• ClientRequest
• ClientNotification
• ClientResult
• ServerRequest
• ServerNotification
• ServerResult

Downstream code must add a wildcard arm when matching these enums outside rmcp:

match request {
    ClientRequest::InitializeRequest(request) => { /* legacy handling */ }
    ClientRequest::DiscoverRequest(request) => { /* modern discovery */ }
    _ => { /* future protocol variants */ }
}

The existing legacy initialize flow remains available and ProtocolVersion::LATEST remains V_2025_11_25 until the draft revision is finalized.

Quick migration checklist

• Manual ServerHandler impls: change call_tool / get_prompt / read_resource return types to CallToolResponse / GetPromptResponse / ReadResourceResponse and wrap results with .into() (macro users: no change)
• Exhaustive matches on protocol union enums → add a wildcard arm; handle DiscoverRequest / DiscoverResult where relevant
• Custom discovery behavior → override ServerHandler::supported_protocol_versions() or discover()
• Exhaustive match on ServerResult → add an InputRequiredResult arm
• StreamableHttpService service types → implement ServerHandler (not just Service<RoleServer>)
• Reads of Annotations.last_modified → it's a String now; parse explicitly if you need a DateTime
• Reads of ToolResultContent.structured_content as an object → use .as_object()
• Snapshot tests of server result JSON → expect "resultType": "complete"
• Custom clients driving requests via Peer directly → handle input_required (use *_once helpers) or switch to the RunningService helpers
• Uses of Meta → MetaObject for results/content/descriptors, RequestMetaObject for request params/contexts, NotificationMetaObject for notification params/contexts (the deprecated alias keeps general uses compiling)
• Run cargo build and follow remaining compiler errors — the compiler is your friend here

---

Questions or migration snags? Reply here and we'll help.

Draft started 2026-07-10, based on the PRs listed above. This guide will be kept up to date until v3 is released — maintainers and contributors, please edit as new breaking changes merge.