Migrating to 3.0.0-beta.1

[DaleSeo]

Upgrading to RMCP 3.x — Migration Guide

✅ RMCP 3.0.0-beta.1 is available. rmcp and rmcp-macros were published on 2026-07-23 from main e660b80; see the rmcp-v3.0.0-beta.1 release and release PR #964.

rmcp = "3.0.0-beta.1"

This guide reflects beta.1 exactly. More changes may land before stable 3.0. 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), version-gated stateless HTTP (SEP-2567), transport-neutral subscription streams, multi round-trip requests (SEP-2322), cache hints (SEP-2549), standard HTTP headers (SEP-2243), schema relaxations (SEP-2106), authorization updates (SEP-2350, SEP-2352, and SEP-2468), and the official Tasks Extension (SEP-2663). 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.
• Tasks move from the experimental 2025-11-25 core API to the io.modelcontextprotocol/tasks extension; the old task hint, core capability, tasks/list, and tasks/result are removed.

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
#994	—	High-level path for pre-registered OAuth clients	No
#998	SEP-2352	Bind dynamic client registration credentials to the issuing authorization server	No
#999	SEP-2567	Serve draft Streamable HTTP requests statelessly; rename stateful_mode to legacy_session_mode	Yes (API rename)
#1000	SEP-2575	Transport-neutral subscriptions/listen; deprecate legacy resource subscription APIs for the draft protocol	No
#1005	SEP-2575	Preserve progress notifications on negotiated HTTP responses by falling back to SSE	No
#1011	SEP-2352	Re-register after the authorization server changes	No
#1012	SEP-2243	Complete draft client headers, tool-schema caching, and invalid annotated-tool filtering	No
#1021	—	Accept stringified numeric JSON-RPC response IDs when they match numeric request IDs	No
#1022	—	Move the final draft conformance client scenarios to the modern lifecycle; core client suite reaches 32/32	No (harness only)
#1020	SEP-2663	Official Tasks Extension; replaces the experimental 2025-11-25 tasks API	Yes
#1025	SEP-2549	Default-enabled client response cache honoring ttlMs / cacheScope, with notification invalidation and configurable policy	No
#1024	—	Distributed Streamable HTTP EventStore and stateless cross-instance SSE replay	Yes (custom HTTP client API)
#1026	—	Reap completed response-send tasks in long-lived services	No
#1029	SEP-2260	Route associated server requests to the originating SSE response stream	No
#1009	—	Consolidate OAuth startup around declarative AuthorizationRequest	Yes
#1031	—	Use the authorization-server issuer as the default private_key_jwt audience	No
#964	—	Publish rmcp and rmcp-macros 3.0.0-beta.1	No

Release and conformance status

rmcp and rmcp-macros 3.0.0-beta.1 are available now. The release CI run at main e660b80 verifies the following with @modelcontextprotocol/conformance@0.2.0-alpha.9:

• Core server: 40/40 scenarios passing (114/114 checks)
• Core client: 32/32 scenarios passing (380/380 checks)
• Tasks Extension: 9/9 runnable server scenarios passing (35/35 checks); tasks-status-notifications remains upstream-skipped
• Client authorization extensions: auth/client-credentials-basic 8/8 and auth/client-credentials-jwt 8/8; auth/enterprise-managed-authorization remains an expected informational failure
• SEP-2260: feat: route SEP-2260 associated server requests to the originating SSE stream #1029 closed Implement SEP-2260: Server requests must associate with a client request #873 by enforcing request association and routing associated server requests on the originating SSE stream

There are no known failures in the dated 2026-07-28 core suites. The completed conformance epic #977 has the full matrix; stable 3.0 and non-conformance Tier 1 follow-ups remain tracked in the 2026-07-28 spec milestone and ROADMAP.md.

---

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
Client response caching	none	automatic per-Peer SEP-2549 cache; configure with ClientCacheConfig
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
Streamable HTTP server config	stateful_mode / with_stateful_mode	legacy_session_mode / with_legacy_session_mode; draft requests are always stateless
Notification subscriptions	resources/subscribe, resources/unsubscribe, standalone HTTP GET stream	long-lived subscriptions/listen request returning a Subscription handle
Tasks	experimental core TasksCapability, client task hint, tasks/list / tasks/result, #[task_handler]	io.modelcontextprotocol/tasks extension, server-directed CreateTaskResult, tasks/get / tasks/update / tasks/cancel, TaskManager
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
OAuth authorization startup	separate positional methods for DCR, CIMD, and pre-registration	one start_authorization(AuthorizationRequest) entry point selects the best supported mechanism
Custom Streamable HTTP SSE clients	get_stream(..., session_id: Arc<str>, ...)	session_id: Option<Arc<str>> supports stateless replay
Cross-instance SSE replay	in-process replay only	optional shared EventStore on LocalSessionManager / NeverSessionManager
SEP-2260 request association	server requests used the standalone SSE stream	bundled local sessions route them on the originating request stream

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

