Public API diff: v1.0.0-rc.5 to 1.0 candidate

This report records the public Elixir API compatibility gate for the MCP 2026-07-28 migration. The comparison is between:

• baseline: v1.0.0-rc.5 (a2464c3423ee48ba825402cc2d17be8042f1451a);
• candidate: the v1.0.0-rc.6 release commit.

The rc.6 package starts the final modern-preferred soak. This report compares the retained rc.5 API surface with the 1.0 candidate, not version strings.

Method

The rc.5 tag and the candidate were compiled independently. As a conservative package-level check, the audit included every BEAM module whose compile source is under lib/, even when the module is hidden from HexDocs. It normalized and compared:

• module names;
• exported functions and arities, excluding module_info/* and __info__/1;
• callbacks, via Code.Typespec.fetch_callbacks/1 and Code.Typespec.spec_to_quoted/2;
• public and opaque types, via Code.Typespec.fetch_types/1 and Code.Typespec.type_to_quoted/1;
• struct field names.

The snapshot totals were:

The type count treats a changed definition as one removed textual row and one added textual row. Those changes were inspected individually as described below. Public compatibility characterization tests remain the runtime check for return shapes and retained deprecated modules; a BEAM snapshot cannot prove behavioral equivalence by itself.

Result

No public module, exported function/arity, callback, named type, or struct field present in rc.5 was removed.

Three existing handler callbacks were widened to admit MRTR input-required results while preserving every rc.5 return:

• ExMCP.Server.Handler.handle_call_tool/3;
• ExMCP.Server.Handler.handle_get_prompt/3;
• ExMCP.Server.Handler.handle_read_resource/2.

Existing structs only gained fields. The additions on rc.5 structs are:

• ExMCP.Response: resultType, ttlMs, and cacheScope;
• ExMCP.Client: MRTR and subscription bookkeeping;
• ExMCP.Tasks.Task: error and input_requests;
• ExMCP.Transport.HTTP: protocol_era, modern_streams, and tool_headers;
• ExMCP.Server.HandlerServer: protocol-era, request-context, MRTR, replay-cache, and subscription state;
• ExMCP.Authorization.Provider.OAuth: authorization-server issuer, rejected-issuer, and granted-scope tracking used to bound migration and scope-step-up retries.

The changed typespec definitions are additive or corrective except for the OAuth state hardening called out below:

• authorization configuration types add issuer, metadata-fetch, client registration, credential-store, protocol-version, and HTTP adapter options;
• capability types add the standard extensions map;
• JSON Schema types now admit all map-shaped schemas, including boolean schemas where the receiving API supports them;
• tool_result/0 widens structuredContent from string-keyed maps to any JSON value, and result/task/transport structs describe their added fields;
• ClientRegistration.registration_request/0 now declares application_type, which its rc.5 documentation and runtime validation already required.

OAuthFlow.auth_params/0 no longer advertises caller-supplied :state. start_authorization_flow/1 now rejects it and generates a high-entropy, single-use state bound to the transaction store. This is an intentional security behavior change, not a removed function or return shape. Applications that supplied :state must retain the returned transaction and use its generated state_param instead.

Additive public API

The candidate adds 54 modules and 402 exports. The main supported additions are grouped here rather than listing internal plumbing:

• era selection and discovery: ExMCP.Client.EraProbe, ExMCP.Client.EraCache, ExMCP.Server.Discover, and ExMCP.Protocol.Initialize;
• modern request context and envelopes: ExMCP.Server.RequestContext, ExMCP.Server.Context, ExMCP.Protocol.Meta, ExMCP.Protocol.ResultEnvelope, and ExMCP.Protocol.CacheableResult;
• MRTR: ExMCP.Client.MRTR, ExMCP.Client.InputDispatcher, ExMCP.Server.MRTR, ExMCP.Server.RequestState, and replay-cache modules;
• subscriptions: ExMCP.Client.Subscription, ExMCP.Server.Subscriptions, the ETS adapter, and the optional PubSub fanout adapter;
• Tasks extension: ExMCP.Tasks, ExMCP.Tasks.Extension, task operations, server dispatch, and store behavior/ETS implementation;
• HTTP 2026 routing: request/tool header modules and modern request-stream clients;
• OAuth 2026 security: credential stores, issuer checking, metadata fetchers, registration policy, and transaction storage.

Existing modules gain additive entry points such as ExMCP.Client.discover/2, listen/3, get_task/3, update_task/4, and cancel_task/3, plus schema compilation, version-registry, version-aware error, stream-management, MRTR result helpers, and option-aware OAuth metadata URL validation.

Protocol-driven behavior changes

These are wire or security changes rather than public Elixir symbol removals:

• modern-preferred connections negotiate MCP 2026-07-28 and use server/discover, stateless Streamable HTTP routing headers, result envelopes, MRTR, and subscriptions/listen;
• legacy revisions and deprecated HTTP+SSE remain selectable throughout 1.x;
• Tasks are advertised only when the extension is configured and supported;
• result cache metadata is validated, but ExMCP 1.0 does not store or reuse responses;
• OAuth state is generated and consumed by ExMCP as described above.

The wire migration is intentionally landing before stable 1.0. These changes would have required an ExMCP 2.0 release if 1.0 had already been published; the retained rc.5 public surface lets existing Elixir applications migrate without a simultaneous package-API rewrite.

Release decision

The public-API gate is satisfied: there are no unresolved rc.5 symbol, callback, named-type, struct-field, or return-shape removals. Stable 1.0 still depends on the conformance, security, interoperability, load, rollback, and minimum seven-day modern-preferred RC soak gates in the migration plan.