Migrating to 2.x

[DaleSeo]

Upgrading to RMCP 2.x — Migration Guide

RMCP 2.x aligns the model types with the current MCP 2025-11-25 specification. This is a breaking release. The JSON wire format is unchanged (only additive _meta / optional fields were introduced) — the breaking changes are at the Rust API level: type names, struct construction, and field access. This guide covers every breaking change and how to update.

To verify the new shapes, cross-check against the official MCP 2025-11-25 Schema Reference. The rmcp type names below map 1:1 to the spec types there.

Why 2.0?

Over time the rmcp model drifted from the MCP Schema Reference. The same content union existed in three slightly different forms (Content/RawContent, PromptMessageContent, SamplingMessageContent), many types sat behind an Annotated<T> wrapper, several names didn't match the spec (ResourceReference, CreateElicitation*, GetTaskInfo*, PrimitiveSchema, and others), and some spec fields were missing (_meta in several places, audio in prompt content). In practice this made it hard to find the type that corresponds to a given spec construct, or to tell whether it was complete and correctly named, and that cognitive load fell on SDK users and maintainers alike.

We had deferred this cleanup because doing it properly is a breaking change, and it wasn't worth spending a major version on by itself. The upcoming 2026-07-28 revision changes that: it requires breaking changes regardless, so realigning the existing model to the current 2025-11-25 schema in the same major (consistent with our versioning approach in #813) avoids an extra bump and a second round of migration.

It also gives the 2026-07-28 work a much better starting point. Building support for the new spec on a model that already maps cleanly to the reference is far simpler than layering it on types that diverge, which would carry the duplication and naming debt forward into v3.

The change is large in line count, but the JSON wire format is unchanged (only additive _meta and optional fields). Most of the volume is mechanical renames and regenerated schema snapshots, and every breaking change is covered below.

---

TL;DR