3.1 Client response cache (#1025, non-breaking)

Clients now cache server/discover, tools/list, prompts/list, resources/list, resources/templates/list, and resources/read responses per Peer. Existing call sites need no changes. The cache is enabled by default, but a response is only stored when the server sends a positive ttlMs; the default TTL for responses that omit the hint is zero.

Matching tool, prompt, resource-list, and resource-updated notifications invalidate affected entries automatically. Private entries are isolated by authorization partition, pagination cursors are part of list cache keys, and MRTR resources/read rounds are not cached.

Configure or disable the cache through the Peer:

use std::time::Duration;
use rmcp::ClientCacheConfig;

peer.set_response_cache_config(
    ClientCacheConfig::default()
        .with_default_ttl(Duration::from_secs(30))
        .with_max_ttl(Duration::from_secs(3600))
        .with_max_entries(1024)
        .with_private_partition(user_id)
        .with_serve_stale_on_error(false),
).await;

// Disable caching entirely:
peer.set_response_cache_config(ClientCacheConfig::disabled()).await;

// Or retain the policy and flush current entries:
peer.clear_response_cache().await;

By default, an expired cached value may be returned as Ok(..) when re-fetching fails. Set with_serve_stale_on_error(false) when callers must observe transport or server errors. Gateways or clients that reuse a connection across principals should set and update private_partition whenever the authorization context changes.

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.

10. Stateless HTTP and subscription streams (SEP-2567 / SEP-2575, #999 + #1000)

Streamable HTTP requests negotiating 2026-07-28 are always served statelessly, regardless of the legacy session setting. The public configuration name now makes that version boundary explicit:

// Before
let config = StreamableHttpServerConfig::default()
    .with_stateful_mode(false);

// 3.0
let config = StreamableHttpServerConfig::default()
    .with_legacy_session_mode(false);

Direct struct construction must similarly rename the stateful_mode field to legacy_session_mode. The setting continues to control sessions, GET/DELETE, priming, and resumability for protocol versions older than 2026-07-28; it does not opt draft requests back into sessions.

The draft protocol replaces resources/subscribe, resources/unsubscribe, and the standalone HTTP GET stream with a long-lived, transport-neutral subscriptions/listen request:

• Servers advertise list-change and resource-subscription capabilities, implement ServerHandler::accepted_subscription_filter, and produce notifications from ServerHandler::listen(SubscriptionContext). SubscriptionSink enforces the accepted filter and adds the subscription request ID.
• Clients call Peer<RoleClient>::listen(SubscriptionFilter) or listen_with_capacity, consume notifications from the returned Subscription, and cancel that request when finished.
• Modern HTTP uses the listen POST response stream directly. It does not use a session, GET, DELETE, Last-Event-ID, or automatic resumption after reconnect.
• The deprecated subscribe() and unsubscribe() helpers keep their existing wire behavior for older negotiated protocol versions.

See the subscriptions_streamhttp client and server examples for complete implementations.

11. Tasks moved to an extension (SEP-2663, #1020)

The experimental 2025-11-25 tasks API has been replaced by the official io.modelcontextprotocol/tasks extension. There is no compatibility shim for the old API.

Removed APIs and wire methods:

• TaskMetadata, TasksCapability, TaskRequestsCapability, TaskAugmentedRequestParamsMeta, and .with_task(..)
• tasks/list and tasks/result (task status and terminal payloads now come from tasks/get)
• #[task_handler] and the tool execution(task_support) attribute

Clients declare support through the extension capability and use the one-round tool call API so they can observe a task handle:

let client_info = ClientInfo::new(
    ClientCapabilities::builder().enable_tasks().build(),
    Implementation::from_build_env(),
);

match client.call_tool_once(params).await? {
    CallToolResponse::Task(created) => {
        let task_id = created.task.task_id;
        // Poll client.peer().get_task(GetTaskParams::new(task_id)).
    }
    CallToolResponse::Complete(result) => { /* server chose synchronous completion */ }
    CallToolResponse::InputRequired(input) => { /* drive MRTR as usual */ }
}

The high-level RunningService::call_tool helper drives MRTR but does not poll Tasks-extension results; when the server may create a task, use call_tool_once, then Peer::get_task, update_task, and cancel_task.

Servers advertise the extension with ServerCapabilities::builder().enable_tasks(), check RequestContext::client_capabilities().is_some_and(|caps| caps.supports_tasks()), and return CallToolResponse::Task(CreateTaskResult::new(task)) when they choose asynchronous execution. rmcp::task_manager::TaskManager provides durable task creation, tasks/get / tasks/update / tasks/cancel handlers, TTL enforcement, in-task input requests, and cooperative cancellation through TaskContext::cancelled() / TaskExit.

Task status notifications through subscriptions/listen are not wired yet, so clients must currently poll tasks/get. See the servers_task_stdio and clients_task_stdio examples for the complete lifecycle.

12. Distributed Streamable HTTP event store (#1024)

A shared EventStore now lets Streamable HTTP responses survive disconnects and server-instance changes. Event IDs identify their stream without relying on a session ID, so stateless clients can reconnect with Last-Event-ID and no Mcp-Session-Id. Legacy session replay uses the same store contract.

Attach your implementation to either bundled session manager:

use std::sync::Arc;
use rmcp::transport::streamable_http_server::session::{
    EventStore, local::LocalSessionManager, never::NeverSessionManager,
};

let event_store: Arc<dyn EventStore> = Arc::new(MyEventStore::new());
let sessions = LocalSessionManager::default().with_event_store(event_store.clone());
let stateless = NeverSessionManager::default().with_event_store(event_store);

EventStore implementations must assign globally unique event IDs, persist before returning from store_event, and replay only later events from the same stream.

Two API changes affect custom integrations:

• StreamableHttpClient::get_stream and get_stream_with_max_sse_event_size now receive session_id: Option<Arc<str>>. Handle None by reconnecting without Mcp-Session-Id; last_event_id still identifies the stream.
• LocalSessionManager and NeverSessionManager no longer implement UnwindSafe / RefUnwindSafe because they may contain Arc<dyn EventStore>. Code that moves them across catch_unwind must adjust that boundary.

13. OAuth startup uses AuthorizationRequest (#1009)

The three OAuth startup paths are now one declarative API. OAuthState::start_authorization_with_metadata_url and start_authorization_with_preregistered_client were removed, and the positional form of start_authorization changed.

use rmcp::transport::AuthorizationRequest;

// 2.x
oauth_state
    .start_authorization(&["mcp"], redirect_uri, Some("My MCP Client"))
    .await?;

// 3.0
oauth_state
    .start_authorization(
        AuthorizationRequest::new(redirect_uri)
            .with_scopes(["mcp"])
            .with_client_name("My MCP Client"),
    )
    .await?;

Add .with_preregistered_client(client_id) and optionally .with_client_secret(secret) for pre-registered credentials, or .with_client_metadata_url(url) for CIMD. The SDK selects pre-registration first, then CIMD when advertised, then Dynamic Client Registration. Omitting .with_scopes(...) keeps automatic scope selection. Direct callers of AuthorizationSession::new now pass the same AuthorizationRequest; failures return the AuthorizationManager alongside the error so the flow can be retried.

14. SEP-2260 request association (#1029, non-breaking)

Sampling, elicitation, and roots requests created while handling a client request are now associated with that request. The bundled local Streamable HTTP session manager routes them over the originating POST SSE stream instead of the standalone GET stream. Clients negotiating 2026-07-28 also reject an unassociated restricted server request with -32602; ping is exempt.

No migration is required for the bundled manager. Custom SessionManager implementations that serialize messages across processes must preserve the association themselves because the in-process OriginatingRequestId extension is not serialized.

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)
• StreamableHttpServerConfig::stateful_mode / .with_stateful_mode(..) → legacy_session_mode / .with_legacy_session_mode(..)
• Modern resource/list-change subscriptions → replace subscribe() / unsubscribe() and standalone GET handling with listen(SubscriptionFilter); server implementations add accepted_subscription_filter and listen
• Experimental tasks API → declare enable_tasks(), replace the client task hint and tasks/list / tasks/result with call_tool_once plus tasks/get / tasks/update / tasks/cancel, and replace #[task_handler] with explicit TaskManager integration
• Client cache policy → disable stale-on-error when callers must observe re-fetch failures; set private_partition when one connection can serve multiple authorization contexts
• OAuth startup → replace positional or specialized start methods with AuthorizationRequest builders
• Custom StreamableHttpClient impls → accept Option<Arc<str>> for SSE reconnect session IDs and handle None
• Cross-instance Streamable HTTP replay → implement EventStore and attach it with .with_event_store(..)
• catch_unwind around bundled session managers → account for the loss of UnwindSafe / RefUnwindSafe
• Custom serializing SessionManager impls → preserve SEP-2260 originating-request association across the process boundary
• Run cargo build and follow remaining compiler errors — the compiler is your friend here

---

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

Started 2026-07-10 and updated through main e660b80 / rmcp-v3.0.0-beta.1 on 2026-07-23. This guide will be kept current through the stable 3.0 release.