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): 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

---

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)
Tool outputSchema	root must be type: "object"	any JSON Schema root type accepted (non-breaking)

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.

---

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 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
• 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.