Area	Old (1.x)	New (2.0)
Content union	Content / RawContent	ContentBlock
Content structs	RawTextContent, RawImageContent, … wrapped in Annotated<T>	flat TextContent, ImageContent, AudioContent, EmbeddedResource with inline annotations / _meta
Resource	RawResource, Annotated<RawResource>	flat Resource (size: u64)
Prompt message	PromptMessageContent + PromptMessageRole	ContentBlock + Role
Sampling content	SamplingMessageContent	SamplingMessageContentBlock
Completion ref	ResourceReference	ResourceTemplateReference
Elicitation	CreateElicitation{Request,RequestParams,Result}, PrimitiveSchema	Elicit{Request,RequestParams,Result}, PrimitiveSchemaDefinition
Tasks	GetTaskInfo*, GetTaskResult*	GetTask*, GetTaskPayload* (+ new TaskMetadata, RelatedTaskMetadata, TaskStatusNotification)
Task status notifications	TaskStatusNotificationParam = Task	TaskStatusNotificationParam wraps { _meta, task } and preserves task field access via Deref
Sampling tool results	missing ToolResultContent.content could deserialize as []	ToolResultContent.content is required; use content: [] for empty results
Construction	Foo { field, .. } literals	Foo::new(..).with_*(..) (most wire types are now #[non_exhaustive])
CancelledNotificationParam.request_id	RequestId	Option<RequestId>

Old names are kept as #[deprecated] aliases for one release where practical, so most code keeps compiling with warnings pointing at the new name.

---

1. Unified content model (ContentBlock)

The Annotated<T> wrapper and the parallel Raw* structs are gone. Each content type is now a single flat struct, and the union is ContentBlock (text | image | audio | resource_link | resource).

// 1.x
let c = RawContent::text("hi").no_annotation();
let text = content.raw.as_text();

// 2.0
let c = ContentBlock::text("hi");
let text = content.as_text();

annotations and _meta are inline fields now; set them with builders. AudioContent also gained _meta.

let c = ContentBlock::Text(
    TextContent::new("hi").with_annotations(Annotations::default().with_priority(0.8)),
);

The Annotated<T> wrapper and the AnnotateAble trait are replaced by inline annotations and _meta fields on each content/resource type. Use .with_annotations(..) in place of .annotate(..) / .optional_annotate(..) (build the Annotations with .with_priority(..) / .with_audience(..) / .with_timestamp(..)), and drop .no_annotation() (annotations are simply left unset).

ToolResultContent.content is now required for sampling tool results. Send an empty vector (JSON "content": []) when there are no content blocks. This does not change CallToolResult, which still keeps its missing-content compatibility behavior.

2. #[non_exhaustive] on wire types

Content, resource, capability, and most spec structs are now #[non_exhaustive], so struct-literal construction from downstream crates no longer compiles. Use the constructors/builders:

// 1.x
let r = RawResource { uri, name, title: None, description: None,
                      mime_type: None, size: None, icons: None, meta: None };

// 2.0
let r = Resource::new(uri, name)
    .with_description("…")
    .with_mime_type("text/plain")
    .with_size(2048); // size is now u64 (was u32)

This also keeps routine spec additions from forcing a breaking release (#865 is an example of one such forced change). See #813 for the versioning rationale.

3. Prompts use Role + ContentBlock

PromptMessageContent is replaced by the unified ContentBlock, and PromptMessageRole by the shared Role. PromptMessage.content is now a ContentBlock and PromptMessage.role a Role.

// 1.x
PromptMessage::new(PromptMessageRole::User, PromptMessageContent::text("hi"));

// 2.0
PromptMessage::new(Role::User, ContentBlock::text("hi"));
// or: PromptMessage::new_text(Role::User, "hi");

PromptMessage::new_image / new_audio now take a meta: Option<Meta> argument: (role, data, mime_type, meta, annotations).

4. Tasks

• New typed TaskMetadata { ttl } — the task field on CallToolRequestParams / CreateMessageRequestParams is now Option<TaskMetadata> (was Option<JsonObject>); construct with TaskMetadata::new().with_ttl(..).
• New RelatedTaskMetadata { task_id } plus the io.modelcontextprotocol/related-task _meta key.
• New TaskStatusNotification (notifications/tasks/status) on both client and server notification unions.
• TaskStatusNotificationParam now models NotificationParams & Task instead of being a direct Task alias. Construct it with TaskStatusNotificationParam::new(task) or task.into(), access .task when you need the wrapped Task, and existing task field access such as params.task_id remains available through Deref.
• Request/method renames (old names kept as deprecated aliases):

1.x	2.0
GetTaskInfoRequest / GetTaskInfoParams	GetTaskRequest / GetTaskParams
GetTaskResultRequest / GetTaskResultParams	GetTaskPayloadRequest / GetTaskPayloadParams

• ListTasksResult dropped the non-spec total field and gained _meta.
• The unused, non-spec TaskList type was removed; use ListTasksResult.

5. Spec-name renames

Old names remain as #[deprecated] aliases.

1.x	2.0
SamplingMessageContent	SamplingMessageContentBlock
ResourceReference	ResourceTemplateReference
CreateElicitationRequest	ElicitRequest
CreateElicitationRequestParams	ElicitRequestParams
CreateElicitationResult	ElicitResult
PrimitiveSchema	PrimitiveSchemaDefinition
ElicitationCompletionNotification	ElicitationCompleteNotification

6. _meta coverage

_meta was added to the result / notification-param types that were missing it for spec parity: InitializeResult, GetPromptResult, ReadResourceResult, CompleteResult, ListTasksResult, ListRootsResult, CreateTaskResult, ProgressNotificationParam, CancelledNotificationParam, ResourceUpdatedNotificationParam, LoggingMessageNotificationParam, and the elicitation-complete notification params. Constructors default these to None.

7. Cancellation

CancelledNotificationParam.request_id is now Option<RequestId> (was RequestId), per 2025-11-25 — task cancellation uses tasks/cancel instead, so requestId is optional.

// 1.x
let p = CancelledNotificationParam { request_id, reason: None };

// 2.0  — new(request_id, reason); request_id is now Option<RequestId>
let p = CancelledNotificationParam::new(Some(request_id), None);

---

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