[FEATURE] MCP Specification 2025-11-25

[yonib05]

Problem Statement

Summary

The Model Context Protocol (MCP) released a new spec revision (2025-11-25) on the one-year anniversary of MCP going public. This revision introduces several production-readiness features driven by community feedback, including enhanced OAuth/auth flows, icon metadata, updated elicitation, and more.

This issue tracks the work needed to update our SDK implementation to conform to the 2025-11-25 spec, which supersedes the 2025-06-18 revision.

Note: Tasks (SEP-1686) and notifications are tracked in a separate issue.

Full diff: 2025-06-18...2025-11-25 on GitHub

---

Major Changes

OpenID Connect Discovery for Auth Server Discovery

Support for OpenID Connect Discovery 1.0 as an auth server discovery mechanism, alongside existing OAuth 2.0 Protected Resource Metadata discovery. (PR #797)

Icon Metadata for Tools, Resources, Resource Templates, and Prompts

New icons array field on Tool, Resource, ResourceTemplate, and Prompt definitions. Icon schema: { src: string, mimeType: string, sizes?: string[] }. (SEP-973)

Incremental Scope Consent via WWW-Authenticate

Incremental scope consent flow using WWW-Authenticate headers, allowing servers to request additional OAuth scopes after initial authorization. (SEP-835)

Tool Name Guidance

Guidance on tool naming: 1–128 characters, case-sensitive, restricted to A-Z, a-z, 0-9, _, -, ., unique within a server. (SEP-986)

Updated ElicitResult and EnumSchema

Standards-based enum schemas supporting titled enums (oneOf with const/title), untitled enums (enum array), single-select (type: "string"), multi-select (type: "array" with items), and minItems/maxItems constraints. (SEP-1330)

URL Mode Elicitation

New mode: "url" elicitation alongside existing mode: "form". Includes client capability elicitation.url, params (url, elicitationId, message), URLElicitationRequiredError (code -32042), and security requirements around URL handling and phishing mitigation. (SEP-1036)

Tool Calling in Sampling

New tools and toolChoice parameters on sampling/createMessage, allowing servers to specify which tools the sampled model can use. (SEP-1577)

OAuth Client ID Metadata Documents

Client ID Metadata Documents (CIMD) as the recommended client registration mechanism, with discovery and validation support. (SEP-991, PR #1296)

---

Minor Changes

• Clarify stdio stderr logging: servers may use stderr for all logging types, not just errors (PR #670)
• HTTP 403 Forbidden for invalid Origin headers in Streamable HTTP transport (PR #1439)
• Polling SSE streams: servers can disconnect at will (SEP-1699)
• GET stream polling/resumption clarifications (Issue #1847)
• Align OAuth 2.0 Protected Resource Metadata discovery with RFC 9728 — WWW-Authenticate header optional with .well-known fallback (SEP-985)
• Updated Security Best Practices
• Optional description field on Implementation interface
• Input validation errors returned as Tool Execution Errors instead of Protocol Errors for model self-correction (SEP-1303)
• Default values for all primitive types in elicitation schemas: string, number, enum (SEP-1034)
• JSON Schema 2020-12 as default dialect for MCP schema definitions (SEP-1613)
• Decoupled request payloads from RPC method definitions into standalone parameter schemas (SEP-1319, PR #1284)

---

Out of Scope

These spec governance updates don't require code changes:

• Formalized MCP governance structure (SEP-932)
• Shared communication practices and community guidelines (SEP-994)
• Working Groups and Interest Groups formalization (SEP-1302)
• SDK tiering system with feature support and maintenance requirements (SEP-1730)

---

References

• MCP 2025-11-25 Changelog
• Elicitation Specification
• Tools Specification
• Full diff: 2025-06-18 → 2025-11-25
• MCP Anniversary Blog Post