omcp
Proposals

SEP-414 Document OpenTelemetry Trace Context Propagation Conventions

Final · Standards Track · Created 2025-04-25

• Status: Final
• Type: Standards Track
• Created: 2025-04-25
• Author(s): Adrian Cole (@codefromthecrypt)
• Sponsor: Marcelo Trylesinski (@Kludex)
• PR: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/414

Abstract

This SEP documents conventions for OpenTelemetry (OTel) trace context propagation in MCP.

OTel semantic conventions for MCP specify using _meta as the carrier for W3C Trace Context keys. This is already in practice in the C# SDK and other implementations.

This specification documents an exception to the DNS prefixing convention for keys in _meta. This enables interoperability across existing and new implementations and serves as a foundation for related SEPs (such as SEP-2028).

Specification

This SEP adds documentation to the MCP specification, noting:

1. When OTel trace context is propagated via _meta, the keys traceparent, tracestate, and baggage follow W3C Trace Context and W3C Baggage value formats.

2. A non-normative example showing trace context in _meta.

3. A note clarifying why this an exception to DNS prefixing keys in _meta: to remain compatible with existing implementations and the OpenTelemetry semantic conventions.

See agentclientprotocol/agent-client-protocol#297 for equivalent documentation changes in ACP.

Non-normative example

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "New York"
    },
    "_meta": {
      "traceparent": "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01"
    }
  }
}

Rationale

Why document this?

This is currently documented elsewhere, but not as an MCP specification. Doing so ensures that SEPs depending on this pattern can complete, as well as other SDKs in and outside the MCP org can as well, such as Logfire and ToolHive.

If we don't document this shared concern, differing interpretations could materialize, such as namespacing traceparent like io.modelcontextprotocol.traceparent, which will break traces and log correlation.

Related SEPs

• SEP-1788 - reserved keys in _meta; should be updated with traceparent, tracestate, and baggage when this SEP is implemented
• SEP-2028 - builds on this SEP for forwarding _meta values to HTTP headers

Backward Compatibility

This SEP documents existing conventions and is backward compatible.

Security Implications

Trace context in _meta may include correlation IDs. Implementations should follow existing data-handling guidance appropriate to their environment.

Reference Implementation

Existing implementations using this pattern:

• C# SDK instrumentation
• Python SDK instrumentation
• OpenInference MCP instrumentation (Python)
• OpenInference MCP instrumentation (TypeScript)
• Envoy AI Gateway
• Logfire
• ToolHive

SEP-932 Model Context Protocol Governance

Final · Process · Created 2025-07-08

• Status: Final
• Type: Process
• Created: 2025-07-08
• Author(s): David Soria Parra
• PR: #931
• Issue: #932

Abstract

This SEP establishes the formal governance model for the Model Context Protocol (MCP) project. It defines the organizational structure, decision-making processes, and contribution guidelines necessary for transparent and effective project stewardship. The proposal introduces a hierarchical governance structure with clear roles and responsibilities, along with the Specification Enhancement Proposal (SEP) process for managing protocol changes.

Motivation

As the Model Context Protocol grows in adoption and complexity, the need for formal governance becomes critical. The current informal decision-making process lacks:

1. Transparency: Community members have no clear visibility into how decisions are made
2. Participation Pathways: Contributors lack defined ways to influence project direction
3. Accountability: No formal structure exists for resolving disputes or contentious issues
4. Scalability: Ad-hoc processes cannot scale with growing community and technical complexity

Without formal governance, the project risks:

• Fragmentation of the ecosystem
• Unclear or inconsistent technical decisions
• Reduced community trust and participation
• Inability to effectively manage contributions at scale

Rationale

The proposed governance model draws inspiration from successful open source projects like Python, PyTorch, and Rust. Key design decisions include:

Hierarchical Structure

We chose a hierarchical model (Contributors → Maintainers → Core Maintainers → Lead Maintainers) that is effectively how the project decisions are made today. From there we will continue to evolve governance in the best interest of the project.

Individual vs Corporate Membership

Membership is explicitly tied to individuals rather than companies to:

• Ensure decisions prioritize protocol integrity over corporate interests
• Prevent capture by any single organization
• Maintain continuity when individuals change employers

SEP Process

The Specification Enhancement Proposal process ensures:

• All protocol changes undergo thorough review
• Community input is systematically collected
• Design decisions are documented for posterity
• Implementation precedes finalization

Specification

Governance Structure

Contributors

• Any individual who files issues, submits pull requests, or participates in discussions
• No formal membership or approval required

Maintainers

• Responsible for specific components (SDKs, documentation, etc.)
• Appointed by Core Maintainers
• Have write/admin access to their repositories
• May establish component-specific processes

Core Maintainers

• Deep understanding of MCP specification required
• Responsible for protocol evolution and project direction
• Meet bi-weekly for decisions
• Can veto maintainer decisions by majority vote
• Current members listed in governance documentation

Lead Maintainers

• Justin Spahr-Summers and David Soria Parra
• Can veto any decision
• Appoint/remove Core Maintainers
• Admin access to all infrastructure

Backwards Compatibility

N/A

Reference Implementation

See #931

1. Documentation Files:
   • /docs/community/governance.mdx - Full governance documentation
   • /docs/community/sep-guidelines.mdx - SEP process guidelines

Security Implications

N/A

SEP-973 Expose additional metadata for Implementations, Resources, Tools and Prompts

Final · Standards Track · Created 2025-07-15

• Status: Final
• Type: Standards Track
• Created: 2025-07-15
• Author(s): @jesselumarie
• Issue: #973

Abstract

This SEP proposes adding two optional fields—icons and websiteUrl. The icons and websiteUrl would be added to the Implementation schema so that clients can visually identify third-party implementations and link directly to their documentation. The icons parameter will also be added to the Tool, Resource and Prompt schemas. While this can be used by both servers and clients for all implementations, we expect it to be used initially for server-provided implementations.

Motivation

Current State

Current implementations only expose namespaced metadata, forcing clients to display generic labels with no visual cues.

Proposed State

The proposed implementation would allow us to add visual affordances and links to documentation, making it easier to visually identify which servers/clients are providing an implementation e.g. a tool in a slash command interface:

• Visual Affordance: Icons make it immediately clear to users which tool or resource source is in use.
• Discoverability: A link to documentation (websiteUrl) allows clients to direct users to more information with a single click.

Rationale

This design builds on prior work in web manifests (MDN) and consolidates community feedback:

• Consolidation of PRs: Merges the changes from PR #417 and PR #862 into a single, cohesive enhancement.
• Flexible Icon Sizes: Supports multiple icon sizes (e.g., 48x48, 96x96, or any for vector formats) to accommodate different client UI needs.
• Optional Fields: By making both fields optional, existing implementations remain fully compatible.

Specification

Extend the Implementation object as follows:

/**
 * A url pointing to an icon URL or a base64-encoded data URI
 *
 * Clients that support rendering icons MUST support at least the following MIME types:
 * - image/png - PNG images (safe, universal compatibility)
 * - image/jpeg (and image/jpg) - JPEG images (safe, universal compatibility)
 *
 * Clients that support rendering icons SHOULD also support:
 * - image/svg+xml - SVG images (scalable but requires security precautions)
 * - image/webp - WebP images (modern, efficient format)
 */
export interface Icon {
  /**
   * A standard URI pointing to an icon resource.
   *
   * Consumers MUST takes steps to ensure URLs serving icons are from the
   * same domain as the client/server or a trusted domain.
   *
   * Consumers MUST take appropriate precautions when consuming SVGs as they can contain
   * executable JavaScript
   *
   * @format uri
   */
  src: string;
  /** Optional override if the server’s MIME type is missing or generic. */
  mimeType?: string;
  /** e.g. "48x48", "any" (for SVG), or "48x48 96x96" */
  sizes?: string;
}

/**
 * Describes the MCP implementation
 */
export interface Implementation extends BaseMetadata {
  version: string;
  /**
   * An optional list of icons for this implementation.
   * This can be used by clients to display the implementation in a user interface.
   * Each icon should have a `kind` property that specifies whether it is a data representation or a URL source, a `src` property that points to the icon file or data representation, and may also include a `mimeType` and `sizes` property.
   * The `mimeType` property should be a valid MIME type for the icon file, such as "image/png" or "image/svg+xml".
   * The `sizes` property should be a string that specifies one or more sizes at which the icon file can be used, such as "48x48" or "any" for scalable formats like SVG.
   * The `sizes` property is optional, and if not provided, the client should assume that the icon can be used at any size.
   */
  icons?: Icon[];
  /**
   * An optional URL of the website for this implementation.
   *
   * Consumers MUST takes steps to ensure URLs serving icons are from the
   * same domain as the client/server or a trusted domain.
   *
   * Consumers MUST take appropriate precautions when consuming SVGs as they can contain
   * executable JavaScript
   *
   * @format: uri
   */
  websiteUrl?: string;
}

Extend the Tool, Resource and Prompt interfaces with the following type:

  /**
   * An optional list of icons for a resource.
   * This can be used by clients to display the resource's icon in a user interface.
   * Each icon should have a `kind` property that specifies whether it is a data representation or a URL source, a `src` property that points to the icon file or data representation, and may also include a `mimeType` and `sizes` property.
   * The `mimeType` property should be a valid MIME type for the icon file, such as "image/png" or "image/svg+xml".
   * The `sizes` property should be a string that specifies one or more sizes at which the icon file can be used, such as "48x48" or "any" for scalable formats like SVG.
   * The `sizes` property is optional, and if not provided, the client should assume that the icon can be used at any size.
   */
  icons?: Icon[];

Backwards Compatibility

Both icons and websiteUrl are optional fields; clients that ignore them will fall back to existing behavior.

Security Implications

This shouldn't introduce any new security implications.

SEP-985 Align OAuth 2.0 Protected Resource Metadata with RFC 9728

Final · Standards Track · Created 2025-07-16

• Status: Final
• Type: Standards Track
• Created: 2025-07-16
• Author(s): sunishsheth2009
• Issue: #985

Abstract

This proposal brings the MCP spec's handling of OAuth 2.0 Protected Resource Metadata in line with RFC 9728.

Currently, the MCP spec requires the use of the HTTP WWW-Authenticate header when returning a 401 Unauthorized to indicate the location of the protected resource metadata. However, RFC 9728, Section 5 states:

“A protected resource MAY use the WWW-Authenticate HTTP response header field, as discussed in RFC 9110, to return a URL to its protected resource metadata to the client.”

This suggests that the MCP spec could be made more flexible while still maintaining RFC compliance.

Rationale

Many large-scale, dynamic, multi-tenant environments rely on a centralized authentication service separate from the backend resource servers. In such deployments, injecting WWW-Authenticate headers from backend services is non-trivial due to separation of concerns and infrastructure complexity.

In these scenarios, having the option to discover metadata via a well-known URL provides a practical path forward for easier MCP adoption. Requiring only the header would impose significant communication overhead between components, especially when hundreds or thousands of MCP instances are created and destroyed dynamically. Also if there are specific managed MCP servers, adopting headers across centralized system would add significant overhead.

While this increases complexity for clients—who must now implement logic to probe metadata endpoints—it reduces friction for server deployments and may encourage broader adoption. There are tradeoffs:

Pros for Server Developers: Avoid complex header injection; simplifies integration in distributed environments.

Cons for Client Developers: Clients must fall back to metadata discovery logic when the header is absent, increasing client complexity.

Proposed State

Update the MCP spec to:

Clients MUST interpret the WWW-Authenticate header, and fallback to probing for metadata if not present.
Servers SHOULD return the WWW-Authenticate header

The reason for deviating a bit on the RFC: Go with SHOULD over MAY for WWW-Authenticate is that it makes supporting other features, such as incremental authorization easier (e.g. you make a request for a tool, but need additional scopes, and receive a WWW-Authenticate challenge indicating the scopes).

Based on the above, following the updated flow:

• Attempt the MCP request without a token.
• If a 401 Unauthorized response is received: Check for a WWW-Authenticate header. If present and includes the resource_metadata parameter, use it to locate the resource metadata.
• If the header is absent or does not include resource_metadata, fallback to requesting /.well-known/oauth-protected-resource.

This change allows more flexible deployment models without removing existing capabilities.

Backward Compatibility

This proposal is fully backward-compatible.

It retains support for the WWW-Authenticate header (already in the spec) and introduces a fallback mechanism using the .well-known metadata path, which is already defined in MCP as a MUST-support location.

Clients that already support metadata probing benefit from improved interoperability. Servers are not required to emit the WWW-Authenticate header if it is infeasible, but doing so is still encouraged to reduce client complexity and enable future extensibility.

SEP-986 Specify Format for Tool Names

Final · Standards Track · Created 2025-07-16

• Status: Final
• Type: Standards Track
• Created: 2025-07-16
• Author(s): kentcdodds
• Issue: #986

Abstract

The Model Context Protocol (MCP) currently lacks a standardized format for tool names, resulting in inconsistencies and confusion for both implementers and users. This SEP proposes a clear, flexible standard for tool names: tool names should be 1–64 characters, case-sensitive, and may include alphanumeric characters, underscores (_), dashes (-), dots (.), and forward slashes (/). This aims to maximize compatibility, clarity, and interoperability across MCP implementations while accommodating a wide range of naming conventions.

Motivation

Without a prescribed format for tool names, MCP implementations have adopted a variety of naming conventions, including different separators, casing, and character sets. This inconsistency can lead to confusion, errors in tool invocation, and difficulties in documentation and automation. Standardizing the allowed characters and length will:

• Make tool names predictable and interoperable across clients.
• Allow for hierarchical and namespaced tool names (e.g., using / and .).
• Support both human-readable and machine-generated names.
• Avoid unnecessary restrictions that could block valid use cases.

Rationale

Community discussion highlighted the need for flexibility in tool naming. While some conventions (like lower-kebab-case) are common, many tools and clients use uppercase, underscores, dots, and slashes for namespacing or clarity. The proposed pattern—allowing a-z, A-Z, 0-9, _, -, ., and /—is based on patterns used in major clients (e.g., VS Code, Claude) and aligns with common conventions in programming and APIs. Restricting spaces and commas avoids parsing issues and ambiguity. The length limit (1–64) is generous enough for most use cases but prevents abuse.

Specification

• Tool names SHOULD be between 1 and 64 characters in length (inclusive).
• Tool names are case-sensitive.
• Allowed characters: uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), dash (-), dot (.), and forward slash (/).
• Tool names SHOULD NOT contain spaces, commas, or other special characters.
• Tool names SHOULD be unique within their namespace.
• Example valid tool names:
  • getUser
  • user-profile/update
  • DATA_EXPORT_v2
  • admin.tools.list

Backwards Compatibility

This change is not backwards compatible for existing tools that use disallowed characters or exceed the new length limits. To minimize disruption:

• Existing non-conforming tool names SHOULD be supported as aliases for at least one major version, with a deprecation warning.
• Tool authors SHOULD update their documentation and code to use the new format.
• A migration guide SHOULD be provided to assist implementers in updating their tool names.

Reference Implementation

A reference implementation can be provided by updating the MCP core library to enforce the new tool name validation rules at registration time. Existing tools can be updated to provide aliases for their new conforming names, with warnings for deprecated formats. Example code and migration scripts can be included in the MCP repository.

Security Implications

None. Standardizing tool name format does not introduce new security risks.

SEP-990 Enable enterprise IdP policy controls during MCP OAuth flows

Final · Standards Track · Created 2025-06-04

• Status: Final
• Type: Standards Track
• Created: 2025-06-04
• Author(s): Aaron Parecki (@aaronpk)
• PR: #646
• Issue: #990

Abstract

This extension is designed to facilitate secure and interoperable authorization of MCP clients within corporate environments, leveraging existing enterprise identity infrastructure.

• For end users, this removes the need to manually connect and authorize the MCP Client to individual services within the organization.
• For enterprise admins, this enables visibility and control over which MCP Servers are able to be used within the organization.

How Has This Been Tested?

We have an end to end implementation of this here, and in-progress MCP implementations with some partners.

Breaking Changes

This is designed to augment the existing OAuth profile by providing an alternative when used under an enterprise IdP. MCP clients can opt in to this profile when necessary.

Additional Context

For more background on this problem, you can refer to my blog post about this here:

Enterprise-Ready MCP

I also presented this at the MCP Dev Summit in May.

A high level overview of the flow is below:

[!IMPORTANT] State: Ready to Review

SEP-991 Enable URL-based Client Registration using OAuth Client ID Metadata Documents

Final · Standards Track · Created 2025-07-07

• Status: Final
• Type: Standards Track
• Created: 2025-07-07
• Author(s): Paul Carleton (@pcarleton) Aaron Parecki (@aaronpk)
• Issue: #991

SEP: OAuth Client ID Metadata Documents for MCP

Abstract

This SEP proposes adopting OAuth Client ID Metadata Documents as specified in draft-parecki-oauth-client-id-metadata-document-03 as an additional client registration mechanism for the Model Context Protocol (MCP). This approach allows OAuth clients to use HTTPS URLs as client identifiers, where the URL points to a JSON document containing client metadata. This specifically addresses the common MCP scenario where servers and clients have no pre-existing relationship, enabling servers to trust clients without pre-coordination while maintaining full control over access policies.

Motivation

The Model Context Protocol currently supports two client registration approaches:

1. Pre-registration: Requires either client developers or users to manually register clients with each server
2. Dynamic Client Registration (DCR): Allows just-in-time registration by sending client metadata to a register endpoint on the Authorization server.

Both approaches have significant limitations for MCP's use case where clients frequently need to connect to servers they've never encountered before:

• Pre-registration by developers is impractical as servers may not exist when clients ship
• Pre-registration by users creates poor UX requiring manual credential management
• DCR requires servers to manage unbounded databases, handle expiration, and trust self-asserted metadata

The Target Use Case: No Pre-existing Relationship

This proposal specifically targets the common MCP scenario where:

• A user wants to connect a client to a server they've discovered
• The client developer has never heard of this server
• The server operator has never heard of this client
• Both parties need to establish trust without prior coordination

For scenarios with pre-existing relationships, pre-registration remains the optimal solution. However, MCP's value comes from its ability to connect arbitrary clients and servers, making the "no pre-existing relationship" case critical to address.

Relatedly, there are many more MCP servers than there are clients (similar to how there are many more web browsers than API's). A common scenario is an MCP server developer wanting to restrict usage to a set of clients they trust.

Key Innovation: Server-Controlled Trust Without Pre-Coordination

Client ID Metadata Documents enable a unique trust model where:

1. Servers can trust clients they've never seen before based on:

   • The HTTPS domain hosting the metadata
   • The metadata content itself
   • Domain reputation and security policies

2. Servers maintain full control through flexible policies:

   • Open Servers: Can accept any HTTPS client_id, enabling maximum interoperability
   • Protected Servers: Can restrict to trusted domains or specific clients

3. No client pre-coordination required:

   • Clients don't need to know about servers in advance
   • Clients just need to host their metadata document
   • Trust flows from the client's domain, not prior registration

Specification Changes

The change to the specification will be adding Client ID Metadata documents as a SHOULD, and changing DCR to a MAY, as we think that Client ID Metadata documents are a better default option for this scenario.

We will primarily rely on the text in the linked RFC, aiming not to repeat most of it. Below is a short version of what we'll need to specify.

Client Requirements

• Clients MUST host their metadata document at an HTTPS URL following RFC requirements
• The client_id URL MUST use "https" scheme and contain a path component
• Metadata documents MUST be valid JSON and include at minimum:
  • client_id: matching the document URL exactly
  • client_name: human-readable name for authorization prompts
  • redirect_uris: array of allowed redirect URIs
  • token_endpoint_auth_method: "none" for public clients

Note a client can use private_key_jwt for a token_endpoint_auth_method given the client metadata can provide public key information.

Server Requirements

• Servers SHOULD fetch metadata documents when encountering URL-formatted client_ids
• Servers MUST validate the fetched document contains matching client_id
• Servers SHOULD cache metadata respecting HTTP headers (max 24 hours recommended)
• Servers MUST validate redirect URIs match those in metadata document

Discovery

• Servers advertise support via OAuth metadata: client_id_metadata_document_supported: true
• Clients detect support and can fallback to DCR or pre-registration if unavailable

Example metadata document:

{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://app.example.com",
  "logo_uri": "https://app.example.com/logo.png",
  "redirect_uris": [
    "http://127.0.0.1:3000/callback",
    "http://localhost:3000/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Integration with Existing MCP Auth

This proposal adds Client ID Metadata Documents as a third registration option alongside pre-registration and DCR. Servers MAY support any combination of these approaches:

• Pre-registration remains unchanged
• DCR remains unchanged
• Client ID Metadata Documents are detected by URL-formatted client_ids, and server support is advertised in OAuth metadata.

Rationale

Why This Solves the "No Pre-existing Relationship" Problem

Unlike pre-registration which requires coordination, or DCR which requires servers to manage a registration database, Client ID Metadata Documents provide:

1. Verifiable Identity: The HTTPS URL serves as both identifier and trust anchor
2. No Coordination Needed: Clients publish metadata, servers consume it
3. Flexible Trust Policies: Servers decide their own trust criteria without requiring client changes
4. Stable Identifiers: Unlike DCR's ephemeral IDs, URLs are stable and auditable

Redirect URI Attestation

A key benefit of Client ID Metadata Documents is attestation of redirect URIs:

1. The metadata document cryptographically binds redirect URIs to the client identity via HTTPS
2. Servers can trust that redirect URIs in the metadata are controlled by the client - not attacker-supplied
3. This prevents redirect URI manipulation attacks common with self-asserted registration

Risks of this approach

Risk: Localhost URL Impersonation

A limitation of Client ID Metadata Documents is that they cannot prevent localhost URL impersonation by itself. An attacker can claim to be any client by:

1. Providing the legitimate client's metadata URL as their client_id
2. Binding to the same localhost port the legitimate client uses
3. Intercepting the authorization code when the user approves

This attack is concerning because the server sees the correct metadata document and the user sees the correct client name, making detection difficult.

Platform-specific attestations (iOS DeviceCheck, Android Play Integrity) could address this, but they're not universally available. This would work by a developer running a backend service that consumes the DeviceCheck / Play Integrity signatures and returns a JWT usable as the private_key_jwt authentication for the token_endpoint_auth_method.

A similar approach without requiring platform-specific attestations that still raises the cost of the attack is possible using JWKS and short-lived JWTs signed by a server-side component hosted by the client developer. This component could use attestation mechanisms other than platform-specific ones to attest to the clients identity, such as the client's standard login flow. Using short lived JWTs reduces the risk of credential compromise and replay, but does not eliminate it entirely - an attacker could still proxy requests to the legitimate client's signing endpoint.

Fully mitigating this risk is outside the scope of this proposal. This proposal has the same risks as DCR does in a localhost redirect scenario.

Servers SHOULD display additional warnings for localhost-only clients.

Risk: Server Side Request Forgery (SSRF)

The authorization server takes a URL as input from an unknown client, and then fetches that URL. A malicious client could use this to send non-metadata requests on behalf of the authorization server. An example would be sending a URL corresponding to a private administration endpoint that the authorization server has access to.

This can be prevented by validating the URL's and the IP's those URL's resolve to prior to initiating a fetch request.

Risk: Distributed Denial of Service (DDoS)

Similarly, an attacker could try to leverage a pool of authorization servers to perform a denial of service attack on a non-MCP server.

There is not any additional amplification for the fetch request (i.e. the bandwidth from the client to make the request roughly equals the bandwidth of the request sent to the target server), and each authorization server can aggressively cache the result of these metadata fetches, so it is unlikely to be an attractive DDoS vector.

Risk: Maturity of referenced specification

The RFC for Client ID Metadata documents is still a draft. It has been implemented by the platform Bluesky, but has not been ratified or very widely adopted outside of that, and may evolve over time. Our intention is to evolve and align with subsequent drafts and any final standard, while minimizing disruption and breakage with existing implementations.

This approach has the risk that there are implementation challenges or flaws in the protocol that have not surfaced yet. However, even though DCR has been ratified, and it also has a number of implementation challenges that developers are facing when trying to use it in an open ecosystem context like MCP. Those challenges are the motivation behind this proposal.

Risk: Client implementation burden, especially local clients

This specification requires an additional piece of infrastructure for clients, since they need to host a metadata file behind an HTTPS url. Without this specification, a client could be strictly a desktop application for example.

The burden of hosting this endpoint is expected to be low as hosting a static JSON file is fairly straightforward and most known clients have a webpage advertising their client or providing download links.

Risk: Fragmentation of authorization approaches

Authorization for MCP is already challenging to fully implement for clients and servers. Questions about how to do it correctly and best practices are some of the most common in the community. Adding another branch to the authorization flow means this could be even more complicated and fractured, meaning fewer developers succeed in following the specification, and the promise of compatibility and an open ecosystem suffers as a result.

This proposal intends to simplify the story for authorization server and resource server developers by providing a clearer mechanism to trust redirect URIs and less operational overhead. This proposal depends on that simplicity being clearly the better option for most folks, which will drive more adoption and end up being the most supported option. If we do not believe that it is clearly the better option, then we should not adopt this proposal.

This proposal also provides a unified mechanism for both open servers and servers that want to restrict which clients can be used. Alternatives to this proposal require that clients and servers implement different mechanisms for the open and protected use cases.

Alternatives Considered

1. Enhanced DCR with Software Statements: More complex, requires JWKS hosting and JWT signing
2. Mandatory Pre-registration: Poor developer and user experience for MCP's distributed ecosystem
3. Mutual TLS: Requires trusting a client certificate authority, impractical in an open ecosystem
4. Status Quo: Continues current pain points for server implementers

Client ID Metadata document is a strict improvement over DCR for the most common open-ecosystem use case. It can be further extended in the future to better support things like OS-level attestations and jwks_uri's.

Backward Compatibility

This proposal is fully backward compatible:

• Existing pre-registered clients continue working unchanged
• Existing DCR implementations continue working unchanged
• Servers can adopt Client ID Metadata Documents incrementally
• Clients can detect support and fall back to other methods

Prototype Implementation

A prototype implementation is available here demonstrating:

1. Client-side metadata document hosting
2. Server-side metadata fetching and validation
3. Integration with existing MCP OAuth flows
4. Proper error handling and fallback behavior

Security Implications

1. Phishing Prevention: Display client hostname prominently
2. SSRF Protection: Validate URLs, limit response size, timeout requests, rate limit outbound requests

Best Practices

• Only fetch client metadata after authenticating the user
• Implement rate limiting on outbound metadata fetches
• Consider additional warnings for new/unknown/localhost domains
• Log metadata fetch failures for monitoring

References

• draft-parecki-oauth-client-id-metadata-document-03
• OAuth 2.1
• RFC 7591 - OAuth 2.0 Dynamic Client Registration
• MCP Specification - Authorization
• Evolving OAuth Client Registration in the Model Context Protocol

SEP-994 Shared Communication Practices/Guidelines

Final · Process · Created 2025-07-17

• Status: Final
• Type: Process
• Created: 2025-07-17
• Author(s): @localden
• Issue: #994
• PR: #1002

Abstract

This SEP establishes the communication strategy and framework for the Model Context Protocol community. It defines the official channels for contributor communication, guidelines for their use, and processes for decision documentation.

Motivation

As the MCP community grows, clear communication guidelines are essential for:

• Consistency: Ensuring all contributors know where and how to communicate
• Transparency: Making project decisions visible and accessible
• Efficiency: Directing discussions to the most appropriate channels
• Security: Establishing proper processes for handling sensitive issues

Specification

Communication Channels

The MCP project uses three primary communication channels:

1. Discord: For real-time or ad-hoc discussions among contributors
2. GitHub Discussions: For structured, longer-form discussions
3. GitHub Issues: For actionable tasks, bug reports, and feature requests

Security-sensitive issues follow a separate process defined in SECURITY.md.

Discord Guidelines

The Discord server is designed for MCP contributors and is not intended for general MCP support.

Public Channels (Default)

• Open community engagement and collaborative development
• SDK and tooling development discussions
• Working and Interest Group discussions
• Community onboarding and contribution guidance
• Office hours and maintainer availability

Private Channels (Exceptions)

Private channels are reserved for:

• Security incidents (CVEs, protocol vulnerabilities)
• People matters (maintainer discussions, code of conduct)
• Coordination requiring immediate focused response

All technical and governance decisions must be documented publicly in GitHub.

GitHub Discussions

Used for structured, long-form discussion:

• Project roadmap planning
• Announcements and release communications
• Community polls and consensus-building
• Feature requests with context and rationale

GitHub Issues

Used for actionable items:

• Bug reports with reproducible steps
• Documentation improvements
• CI/CD and infrastructure issues
• Release tasks and milestone tracking

Decision Records

All MCP decisions are documented publicly:

• Technical decisions: GitHub Issues and SEPs
• Specification changes: Changelog on the MCP website
• Process changes: Community documentation
• Governance decisions: GitHub Issues and SEPs

Decision documentation includes:

• Decision makers
• Background context and motivation
• Options considered
• Rationale for chosen approach
• Implementation steps

Rationale

This framework balances openness with practicality:

• Public by default: Maximizes transparency and community participation
• Private when necessary: Protects security and personal matters
• Channel separation: Keeps discussions organized and searchable
• Documentation requirements: Ensures decisions are preserved and discoverable

Backward Compatibility

This SEP establishes new processes and does not affect existing protocol functionality.

Reference Implementation

The communication guidelines are published at: https://omcp.tech/community/communication

SEP-1024 MCP Client Security Requirements for Local Server Installation

Final · Standards Track · Created 2025-07-22

• Status: Final
• Type: Standards Track
• Created: 2025-07-22
• Author(s): Den Delimarsky
• Issue: #1024

Abstract

This SEP addresses critical security vulnerabilities in MCP client implementations that support one-click installation of local MCP servers. The current MCP specification lacks explicit security requirements for client-side installation flows, allowing malicious actors to execute arbitrary commands on user systems through crafted MCP server configurations distributed via links or social engineering.

This proposal establishes a best practice for MCP clients, requiring explicit user consent before executing any local server installation commands and complete command transparency.

Motivation

The existing MCP specification does not address client-side security concerns related to streamlined ("one-click") local server configuration. Current MCP clients that implement these configuration experiences create significant attack vectors:

1. Silent Command Execution: MCP clients can automatically execute embedded commands without user review or consent when installing local servers via one-click flows.

2. Lack of Visibility: Users have no insight into what commands are being executed on their systems, creating opportunities for data exfiltration, system compromise, and privilege escalation.

3. Social Engineering Vulnerabilities: Users become comfortable executing commands labeled as "MCP servers" without proper scrutiny, making them susceptible to malicious configurations.

4. Arbitrary Code Execution: Attackers can embed harmful commands in MCP server configurations and distribute them through legitimate channels (repositories, documentation, social media).

Visual Studio Code addressed this by implementing consent dialogs. Similarly, Cursor also supports a consent dialog for one-click local MCP server installation.

Without explicit security requirements in the specification, MCP client implementers may unknowingly create vulnerable installation flows, putting end users at risk of system compromise.

Specification

Client Security Requirements

MCP clients that support one-click local MCP server configuration MUST implement the following security controls:

Pre-Configuration Consent

Before executing any command to install or configure a local MCP server, the MCP client MUST:

1. Display a clear consent dialog that shows:

   • The exact command that will be executed, without truncation
   • All arguments and parameters
   • A clear warning that this operation may be potentially dangerous

2. Require explicit user approval through an affirmative action (button click, checkbox, etc.)

3. Provide an option for users to cancel the installation

4. Not proceed with installation if consent is denied or not provided

Rationale

Design Decisions

Mandatory Consent Dialogs: The requirement for explicit consent dialogs balances security with usability. While this adds friction to the MCP server configuration process, it prevents potential breaches from silent command execution.

Backward Compatibility

This SEP introduces new requirements for MCP client implementations but does not change the core MCP protocol or wire format.

Impact Assessment:

• Low Impact: Existing MCP servers and the core protocol remain unchanged
• Client Implementation Required: MCP clients must update their local server installation flows to comply with new security requirements
• User Experience Changes: Users will see consent dialogs where none existed before

Migration Path:

1. MCP clients can implement these changes in new versions without breaking existing functionality
2. Existing installed MCP servers continue to work normally
3. Only new installation flows require the consent mechanisms

No protocol-level backward compatibility issues exist, as this SEP addresses client behavior rather than the MCP wire protocol.

Reference Implementation

N/A

Security Implications

Security Benefits

This SEP directly addresses:

• Arbitrary Code Execution: Prevents silent execution of malicious commands
• Social Engineering: Forces users to consciously review commands before execution
• Supply Chain Attacks: Creates visibility into MCP server installation commands
• Privilege Escalation: Users can identify and reject commands requesting elevated privileges

Residual Risks

Even with these controls, risks remain:

• User Override: Users may approve malicious commands despite warnings
• Sophisticated Obfuscation: Advanced attackers may craft commands that appear legitimate
• Implementation Gaps: Clients may implement controls incorrectly

Risk Mitigation

These residual risks are addressed through:

• Clear warning language in consent dialogs
• Recommendation for additional security layers (sandboxing, signatures)
• Ongoing security research and community awareness

SEP-1034 Support default values for all primitive types in elicitation schemas

Final · Standards Track · Created 2025-07-22

• Status: Final
• Type: Standards Track
• Created: 2025-07-22
• Author(s): Tapan Chugh (chugh.tapan@gmail.com)
• Issue: #1034

Abstract

This SEP recommends adding support for default values to all primitive types in the MCP elicitation schema (StringSchema, NumberSchema, and EnumSchema), extending the existing support that only covers BooleanSchema.

Motivation

Elicitations in MCP offer a way to mitigate complex API designs: tools can request information on-demand rather than resorting to convoluted parameter handling. The challenge however is that users must manually enter obvious information that could be pre-populated for more natural interactions. Currently, only BooleanSchema supports default values in elicitation requests. This limitation prevents servers from providing sensible defaults for text inputs, numbers, and enum selections leading to more user overhead.

Real-World Example

Consider implementing an email reply function. Without elicitation, the tool becomes unwieldy:

def reply_to_email_thread(
    thread_id: str,
    content: str,
    recipient_list: List[str] = [],
    cc_list: List[str] = []
) -> None:
    # Ambiguity: Does empty list mean "no recipients" or "use defaults"?
    # Complex logic needed to handle different combinations

With elicitation, the tool signature itself can be much simpler

def reply_to_email_thread(
    thread_id: str,
    content: Optional[str] = ""
) -> None:
    # Code can lookup the participants from the original thread
    # and prepare an elicitation request with the defaults setup

const response = await client.request("elicitation/create", {
  message: "Configure email reply",
  requestedSchema: {
    type: "object",
    properties: {
      recipients: {
        type: "string",
        title: "Recipients",
        default: "alice@company.com, bob@company.com"  // Pre-filled
      },
      cc: {
        type: "string",
        title: "CC",
        default: "john@company.com"  // Pre-filled
      },
      content: {
        type: "string",
        title: "Message"
        default: "" // If provided in the tool above
      }
    }
  }
});

Implementation

A working implementation demonstrating clients require minimal changes to display defaults (~10 lines of code):

• Implementation PR: https://github.com/chughtapan/fast-agent/pull/2
• A demo with the above email reply workflow: https://asciinema.org/a/X7aQZjT2B5jVwn9dJ9sqQVkOM

Specification

Schema Changes

Extend the elicitation primitive schemas to include optional default values:

export interface StringSchema {
  type: "string";
  title?: string;
  description?: string;
  minLength?: number;
  maxLength?: number;
  format?: "email" | "uri" | "date" | "date-time";
  default?: string; // NEW
}

export interface NumberSchema {
  type: "number" | "integer";
  title?: string;
  description?: string;
  minimum?: number;
  maximum?: number;
  default?: number; // NEW
}

export interface EnumSchema {
  type: "string";
  title?: string;
  description?: string;
  enum: string[];
  enumNames?: string[];
  default?: string; // NEW - must be one of enum values
}

// BooleanSchema already has default?: boolean

Behavior

1. The default field is optional, maintaining full backward compatibility
2. Default values must match the schema type
3. For EnumSchema, the default must be one of the valid enum values
4. Clients that support defaults SHOULD pre-populate form fields. Clients that don't support defaults MAY ignore the field entirely.

Rationale

1. The high-level rationale is to follow the precedent set by BooleanSchema rather than creating new mechanisms.
2. Making defaults optional ensures backward compatibility.
3. This maintains the high-level intuition of keeping the client implementation simple.

Alternatives Considered

1. Server-side Templates: Servers could maintain templates separately, but this adds complexity
2. New Request Type: A separate request type for forms with defaults would fragment the API
3. Required Defaults: Making defaults required would break existing implementations

Backwards Compatibility

This change is fully backward compatible with no breaking changes. Clients that don't understand defaults will ignore them, and existing elicitation requests continue to work unchanged. Clients can adopt default support at their own pace

Security Implications

No new security concerns:

1. No Sensitive Data: The existing guidance against requesting sensitive information still applies
2. Client Control: Clients retain full control over what data is sent to servers
3. User Visibility: Default values are visible to users who can modify them before submission

SEP-1036 URL Mode Elicitation for secure out-of-band interactions

Final · Standards Track · Created 2025-07-22

• Status: Final
• Type: Standards Track
• Created: 2025-07-22
• Author(s): Nate Barbettini (@nbarbettini) and Wils Dawson (@wdawson)
• Issue: #1036

Abstract

This SEP introduces a new url mode for the existing elicitation client capability, enabling secure out-of-band interactions that bypass the MCP client. URL mode elicitation addresses sensitive use cases that form mode elicitation cannot, such as gathering sensitive credentials, performing OAuth flows for external (3rd-party) authorization, and handling payments, without exposing sensitive data to the MCP client. By directing users to trusted URLs in their browser, this mode maintains security boundaries while enabling rich integrations with third-party services.

Motivation

The current MCP specification (2025-06-18) provides an elicitation mechanism for gathering non-sensitive information from users through structured, in-band requests (most commonly imagined as the MCP client rendering a form to collect data from the end-user). However, several critical use cases require interactions that must not pass through the MCP client:

1. Sensitive data collection: API keys, passwords, and other credentials must never transit through intermediary systems.
2. External authorization: MCP servers often need to access third-party APIs on behalf of users. The MCP authorization specification only covers client-to-server authorization, not server-to-third-party authorization. The Security Best Practices document explicitly forbids token passthrough, requiring a secure mechanism for external (3rd-party) OAuth flows. This was a particularly important motivating factor emerging from discussions in #234 and #284.
3. Payment and Subscription Flows: Financial transactions require PCI compliance and secure payment processing that cannot be achieved through in-band data collection.

Without a standardized mechanism for these interactions, MCP servers must resort to non-standard workarounds or insecure practices like requesting API keys through in-band, form-style elicitation. This SEP addresses these gaps by introducing a URL elicitation mode that leverages established web security patterns to handle sensitive interactions securely.

URL elicitation is fundamentally different from MCP authorization. URL elicitation is not for authorizing the MCP client's access to the MCP server (that's handled directly by MCP authorization). Instead, it's used when the MCP server needs to obtain sensitive information or third-party authorization on behalf of the user. The MCP client's bearer token remains unchanged, and the client's only responsibility is to provide the user with context about the elicitation URL the server wants them to open.

Specification

Overview

Elicitation is updated to support two modes:

• Form mode (in-band): Servers can request structured data from users with optional JSON schemas to validate responses (no change here, other than adding a name to the existing capability)
• URL mode (out-of-band): Servers can direct users to external URLs for sensitive interactions that must not pass through the MCP client

Capabilities

Clients that support elicitation MUST declare the elicitation capability during initialization:

{
  "capabilities": {
    "elicitation": {
      "form": {},
      "url": {}
    }
  }
}

For backwards compatibility, an empty capabilities object is equivalent to declaring support for form mode only:

{
  "capabilities": {
    "elicitation": {},
  },
}

Clients declaring the elicitation capability MUST support at least one mode (form or url).

Form Elicitation Requests

The only change from the existing specification is the addition of a mode field in the elicitation/create request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "elicitation/create",
  "params": {
    "mode": "form", // New field
    "message": "Please provide your GitHub username",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      },
      "required": ["name"]
    }
  }
}

URL Elicitation Requests

URL elicitation requests MUST specify mode: "url" and include these parameters:

Example: OAuth Authorization Flow

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "elicitation/create",
  "params": {
    "mode": "url",
    "elicitationId": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://github.com/login/oauth/authorize?client_id=abc123&state=xyz789&scope=repo",
    "message": "Please authorize access to your GitHub repositories to continue."
  }
}

Response Actions

URL elicitation responses use the same three-action model as form elicitation:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "action": "accept" // or "decline" or "cancel"
  }
}

The response with action: "accept" indicates that the user has consented to the interaction. The interaction occurs out of band and the client is not aware of the outcome unless the server sends a completion notification.

Completion Notifications

Servers SHOULD send a notifications/elicitation/complete notification when an out-of-band interaction started by URL mode elicitation is completed. This allows clients to react programmatically if appropriate.

• The notification MUST only be sent to the client that initiated the elicitation request.
• The notification MUST include the elicitationId established in the original elicitation/create request.
• Clients MUST ignore notifications referencing unknown or already-completed IDs.
• If a completion notification never arrives, clients SHOULD provide a manual way for the user to continue the interaction.

Clients MAY use the notification to automatically retry requests that received a URL elicitation required error, update the user interface, or otherwise continue an interaction. However, because delivery of the notification is not guaranteed, clients must not wait indefinitely for a notification from the server.

{
  "jsonrpc": "2.0",
  "method": "notifications/elicitation/complete",
  "params": {
    "elicitationId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

URL Elicitation Required Error

When a request cannot be processed until an elicitation is completed, the server MAY return a URLElicitationRequiredError (code -32042) to indicate that a URL mode elicitation is required. The server MUST NOT return this error except when URL mode elicitation is required by the user interaction.

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32042,
    "message": "This request requires more information.",
    "data": {
      "elicitations": [
        {
          "mode": "url",
          "elicitationId": "550e8400-e29b-41d4-a716-446655440000",
          "url": "https://oauth.example.com/authorize?client_id=abc123&response_type=code&...",
          "message": "Authorization is required to access your Example Co files."
        }
      ]
    }
  }
}

Any elicitations returned in the error MUST be URL mode elicitations and include an elicitationId.

Returning a URLElicitationRequiredError is equivalent to sending an elicitation/create request. The server may return an error (instead of sending a separate elicitation/create request) as an affordance to the client to make it clear that a particular elicitation is directly related to a failed client request.

The client must treat URLElicitationRequiredError responses as equivalent to elicitation/create requests. Clients may automatically retry the failed request after the elicitation is completed successfully, for example after receiving a completion notification.

Rationale

Design Decisions

Why extend elicitation instead of creating a new mechanism?

Initially, we considered creating a separate mechanism for out-of-band interactions (discussed in #475). However, after discussions with the MCP maintainers, we decided to extend the existing elicitation specification because:

1. Both mechanisms serve the same fundamental purpose: gathering information from users
2. Having two similar-but-separate mechanisms for the same purpose is confusing and error-prone
3. The mode parameter cleanly separates the two interaction patterns

Why can't the client perform the interaction itself?

It is tempting to suggest that the MCP client should perform the interaction itself, e.g. act as an OAuth client to a third-party authorization server. However, there are several reasons why this is not a good idea:

• If the MCP client obtains user tokens from a third-party authorization server, the MCP server becomes a token passthrough server, which is explicitly forbidden.
• Similarly, for payment-type flows, the MCP client would need to perform PCI-compliant payment processing, which is not a desired requirement for MCP clients.

Why doesn't the server block (wait) on the elicitation to complete?

URL mode elicitation requests are asynchronous or "disconnected" flows by design, because the kinds of interactions they enable are inherently asynchronous. Payment flows, external authorization, etc. can take minutes or more to complete, and in some cases never complete at all (if abandoned by the end-user).

Why disallow URLs in form mode?

Being very explicit about when URLs can (and cannot) be sent in an elicitation request improves the client's security posture. By clearly stating in the spec that URLs are only allowed in the url field of a URL mode elicitation request, client implementers can implement UX patterns that are consistent with the security model. For example, a client could refuse to render a URL as a clickable hyperlink in a form mode elicitation request, reducing the likelihood of a user clicking on a malicious URL sent by a malicious server.

Alternative Approaches Considered

1. Token Passthrough: Simply passing the MCP client's token to external services was rejected due to security concerns documented in the Security Best Practices. Having the MCP client obtain additional tokens and passing those to the MCP server was rejected for the same reason.

2. OAuth-specific Capability: Creating a capability specific to external (3rd-party) authorization with OAuth was considered, but rejected in favor of the more general URL mode elicitation approach that supports multiple use cases.

Community Feedback

This proposal incorporates extensive community feedback from discussions in #475, #234, and #284, as well as the #auth-wg working group on Discord. The community identified the need for:

• Secure credential collection without client exposure
• External authorization patterns separate from MCP authorization
• Payment and subscription flow support
• Clear security boundaries and trust models

Backward Compatibility

This SEP introduces the following breaking changes:

1. Capability Declaration: Clients must now specify which elicitation modes they support:

   {
     "capabilities": {
       "elicitation": {
         "form": {},
         "url": {}
       }
     }
   }
   

   Previously, clients only declared "elicitation": {} without mode specification.

2. Mode Parameter: All elicitation/create requests must now include a mode parameter ("form" or "url").

Migration Path

To ease migration:

• Servers SHOULD check client capabilities before sending mode-specific requests
• Clients MAY initially support only form mode to maintain compatibility
• Existing form elicitation implementations continue to work with the addition of the mode parameter

Reference Implementation

Client/server implementation in TypeScript: feat/url-elicitation

Explainer video: https://drive.google.com/file/d/1llCFS9wmkK_RUgi5B-zHfUUgy-CNb0n0/view?usp=sharing

Security Implications

This SEP introduces several security considerations:

URL Security Requirements

1. SSRF Prevention: Clients must validate URLs to prevent Server-Side Request Forgery attacks
2. Protocol Restrictions: Only HTTPS URLs are allowed for URL elicitation
3. Domain Validation: Clients must clearly display target domains to users

Trust Boundaries

URL elicitation explicitly creates clear trust boundaries:

• The MCP client never sees sensitive data obtained by the MCP server via URL elicitation
• The MCP server must independently verify user identity
• Third-party services interact directly with users through secure browser contexts

Identity Verification

Servers must verify that the user completing a URL elicitation is the same user who initiated the request. Verifying the identity of the user must not rely on untrusted input (e.g. user input) from the client.

Implementation Requirements

1. Clients must:

   • Use secure browser contexts that prevent inspection of user inputs
   • Validate URLs for SSRF protection
   • Obtain explicit user consent before opening URLs
   • Clearly display target domains

2. Servers must:

   • Bind elicitation state to authenticated user sessions
   • Verify user identity at the beginning and end of a URL elicitation flow
   • Implement appropriate rate limiting

3. Both parties should:

   • Log security events for audit purposes
   • Implement timeout mechanisms for elicitation requests
   • Provide clear error messages for security failures

Relationship to Existing Security Measures

This proposal builds upon and complements existing MCP security measures:

• Works within the existing MCP authorization framework (MCP authorization is not affected by this proposal)
• Follows Security Best Practices regarding token handling
• Maintains separation of concerns between client-server and server-third-party authorization

SEP-1046 Support OAuth client credentials flow in authorization

Final · Standards Track · Created 2025-07-23

• Status: Final
• Type: Standards Track
• Created: 2025-07-23
• Author(s): Darin McAdams (@D-McAdams )
• Issue: #1046

Preamble

Title: Support OAuth client credentials flow in authorization Author: Darin McAdams (@D-McAdams ) Status: Proposal Type: Standards Track Created: 2025-07-23

Abstract

Recommends adding the OAuth client credentials flow to the authorization spec to enable machine-to-machine scenarios.

Motivation

The original authorization spec mentioned the client credentials flow, but it was dropped in subsequent revisions. Therefore, the spec is currently silent on how to solve machine-to-machine scenarios where an end-user is unavailable for interactive authorization.

Specification

The authorization spec would be amended to list the OAuth client credentials flow as being allowed. Adhering to the patterns established by OAuth 2.1, the specification would RECOMMEND the use of asymmetric methods defined in RFC 753 (JWT Assertions), but also allow client secrets.

As guidance to implementors, the spec overview would also be updated to describe the different flows and when each is applicable. In addition, to address a common question, the spec would be updated to indicate that implementors may implement other authorization scenarios beyond what's defined; emphasizing that the specification defines the baseline requirements.

Rationale

To maximize interoperability (and minimize SDK complexity), this change would intentionally constrain the client credentials flow to two options:

1. JWT Assertions as per RFC 7523 (RECOMMENDED)
2. Client Secrets via HTTP Basic authentication (Allowed for maximum compatibility with existing systems)

Other options, such as mTLS, are not included.

While the spec encourages the use of RFC 7523 (JWT Assertions), it does not yet specify how to populate the JWT contents nor how to discover the client's JWKS URI to validate the JWT. In future iterations of the spec, it will be beneficial to do so. However, this was currently left unspecified pending maturity of other RFCs that can define these profiles. The other RFCs include WIMSE Headless JWT Authentication (for specifying JWT contents) and Client ID Metadata (for specifying the JWKS URI). This revision intentionally leaves extensibility for these future profiles. As a practical matter, this means implementers needing to ship solutions ASAP will most likely use client secrets which are widely supported today, whereas the JWT Assertion pattern represents the longer-term direction.

Backward Compatibility

This change is fully backward compatible. It introduces a new authorization flow, but does not alter the existing flows.

Security Implications

The specification refers to the existing OAuth security guidance.

SEP-1302 Formalize Working Groups and Interest Groups in MCP Governance

Final · Standards Track · Created 2025-08-05

• Status: Final
• Type: Standards Track
• Created: 2025-08-05
• Author(s): tadasant
• Issue: #1302

PR: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1350

Abstract

A short (~200 word) description of the technical issue being addressed.

In SEP-994, we introduced a notion of “Working Groups” and “Interest Groups” that facilitate MCP sub-communities for discussion and collaboration. This SEP aims to formally define those two terms: what they are meant to achieve, how groups can be created, how they are governed, and how they can be retired.

Interest Groups work to define problems that MCP should solve by facilitating discussions, while Working Groups push forward specific solutions by collaboratively producing deliverables (in the form of SEPs or community-owned implementations of the specification). Interest Group input is a welcome (but not required) justification for creation of a Working Group. Interest Group or Working Group input is collectively a welcome (but not required) input into a SEP.

Motivation

The motivation should clearly explain why the existing protocol specification is inadequate to address the problem that the SEP solves.

The community has already been self-organizing into several disparate systems for these collaborative groups:

• The Steering group has had a long-standing practice of managing a handful of collaborative groups through Discord channels (e.g. security, auth, agents). See bottom of MAINTAINERS.md.
• The “CWG Discord” has had a semi-formal process for pushing equivalent grassroots initiatives, mostly in pursuit of creating artifacts for SEP consideration (e.g. hosting, UI, tool-interfaces, search-tools)

With SEP-994 resulting in the merging of the Discord communities, we have a need to:

• Merge the existing initiatives into one unified approach, so when we reference “working group” or “interest group”, everyone knows what that means and what kind of weight the reference might carry
• Standardize a process around the creation (and eventual retirement) of such groups
• Properly distinguish between “working” and “interest” groups; the CWG experience has shown two very different motivations for starting a group worth treating with different expectations and lifecycle. Put succinctly, “interest” groups are about brainstorming possible problems, and “working” groups are about pushing forward specific solutions.

These groups exist to:

• Facilitate high signal spaces for discussion such that those opting into notifications and meetings feel most content is relevant to them and they can meaningfully contribute their experience and learn from others
• Create norms, expectations, and single points of involved leadership around making collaborative progress towards concrete deliverables that help evolve MCP

It will also form the foundation for cross-group initiatives, such as maintaining a calendar of live meetings.

Specification

The technical specification should describe the syntax and semantics of any new protocol feature. The specification should be detailed enough to allow competing, interoperable implementations. A PR with the changes to the specification should be provided.

Interest Groups (IG) [Problems]

Goal: facilitate discussion and knowledge-sharing among MCP community members with similar interests surrounding some MCP sub-topic or context. The focus is on collecting problems that may or may not be worth solving with SEPs or other community artifacts.

Expectations:

• At least one substantive thread / conversation per month
• AND/OR a live meeting attended by 3+ unaffiliated individuals

Examples:

• Security in MCP (currently: #security)
• Auth in MCP (currently: #auth)
• Using MCP in an internal enterprise setting (currently: #enterprise-wg)
• Tooling and practices surrounding hosting MCP servers (currently: #hosting-wg)
• Tooling and practices surrounding implementing MCP clients (currently: #client-implementors)

Lifecycle:

• Creation begins by filling out a template in #wg-ig-group-creation Discord channel
• A community moderator will review and call for a vote in the (private) #community-moderators Discord channel. Majority positive vote by members over a 72h period approves creation of the group. Can be reversed at any time (e.g. after more input comes in). Core and lead maintainers can veto.
• Facilitator(s) and Maintainer(s) responsible for organizing IG into meeting expectations
  • Facilitator is an informal role responsible for shepherding or speaking for a group
  • Maintainer is an official representative from the MCP steering group (not required for every group to have this)
• IG is retired only when community moderators or core+ maintainers decide it is not meeting expectations
  • This means successful IG’s will live on in perpetuity

Creation Template:

• Facilitator(s)
• Maintainer(s) (optional)
• Flag potential overlap with other IG’s
• How this IG differentiates itself from the related IG’s
• First topic you want to discuss

There is no requirement to be part of an IG to start a WG, or even to start a SEP. However, forming consensus in IG’s to support justifying the creation of a WG is often a good idea. Similarly, citing IG or WG support of a SEP helps the SEP as well.

Working Groups (WG) [Solutions]

Goal: facilitate MCP community collaboration on a specific SEP, themed series of SEPs, or officially endorsed Project.

Expectations:

• Minimum monthly progress towards at least one SEP or spec-related implementation OR holds maintenance responsibilities for a Project
• Facilitator(s) is/are responsible for fielding status update requests by community moderators or maintainers

Examples:

• Registry
• Inspector
• Tool Filtering
• Server Identity

Lifecycle:

• Creation begins by filling out a template in #wg-ig-group-creation Discord channel
• A community moderator will review and call for a vote in the (private) #community-moderators Discord channel. Majority positive vote by members over a 72h period approves creation of the group. Can be reversed at any time (e.g. after more input comes in). Core and lead maintainers can veto.
• Facilitator(s) and Maintainer(s) responsible for organizing WG into meeting expectations
  • Facilitator is an informal role responsible for shepherding or speaking for a group
  • Maintainer is an official representative from the MCP steering group (not required for every group to have this)
• WG is retired when either:
  • Community moderators or core+ maintainers decide it is not meeting expectations
  • The WG does not have a WIP Issue/PR for at least a month, or has completed all Issues/PRs it intends to pursue.

Creation Template:

• Facilitator(s)
• Maintainer(s) (optional)
• Explanation of interest/use cases (ideally from an IG but can come from anywhere)
• First Issue/PR/SEP you intend to procure

WG/IG Facilitators

A “Facilitator” role in a WG or IG does not result in a maintainership role across the MCP organization. It is an informal role into which anyone can self-nominate, responsible for helping shepherd discussions and collaboration within the group.

Core Maintainers reserve the right to modify the list of Facilitators and Maintainers for any WG/IG at any time.

PR for the changes to our documentation we'd want to enact this SEP: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1350

Rationale

The rationale explains why particular design decisions were made. It should describe alternate designs that were considered and related work. The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.

The design above comes from experience in facilitating the creation of + observing the behavior of informal “Community Working Groups” in the CWG Discord, and leading one of / participating in / observing the “Steering Committee Working Groups”. While the Steering WG’s were usually informally created by Lead Maintainers, the CWG Discord had a lightweight WG-creation process that involved similar steps to the proposal above (community members would propose WG’s in #working-group-ideation, and moderators would create channels from that collaboration).

As precedent, the WG and IG concepts here are similar to W3C’s notion of Working Groups and Interest Groups.

Considerations

In proposing the WG/IG design, we took the following into consideration:

Clear on-ramp for community involvement

A very common question for folks looking to invest in the MCP ecosystem is, "how do I get involved?"

These IG and WG abstractions help provide an elegant on-ramp:

1. Join the Discord, follow the conversation in IGs relevant to you. Attend live calls. Participate.
2. Offer to facilitate calls. Contribute your use cases in SEP proposals and other work.
3. When you're comfortable contributing to deliverables, jump in to contribute to WG work.
4. Do this for a period of time, get noticed by WG maintainers to get nominated as a new maintainer.

Minimal changes to existing governance structure

We did not want this change to introduce new elections, appointments, or other notions of leadership. We leverage community moderators to thumbs-up creation of new groups, allow core maintainers to veto, maintainership status stays unchanged, and the notion of "facilitator" is new but self-nominated, so does not introduce any new governance processes.

Alignment with current status quo

There is a clear "migration" path for the existing "CWG" working groups and Steering working groups - just a matter of sorting out what is "working" vs. "interest", but functionally this proposal stays out of the way of changing anything that has been working within each group's existing structure.

Nature of requests for gathering spaces

It has been clear from the requests to CWG that some groups form with a motivation to collaborate on some deliverable (e.g. search-tools), and others form due to common interests and a want for sub-community but not yet specific deliverables (e.g. enterprise). Hence, we separate the motivations into Working Groups vs. Interest Groups.

Potential for overlap in scope

In the requests for new group spaces, it is sometimes non-obvious why a new one needs to exist. For example, the stated motivation for enterprise at times sounded like it may just be another flavor of hosting. We ultimately settled on a distinction that made it clear one was not a direct subset of the other, but the concern of making clear boundaries between groups (and letting community moderators / maintainers centralize the decision-making around "what are the right layers of abstraction") is what led to the questions in the creation templates around e.g. "flag potential overlap with other IG’s".

Path to retiring stale groups

Many working groups in the old CWG and Steering models have gone stale since creation. They serve no real purpose and should be retired. For this, we introduce the formal concept of facilitators and optional maintainers in groups; and the community moderator right to retire them. By having at least informal leadership in place per group, a moderator can easily make the decision to retire a group if everyone is in agreement to proceed.

Alternatives Considered

Hierarchy between IGs and WGs

We considered requiring that WGs be owned or spawned by a "sponsor" IG, for the purpose of more clearly exhibiting a progression of ideas to the community; but decided against this requiring to avoid adding a new layer of governance and alignment with how the less formal groups works today.

A single WG concept (instead of both WG and IG)

There has been regular tension in both CWG and the Steering group around the question of "is XYZ really a working group? how will maintainership work?" By making IG's explicitly discussion-oriented and maintainership involvement optional, we create a space to drive those discussions without requiring some formal expectation of deliverables like we might in a well-defined WG.

Free-for-all WG/IG creation process

While very community-driven, the concern of group overlap would quickly fragment the conversations and collaboration to an untenable level; we need a centralized point of discernment here.

Backward Compatibility

All SEPs that introduce backward incompatibilities must include a section describing these incompatibilities and their severity. The SEP must explain how the author proposes to deal with these incompatibilities.

There is no major change suggested in the day to day of existing groups - the expectations laid out of IGs and WGs are easily met by existing active groups as long as they keep doing as they are doing.

A migration path for all groups is laid out below.

Reference Implementation

The reference implementation must be completed before any SEP is given status “Final”, but it need not be completed before the SEP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of “rough consensus and running code” is still useful when it comes to resolving many discussions of protocol details.

The below is the suggested migration path for each group. "Migration" just involves acknowledgement of this SEP and the expectations of each group, plus methodology for possible eventual retirement (or immediate retirement, in some cases).

After this SEP is approved, we can ping each of the groups to confirm they are on board with the migration plan.

Steering Working Groups

• All official SDK groups --> Working Groups
• Registry --> Working Group
• Documentation --> Working Group
• Inspector --> Working Group
• Auth --> Interest Group + some WGs: client-registration, improve-devx, profiles, tool-scopes
• Agents --> Working Group [Long Running / Async Tool Calls; unless we want an Agents IG on top of that?]
• Connection Lifetime --> Retire
• Streaming --> Retire
• Spec Compliance --> Retire (good idea but stale; would be good for someone to spearhead a new Working Group)
• Security --> Interest Group (perhaps with Security Best Practices WG?)
• Transports --> Interest Group
• Server Identity --> Working Group
• Governance --> Working Group (or Retire if no more work here?)

Community Working Groups

• agent-comms --> Retire
• enterprise --> Interest Group (request a proposal to start)
• hosting --> Interest Group (request a proposal to start)
• load-balancing --> Retire
• model-awareness --> Working Group (request a proposal to start)
• search-tools (tool-filtering) --> Working Group
• server-identity --> merge with Steering equivalent
• security --> merge with Steering equivalent
• server-identity --> merge with Steering equivalent
• tool-interfaces --> Retire
• ui --> Interest Group
• schema-validation --> Retire (same as Steering equivalent)

SEP-1303 Input Validation Errors as Tool Execution Errors

Final · Standards Track · Created 2025-08-05

• Status: Final
• Type: Standards Track
• Created: 2025-08-05
• Author(s): @fredericbarthelet
• Issue: #1303

Abstract

This SEP proposes treating tools input validation errors as Tool Execution Errors rather than Protocol Errors. This change would enable language models to receive validation error feedback in their context window, allowing them to self-correct and successfully complete tasks without human intervention, significantly improving task completion rate.

Motivation

Language models can learn from tool input validation error messages and retry a tools/call with corrected parameters accordingly, but only if they receive the error feedback in their context window. Protocol Errors are catch at the application level by the MCP Client. Only Tool Execution Errors are forwarded back to the model as JSON-RPC responses. With the current specifications, models cannot see these error messages and thus cannot self-correct, leading to repeated failures and poor user experiences.

Problem Statement

Consider a flight booking tool that validates departure dates using the following zod validation schema:

departureDate: z.string()
  .regex(/^\d{2}\/\d{2}\/\d{4}$/, "date must be in dd/mm/yyyy format")
  .superRefine((dateStr, ctx) => {
    const date = parseDateFr(dateStr);
    if (date.getTime() < Date.now()) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message:
          "Dates must be in the future. Current date is " +
          formatDateFr(new Date()),
      });
    }
    return true;
  })
  .describe("Departure date in dd/mm/yyyy format");

Tool expected input JSON schema can only describe the regex statement. The actual programmatic check that the date is in the past cannot be expressed here as JSON schema. Even when a model provides a syntactically correct date that passes JSON schema validation, there is no guarantee it will be in the future. When a validation error is raised and returned as a Protocol Error:

1. The model doesn't receive the error message explaining why the date was rejected
2. The model repeats the same mistake multiple times (e.g., Cursor typically consistently sends dates in 2024 when the user only specify day and month or relative date and repeats the same tools/call request 3 times without getting any information as to why the tools call fails)
3. The task fails despite the model being capable of correcting itself if given proper feedback
4. Users experience frustration and must manually intervene

Benefits of This Proposal

1. Higher Task Completion Rates: Models can self-correct validation errors without human intervention
2. Better User Experience: Reduced failures and faster task completion
3. Leverages Model Capabilities: Modern LLMs excel at understanding and responding to error messages
4. Reduced API Calls: Fewer retry attempts as models correct themselves on the first error

Specification

Current Behavior

The tool errors specification currently provides ambiguous guidance:

• "Invalid arguments" should be treated as Protocol Error
• "Invalid input data" should be treated as Tool Execution Error

This ambiguity leads to inconsistent implementations where valuable error feedback is lost.

Proposed Change

Clarify the specification with the following changes:

1. Removes the "invalid argument" category from Protocol Errors.
2. Tool Execution Errors should be used for all tool argument validation failures (merging invalid argument and invalid input data under a new input validation errors category)

Specification Text Changes

Update the error handling section to include:

## Error Handling

Tools use two error reporting mechanisms:

1. **Protocol Errors**: Standard JSON-RPC errors for issues like:

   - Unknown tools
   - Server errors

2. **Tool Execution Errors**: Reported in tool results with `isError: true`:
   - API failures
   - Input validation errors
   - Business logic errors

Implementation

Before (Protocol Error)

// Model submits past date
request: {
  ...
  method: "tools/call",
  params: {
    name: "book_flight",
    arguments: {
      departureDate: "12/12/2024"  // Past date
    }
  }
}

// Server returns Protocol Error
response: {
  ...
  error: {
    code: -32602,
    message: "Invalid params"
  }
}

// Model retries blindly with another past date
// This cycle repeats until failure

After (Tool Execution Error)

// Model submits past date
request: {
  ...
  method: "tools/call",
  params: {
    name: "book_flight",
    arguments: {
      departureDate: "12/12/2024"  // Past date
    }
  }
}

// Server returns Tool Execution Error (visible to model)
response: {
  ...
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Dates must be in the future. Current date is 08/08/2025"
      }
    ],
    "isError": true
  }
}

// Model understands the error and corrects itself
request: {
  method: "tools/call",
  params: {
    name: "book_flight",
    arguments: {
      departureDate: "12/12/2025"  // Future date
    }
  }
}

Backwards Compatibility

This change is backwards compatible as it:

• Does not alter the protocol structure
• Only clarifies existing ambiguous behavior
• Maintains all existing error types and formats
• Improves behavior without breaking existing implementations

Servers implementing the clarified behavior will provide better model self-recovery while continuing to work with all existing clients.

References

• MCP Tools Error Handling Specification
• Better MCP tools/call Error Responses: Help Your AI Recover Gracefully
• Related Issue: https://github.com/modelcontextprotocol/typescript-sdk/pull/824

SEP-1319 Decouple Request Payload from RPC Methods Definition

Final · Standards Track · Created 2025-08-08

• Status: Final
• Type: Standards Track
• Created: 2025-08-08
• Author(s): @kurtisvg
• Issue: #1319

Abstract

This SEP proposes a structural refactoring of the Model Context Protocol (MCP) specification. The core change is to define payload of requests (e.g., CallToolRequest) as independent definitions and have the RPC method definitions refer to these models. This decouples the definition of the data payload from the definition of the remote procedure that transports it, leading to a clearer, more modular, and more maintainable specification.

Motivation

The current MCP specification tightly couples the data payload of a request with the JSON-RPC method that transports it. This design presents several challenges:

• Reduced Clarity: It forces developers to mentally parse the JSON-RPC transport structure just to understand the core data being exchanged. This increases cognitive load and makes the specification difficult to read and implement correctly.
• Hindered Maintainability: Defining data structures inline prevents their reuse across different methods, leading to redundancy and making future updates to the protocol more complex and error-prone.
• Tightly Coupled to JSON-RPC: Most critically, this tight coupling to JSON-RPC is the primary blocker for defining bindings for other transport protocols. To support transports like gRPC (which is currently a popular ask from the community), a transport-agnostic definition of its request and response messages. The current structure makes this practically impossible.

By refactoring the specification to separate the data model (the "what") from the RPC method (the "how"), this proposal will create a clearer, more modular specification. This change will immediately improve the developer experience and, most importantly, pave the way for the future evolution of MCP across multiple transports.

Specification

The proposal introduces the following principle: All data structures used as parameters (params) or results (result) for RPC methods should be defined as standalone, named schemas. The RPC method definitions will then use references to these schemas.

Current Approach (Inline Definition):

The RPC method definition contains the full structure of its parameters and results.

export interface CallToolRequest extends Request {
  method: "tools/call";
  params: {
    name: string;
    arguments?: { [key: string]: unknown };
  };
}

Proposed Approach (Decoupled Definition):

First, the data models for the request and response are defined as top-level schemas.

/**
 * Parameters for a `tools/call` request.
 *
 * @category tools/call
 */
export interface CallToolRequestParams extends RequestParams {
  name: string;
  arguments?: { [key: string]: unknown };
}

Then, the RPC method definition becomes much simpler, merely referring to these models.

export interface CallToolRequest extends Request {
  method: "tools/call";
  params: CallToolRequestParams;
}

Rationale

The proposed solution—separating payload definitions from the RPC method—was chosen as the most direct and non-disruptive path to achieving the goals outlined in the motivation.

This approach establishes a clear architectural boundary between two distinct concerns:

1. The Data Layer: The transport-agnostic payload definition (e.g., CallToolRequestParams), which represents the core information being exchanged.
2. The Transport Layer: The protocol-specific wrapper (e.g., the JSON-RPC CallToolRequest object), which describes how the data is sent.

This architectural separation is superior to maintaining separate, parallel specifications for each transport (e.g., one for JSON-RPC, another for gRPC), which would introduce significant maintenance overhead and risk inconsistencies.

Crucially, this design refactors the specification document itself but intentionally leaves the on-the-wire format unchanged. This makes the proposal fully backward-compatible, requiring no changes from existing, compliant clients and servers. In short, this change is a strategic, foundational improvement that enables future growth without penalizing the current ecosystem.

Backward Compatibility

This proposal is a non-breaking change for existing implementations. It is a refactoring of the specification document itself and does not alter the on-the-wire JSON format of the protocol messages. A client or server that is compliant with the old specification structure will remain compliant with the new one, as the resulting JSON payloads are identical.

The primary impact is on developers who read the specification and on tools that parse the specification to generate code or documentation.

SEP-1330 Elicitation Enum Schema Improvements and Standards Compliance

Final · Standards Track · Created 2025-08-11

• Status: Final
• Type: Standards Track
• Created: 2025-08-11
• Author(s): chughtapan
• Issue: #1330

Abstract

This SEP proposes improvements to enum schema definitions in MCP, deprecating the non-standard enumNames property in favor of JSON Schema-compliant patterns, and introducing additional support for multi-select enum schemas in addition to single choice schemas. The new schemas have been validated against the JSON specification.

Schema Changes: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1148 Typescript SDK Changes: https://github.com/modelcontextprotocol/typescript-sdk/pull/1077 Python SDK Changes: https://github.com/modelcontextprotocol/python-sdk/pull/1246 Client Implementation: https://github.com/evalstate/fast-agent/pull/324/files Working Demo: https://asciinema.org/a/anBvJdqEmTjw0JkKYOooQa5Ta

Motivation

The existing schema for enums uses a non-standard approach to adding titles to enumerated values. It also limits use of enums in Elicitation (and any other schema object that should adopt EnumSchema in the future) to a single selection model. It is a common pattern to ask the user to select multiple entries. In the UI, this amounts to the difference between using checkboxes or radio buttons.

For these reasons, we propose the following non-breaking minor improvements to the EnumSchema for improving user and developer experience.

• Keep the existing EnumSchema as "Legacy"
  • It uses a non-standard approach for adding titles to enumerated values
  • Mark it as Legacy but still support it for now.
  • As per @dsp-ant When we have a proper deprecation strategy, we'll mark it deprecated
• Introduce the distinction between Untitled and Titled enums.
  • If the enumerated values are sufficient, no separate title need be specified for each value.
  • If the enumerated values are not optimal for display, a title may be specified for each value.
• Introduce the distinction between Single and Multi-select enums.
  • If only one value can be selected, a Single select schema can be used
  • If more than one value can be selected, a Multi-select schema can be used
• In ElicitResponse, add array as an additionalProperty type
  • Allows multiple selection of enumerated values to be returned to the server

Specification

1. Mark Current EnumSchema with Non-Standard enumNames Property as "Legacy"

The current MCP specification uses a non-standard enumNames property for providing display names for enum values. We propose to mark enumNames property as legacy, suggest using TitledSingleSelectEnum, a standards compliant enum type we define below.

// Continue to support the current EnumSchema as Legacy

/**
 * Legacy: Use TitledSingleSelectEnumSchema instead.
 * This interface will be removed in a future version.
 */
export interface LegacyEnumSchema {
  type: "string";
  title?: string;
  description?: string;
  enum: string[];
  enumNames?: string[]; // Titles for enum values (non-standard, legacy)
}

2. Define Single Selection Enums (with Titled and Untitled varieties)

Enums may or may not need titles. The enumerated values may be human readable and fine for display. In which case an untitled implementation using the JSON Schema keyword enum is simpler. Adding titles requires the enum array to be replaced with an array of objects using const and title.

// Single select enum without titles
export type UntitledSingleSelectEnumSchema = {
  type: "string";
  title?: string;
  description?: string;
  enum: string[]; // Plain enum without titles
};

// Single select enum with titles
export type TitledSingleSelectEnumSchema = {
  type: "string";
  title?: string;
  description?: string;
  oneOf: Array<{
    const: string; // Enum value
    title: string; // Display name for enum value
  }>;
};

// Combined single selection enumeration
export type SingleSelectEnumSchema =
  UntitledSingleSelectEnumSchema | TitledSingleSelectEnumSchema;

3. Introduce Multiple Selection Enums (with Titled and Untitled varieties)

While elicitation does not support arbitrary JSON types like arrays and objects so clients can display the selection choice easily, multiple selection enumerations can be easily implemented.

// Multiple select enums without titles
export type UntitledMultiSelectEnumSchema = {
  type: "array";
  title?: string;
  description?: string;
  minItems?: number; // Minimum number of items to choose
  maxItems?: number; // Maximum number of items to choose
  items: {
    type: "string";
    enum: string[]; // Plain enum without titles
  };
};

// Multiple select enums with titles
export type TitledMultiSelectEnumSchema = {
  type: "array";
  title?: string;
  description?: string;
  minItems?: number; // Minimum number of items to choose
  maxItems?: number; // Maximum number of items to choose
  items: {
    oneOf: Array<{
      const: string; // Enum value
      title: string; // Display name for enum value
    }>;
  };
};

// Combined Multiple select enumeration
export type MultiSelectEnumSchema =
  UntitledMultiSelectEnumSchema | TitledMultiSelectEnumSchema;

4. Combine All Varieties as EnumSchema

The final EnumSchema rolls up the legacy, multi-select, and single-select schemas as one, defined as:

// Combined legacy, multiple, and single select enumeration
export type EnumSchema =
  SingleSelectEnumSchema | MultiSelectEnumSchema | LegacyEnumSchema;

5. Extend ElicitResult

The current elicitation result schema only allows returning primitive types. We extend this to include string arrays for MultiSelectEnums:

export interface ElicitResult extends Result {
  action: "accept" | "decline" | "cancel";
  content?: { [key: string]: string | number | boolean | string[] }; // string[] is new
}

Instance Schema Examples

Single-Select Without Titles (No change)

{
  "type": "string",
  "title": "Color Selection",
  "description": "Choose your favorite color",
  "enum": ["Red", "Green", "Blue"],
  "default": "Green"
}

Legacy Single Select With Titles

{
  "type": "string",
  "title": "Color Selection",
  "description": "Choose your favorite color",
  "enum": ["#FF0000", "#00FF00", "#0000FF"],
  "enumNames": ["Red", "Green", "Blue"],
  "default": "#00FF00"
}

Single-Select with Titles

{
  "type": "string",
  "title": "Color Selection",
  "description": "Choose your favorite color",
  "oneOf": [
    { "const": "#FF0000", "title": "Red" },
    { "const": "#00FF00", "title": "Green" },
    { "const": "#0000FF", "title": "Blue" }
  ],
  "default": "#00FF00"
}

Multi-Select Without Titles

{
  "type": "array",
  "title": "Color Selection",
  "description": "Choose your favorite colors",
  "minItems": 1,
  "maxItems": 3,
  "items": {
    "type": "string",
    "enum": ["Red", "Green", "Blue"]
  },
  "default": ["Green"]
}

Multi-Select with Titles

{
  "type": "array",
  "title": "Color Selection",
  "description": "Choose your favorite colors",
  "minItems": 1,
  "maxItems": 3,
  "items": {
    "anyOf": [
      { "const": "#FF0000", "title": "Red" },
      { "const": "#00FF00", "title": "Green" },
      { "const": "#0000FF", "title": "Blue" }
    ]
  },
  "default": ["Green"]
}

Rationale

1. Standards Compliance: Aligns with official JSON Schema specification. Standard patterns work with existing JSON Schema validators
2. Flexibility: Supports both plain enums and enums with display names for single and multiple choice enums.
3. Client Implementation: shows that the additional overhead of implementing a group of checkboxes v/s a single checkbox is minimal: https://github.com/evalstate/fast-agent/pull/324/files

Backwards Compatibility

The LegacyEnumSchema type maintains backwards compatible during the migration period. Existing implementations using enumNames will continue to work until a protocol-wide deprecation strategy is implemented, and this schema is removed.

Reference Implementation

Schema Changes: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1148 Typescript SDK Changes: https://github.com/modelcontextprotocol/typescript-sdk/pull/1077 Python SDK Changes: https://github.com/modelcontextprotocol/python-sdk/pull/1246 Client Implementation: https://github.com/evalstate/fast-agent/pull/324/files Working Demo: https://asciinema.org/a/anBvJdqEmTjw0JkKYOooQa5Ta

Security Considerations

No security implications identified. This change is purely about schema structure and standards compliance.

Appendix

Validations

Using stored validations in the JSON Schema Validator at https://www.jsonschemavalidator.net/ we validate:

• All of the example instance schemas from this document against the proposed JSON meta-schema EnumSchema in the next section.
• Valid and invalid values against the example instance schemas from this document.

Legacy Single Selection

• EnumSchema validating a legacy single select instance schema with titles
• The legacy titled single select instance schema validating a correct single selection
• The legacy titled single select instance schema validating an incorrect single selection

Single Selection

• EnumSchema validating a single select instance schema without titles
• EnumSchema validating a single select instance schema with titles
• The untitled single select instance schema validating a correct single selection
• The untitled single select instance schema invalidating an incorrect single selection
• The titled single select instance schema validating a correct single selection
• The titled single select instance schema invalidating an incorrect single selection

Multiple Selection

• EnumSchema validating the multi-select instance schema without titles
• EnumSchema validating the multi-select instance schema with titles
• The untitled multi-select instance schema validating a correct multiple selection The untitled multi-select instance schema validating invalidating an incorrect multiple selection The titled multi-select instance schema validating a correct multiple selection The titled multi-select instance schema validating invalidating an incorrect multiple selection

JSON meta-schema

This is our proposal for the replacement of the current EnumSchema in the specification’s schema.json.

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "definitions": {
    // New Definitions Follow
    "UntitledSingleSelectEnumSchema": {
      "type": "object",
      "properties": {
        "type": { "const": "string" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "enum": {
          "type": "array",
          "items": { "type": "string" },
          "minItems": 1
        }
      },
      "required": ["type", "enum"],
      "additionalProperties": false
    },

    "UntitledMultiSelectEnumSchema": {
      "type": "object",
      "properties": {
        "type": { "const": "array" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "minItems": {
          "type": "number",
          "minimum": 0
        },
        "maxItems": {
          "type": "number",
          "minimum": 0
        },
        "items": {
          "type": "object",
          "properties": {
            "type": { "const": "string" },
            "enum": {
              "type": "array",
              "items": { "type": "string" },
              "minItems": 1
            }
          },
          "required": ["type", "enum"],
          "additionalProperties": false
        }
      },
      "required": ["type", "items"],
      "additionalProperties": false
    },

    "TitledSingleSelectEnumSchema": {
      "type": "object",
      "required": ["type", "anyOf"],
      "properties": {
        "type": { "const": "string" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "anyOf": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["const", "title"],
            "properties": {
              "const": { "type": "string" },
              "title": { "type": "string" }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },

    "TitledMultiSelectEnumSchema": {
      "type": "object",
      "required": ["type", "anyOf"],
      "properties": {
        "type": { "const": "array" },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "anyOf": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["const", "title"],
            "properties": {
              "const": { "type": "string" },
              "title": { "type": "string" }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },

    "LegacyEnumSchema": {
      "properties": {
        "type": {
          "type": "string",
          "const": "string"
        },
        "title": { "type": "string" },
        "description": { "type": "string" },
        "enum": {
          "type": "array",
          "items": { "type": "string" }
        },
        "enumNames": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "required": ["enum", "type"],
      "type": "object"
    },

    "EnumSchema": {
      "oneOf": [
        { "$ref": "#/definitions/UntitledSingleSelectEnumSchema" },
        { "$ref": "#/definitions/UntitledMultiSelectEnumSchema" },
        { "$ref": "#/definitions/TitledSingleSelectEnumSchema" },
        { "$ref": "#/definitions/TitledMultiSelectEnumSchema" },
        { "$ref": "#/definitions/LegacyEnumSchema" }
      ]
    }
  }
}

SEP-1577 Sampling With Tools

Final · Standards Track · Created 2025-09-30

• Status: Final
• Type: Standards Track
• Created: 2025-09-30
• Author(s): Olivier Chafik (@ochafik)
• Issue: #1577

Updates:

• Oct 1: renamed tool_choice -> toolChoice (+ "none" value); removed exotic stopReasons "refusal" & "other"; allowed {CreateMessageResult,SamplingMessage}.content to be single contents or arrays of contents;
• Oct 6: aligned ToolResultContent on CallToolResult (support image / audio); added "Possible Follow Ups" section.
• Oct 10: updated reference impl example w/ simple tool registry (unify mcp tools w/ tool loop tools, see comment below) and a "choose your own adventure" game that uses sampling w/ tools + elicitation.
• Oct 27: aligned ToolResultContent.content on CallToolResult.content (using ContentBlock); added ToolResultContent._meta
• Nov 5:
  • kept stopReason as open string but w/ redundant explicit enums for visibility
  • removed requirement to throw when includeContext not matching advertised ClientCapabilities.sampling.context
  • mitigates backwards compatibility issue of CreateMessageResult.content being an array of contents OR a single content by saying sampling MUST NOT return an array in earlier spec versions (+ acknowledging SDK updates of code w/ sampling will need small code changes)
• Nov 7: renamed type ToolCallContent to ToolUseContent (to match its tool_use type & the toolUse stopReason). SEP was approved!
• Nov 10: removing disable_parallel_tool_use / keeping for a later update as the Gemini API has no way to implement this for now.
• Nov 11: added extra notes about Gemini API's function calling modes & roles; requiring SamplingMessage w/ tool result contents not be mixed w/ other content types

Abstract

This SEP introduces tools & toolChoice params to sampling/createMessage and soft-deprecates includeContext (fences thisServer & allServers under a capability). This allows MCP servers to run their own agentic loops using the client's tokens (still under the user supervision), and reduces the complexity of client implementations (context support becoming explicitly optional).

Motivation

• Sampling doesn't support tool calling, although it's a cornerstone of modern agentic behaviour. Without explicit support for it, MCP servers that use Sampling can either try and emulate tool calling w/ complex prompting / custom parsing of the outputs, or are limited to simpler, non-agentic requests. Adding support for tool calling could unlock many novel use cases in the MCP ecosystem.

• Context inclusion is ambiguously defined (see this doc): it makes it particularly tricky to fully implement sampling, which along with other precautions needed for sampling (unaffected by this SEP) may have contributed to low adoption of the feature in clients (feature was introduced in the MCP Nov 2024 spec).

Please note some related work:

• MCP Sampling (@jerome3o-anthropic): extremely similar proposal:
  • Add same tools semantics,
  • Deprecate includeContext (doc explains why its semantics are ambiguous)
  • (goes further to suggest explicit context sharing, which is out of scope from this proposal)
• Allow Prompt/Sampling Messages to contain multiple content blocks. #198
  • In this PR we've made {CreateMessageResult,SamplingMessage}.content to accept a single content or an array of contents. The result.content change is backwards incompatible but is required to support parallel tool calls. The SamplingMessage.content change then makes it much more natural to write a tool loop (see example in reference implementation: toolLoopSampling.ts)

In the "Possible Follow ups" Section below, we give examples of features that were kept out of scope from this SEP but which we took care to make this SEP reasonably compatible with.

Specification

Overview

• Add traditional tool call support in CreateMessageRequest w/ tools (w/ JSON schemas) & toolChoice params, requiring a server-side tool loop
  • Sampling may now yield ToolCallBlock responses
  • Server needs to call tools by itself
  • Server calls sampling again with ToolResultParamBlock to inject tool results
  • toolChoice.mode can be “auto" | "required" | "none" to allow common structured outputs use case (see below for possible follow up improvements)
  • Fenced by new capability (sampling { tools {} })
• Fix/update underspecified strings in CreateMessageResult:
  • stopReason: “endTurn" | "stopSequence" | “toolUse" | “maxToken" | string (explicit enums + open string for compat)
  • role: “assistant”
• Soft-deprecate CreateMessageRequest.params.includeContext != ‘none’ (now fenced by capability)
  • Incentivize context-free sampling implementation

Protocol changes

• sampling/createMessage
  • MUST throw an error when includeContext is “thisServer” | “allServers” but clientCapabilities.sampling.context is missing
  • MUST throw an error when tool or toolChoice are defined but clientCapabilities.sampling.tools is missing
  • Servers SHOULD avoid [includeContext](https://omcp.tech/specification/2025-06-18/schema#createmessagerequest) != ‘none’as values“thisServer”and“allServers”` may be removed in future spec releases.
  • CreateMessageRequest.messages MUST balance any “assistant” message w/ a ToolUseContent (and id: $id1) w/ a “user” message w/ a ToolResultContent (and tool_result_id: $id1)
    • Note: this is a requirement for Claude API implementation (parallel tool call must all be responded to in one go)
  • SamplingMessage with tool result content blocks MUST NOT contain other content types.

Schema changes

• ClientCapabilities

  interface ClientCapabilities {
    ...
    sampling?: {
      context?: object; // NEW: Allows CreateMessageRequest.params.includeContext != "none"
      tools?: object;   // NEW: Allows CreateMessageRequest.params.{tools,toolChoice}
    };
  }
  

• CreateMessageRequest (use existing Tool)

  interface CreateMessageRequest {
    method: “sampling/createMessage”;
    params: {
      ...
      messages: SamplingMessage[]; // Note: type updated, see below
      
      tools?: Tool[] // NEW (existing type)
  
      toolChoice?: ToolChoice // NEW
    };
  }
  
  interface ToolChoice { // NEW
    mode?: “auto” | "required" | "none";
    // disable_parallel_tool_use?: boolean; // Update (Nov 10): removed, see below
  }
  

  • Notes:
    • OpenAI vs. Anthropic API idioms to avoid parallel tool calls:
      • OpenAI: parallel_tool_calls: false (top-level param)
      • Anthropic: tool_choice.disable_parallel_tool_use: true
        • Preferred here as default value if unset is false (e.g. parallel tool calls allowed)
    • OpenAI vs. Anthropic API re/ tool_choice "none" vs. tools:
      • OpenAI: tools: [$Foo], tool_choice: "none" forbids any tool call
        • Preferred behaviour here
      • Anthropic: tools: [$Foo], tool_choice: {mode: "none"} may still call tool Foo
    • Gemini vs. OAI / Anthropic re/ disable_parallel_tool_use:
      • Gemini API has no way to disable parallel tool calls atm (unlike OAI / Anthropic APIs). Removing this flag for now, to be reintroduced when Gemini has any way of supporting it. Otherwise clients would get unexpected multiple tool calls (or alternatively if implemented that way, unexpected failures / costly retry until a single tool call is emitted)
      • Gemini API's Function calling modes have an ANY value that should match the proposed required

• SamplingMessage:

  /*
    BEFORE:
    
    interface SamplingMessage {
      content: TextContent | ImageContent | AudioContent
      role: Role;
    }
  */
  
  type SamplingMessage = UserMessage | AssistantMessage; // NEW
  
  type AssistantMessageContent =
    TextContent | ImageContent | AudioContent | ToolUseContent;
  type UserMessageContent =
    TextContent | ImageContent | AudioContent | ToolResultContent;
  interface AssistantMessage {
    // NEW
    role: "assistant";
    content: AssistantMessageContent | AssistantMessageContent[];
  }
  
  interface ToolUseContent {
    // NEW
    type: "tool_use";
    name: string;
    id: string;
    input: object;
  }
  
  interface UserMessage {
    // NEW
    role: "user";
    content: UserMessageContent | UserMessageContent[];
  }
  
  interface ToolResultContent {
    // NEW
    _meta?: { [key: string]: unknown };
    type: "tool_result";
    toolUseId: string;
    content: ContentBlock[];
    structuredContent: object;
    isError?: boolean;
  }
  

• Notes:

  • Differences of role vs. content type when it comes to tool calling between APIs:
    • OpenAI: role: “system" | “user" | “assistant" | “tool" (where tool is for tool results), while tool calls are nested in assistant messages, content is then typically null but some “OpenAI compatible” APIs accept non-null values

      • [
          { role: "user", content: "what is the temperature in london?" },
          {
            role: "assistant",
            content: "Let me use a tool...",
            tool_calls: [
              {
                id: "call_1",
                type: "function",
                function: {
                  name: "get_weather",
                  arguments: '{"location": "London"}',
                },
              },
            ],
          },
          {
            role: "tool",
            content: '{"temperature": 20, "condition": "sunny"}',
            tool_call_id: "call_1",
          },
        ];
        

    • Claude API: role: “user" | “assistant", tool use and result are passed through specially-typed message content parts:

      • [
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "what is the temperature in london?"
              }
            },
          {
            "role": "assistant",
            "content": [
              {
                "type": "text",
                "text": "Let me use a tool..."
              },
              {
                "type": "tool_use",
                "id": "call_1",
                "name": "get_weather",
                "input": {"location": "London"}
              }
            ]
          },
          {
            "role": "user",
            "content": [
              {
                "type": "tool_result",
                "tool_call_id": "call_1",
                "content": {"temperature": 20, "condition": "sunny"}
              }
            ]
          }
        ]
        

    • Gemini API:
      • function role (similar to OAI's tool role)
      • No tool call id concept (function calling: Gemini requires tool results to be provided in the exact same order as the tool use parts. An implementation could generate the tool call ids and use them to reorder the tool results if needed.

• CreateMessageResult

  /*
    BEFORE:
  
    interface CreateMessageResult {
      _meta?: { [key: string]: unknown };
      content: TextContent | ImageContent | AudioContent;
      role: Role;
      stopReason?: string;
      [key: string]: unknown;
  }
  */
  interface CreateMessageResult {
    _meta?: { [key: string]: unknown };
  
    content: AssistantMessageContent | AssistantMessageContent[] // UPDATED
  
    role: "assistant"; // UPDATED
  
    stopReason?: “endTurn" | "stopSequence" | “toolUse" | “maxToken" | string // UPDATED
  
    [key: string]: unknown;
  }
  

  • Notes:
    • Backwards compatibility issue: returning CreateMessageResult.content as an array of contents OR a single content is problematic, so we propose:
      • sampling/createMessage MUST NOT return an array in CreateMessageResult.content before spec version Nov 2025.
        • This guarantees wire-level backwards-compatibility
      • Existing code that uses sampling may break w/ new SDK releases as it will need to test content to know if it's an array or a single block, and act accordingly.
      • This seems reasonable(?)
    • CreateMessageResult.stopReason field is currently defined as an open string, and the spec only mentions the endTurn as example value.
    • OpenAI vs. Anthropic API idioms
      • Finish/stop reason
        • OpenAI’s ChatCompletion: finish_reason: “stop” | “length” | “tool_use” (…?)
        • Anthropic: stop_reason: “end_turn” | “max_tokens” | “stop_sequence” | “tool_use” | “pause_turn” | “refusal”

Possible Follow ups

These are out of scope for this SEP, but care was taken not to preclude them, so where appropriate we give examples of how they could be implemented on top of / after this SEP.

Streaming support

See: Streaming tool use results #117

This could be important for some longer-running use cases or when latency is important, but would play better w/ streaming support in MCP tools.

A possible way to implement this would be to use notifications w/ payload, and possibly create a new method sampling/createMessageStreamed. Both should be orthogonal w/ this SEP (but we'd need to create delta types for results, similar to streaming APIs in inference API such as Claude API and OpenAI API).

Cache friendliness updates

Two bits needed here:

• Introduce cache awareness
  • Implicit caching guidelines phrased as SHOULDs
  • Explicit cache points and TTL semantics as in the Claude API? (incl. beta behaviour for longer caching)
    • Pros: easy to implement for at least 1 implementor (Anthropic)
    • Cons: if hard to implement for others, unlikely to get approval.
  • “Whole prompt” / prompt-prefix cache w/ an explicit key as in the OpenAI API?
    • Pros:
      • simpler for users (no need to think about where the shared prefix stops)
      • implicitly supports updating the cache (maybe even as subtree)
    • Cons: possibly harder to implement / more storage inefficient
• Introduce allowed_tools feature to enable / disable tools w/o breaking context caching

  • Relevant to this SEP as we may want to merge this feature under the tool_choice field, similar to what OpenAI did.

    interface ToolChoice { // NEW
      mode?: “auto” | "required";
      allowed_tools?: string[]
    }
    

Allow client to call the server’s tools by itself in an agentic loop

From the server’s perspective, that would remove the need to call tools by itself / inject tool results in follow up sampling calls.

The MCP server would just allowlist its own tools in the sampling request, w/t a dedicated tool definition such as:

{
  type: "server-tool"; // MCP tool from same server.
  name: string;
}

Pros:

• Safe, limited to that server’s tools.
• If we propagate the mcp-session-id, can leverage keep any server-side session context / caching

Allow client to call any other MCP servers’ tools by itself in an agentic loop

Although this sounds similar to the previous one (allow only same server’s tools), this option wouldn’t need a protocol change / could be entirely done by the client as an implementation detail of their sampling support.

The end user would allowlist tools from any other MCP server for use in a sampling request, without the server having to ask for anything. The client UI would e.g. display a tool selection UI as part of the sampling approval flow, auto enabling tools from same server by default.

Pros:

• Technically no spec change needed (if anything, mention this as a freedom clients have)
• Possibly similar to what CreateMessageRequest.params.includeContext = thisServer / allServers intended semantics may have meant
  • CreateMessageRequest.params.allowImplicitToolCalls = “none” | “thisServer” | “allServers” (assuming we wanted to give the server any control over this)

Cons:

• Classifier might be needed to avoid High potential for privacy leaks / abuse
  • If user approves Gmail MCP tool usage / delegation by mistake, server gets access to their private emails through sampling

Allow server to list & call clients’ tools (client/server → p2p)

If we say the client can now expose tools that the server can call, it opens a set of possibilities:

• The client can “forward” other servers’ tools (maybe w/ some namespacing for seamless aggregation)
  • The server can then call these tools as part of its tool loop.
• Client & Server semantics start to lose weight, we enter a more peer-to-peer, symmetrical relationship
  • Client could also ask a server for sampling, while we’re at it
  • Symmetry at the protocol layer, but still directionality at the transport layer (e.g. for HTTP transport, direction of POST requests still matters)

Simplify structured outputs use case

A major use case of sampling is to get outputs that conform to a given schema.

This is possible in OpenAI’s API for instance.

The most common workaround is to give a single tool and set tool_choice: "required", which guarantees the output is a ToolCall containing inputs that conform to the tool’s input schema.

While this SEP proposes we enable this "required"-based workaround, as a follow up it would be great to provide more explicit / simpler JSON schema support, which would also allow schema types not allowed in tool inputs (which require an object w/ properties, so one has to pick at least a name for their outputs, which requires thinking / interplay w/ the prompting strategy):

interface CreateMessageRequest {
  method: “sampling/createMessage”;
  params: {
    messages: SamplingMessage[];
    ...
    format: {
      type: "json_schema",
      "schema": {
        "type": "array",
        "minItems": 5,
        "maxItems": 100
      }
    }
  }

SEP-1613 Establish JSON Schema 2020-12 as Default Dialect for MCP

Final · Standards Track · Created 2025-10-06

• Status: Final
• Type: Standards Track
• Created: 2025-10-06
• Author(s): Ola Hungerford
• Issue: #1613

Abstract

This SEP establishes JSON Schema 2020-12 as the default dialect for embedded schemas within MCP messages (tool inputSchema/outputSchema and elicitation requestedSchema fields). Schemas may explicitly declare alternative dialects via the $schema field. This resolves ambiguity that has caused compatibility issues between implementations.

Motivation

The MCP specification does not explicitly state which JSON Schema version to use for embedded schemas. This has caused:

• Validation failures between clients and servers assuming different versions
• Implementation divergence across SDK ecosystems
• Developer uncertainty requiring arbitrary version choices

Community discussion (GitHub Discussion #366, PR #655) revealed that implementations were split between draft-07 and 2020-12, with multiple maintainers and community members expressing strong preference for 2020-12 as the default.

Specification

1. Default Dialect

Embedded JSON schemas within MCP messages MUST conform to JSON Schema 2020-12 when no $schema field is present.

2. Explicit Dialect Declaration

Schemas MAY include an explicit $schema field to declare a different dialect:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  }
}

3. Schema Validation Requirements

• Schemas MUST be valid according to their declared or default dialect
• The inputSchema field MUST NOT be null

For tools with no parameters, use one of these valid approaches:

• true - accepts any input (most permissive)
• {} - equivalent to true, accepts any input
• { "type": "object" } - accepts any object with any properties
• { "type": "object", "additionalProperties": false } - accepts only empty objects {}

Example for a tool with no parameters:

{
  "name": "get_current_time",
  "description": "Returns the current server time",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

4. Scope of Application

This specification applies to:

• tools/list response: inputSchema and outputSchema
• prompts/elicit request: requestedSchema
• Future MCP features embedding JSON Schema definitions

5. Implementation Requirements

Servers MUST:

• Generate schemas conforming to 2020-12 by default
• Include explicit $schema when using non-default dialects

Clients MUST:

• Validate schemas according to declared or default dialect
• Support at least JSON Schema 2020-12

Rationale

Why 2020-12?

1. Ecosystem alignment: Python SDK (via Pydantic) and Go SDK implementations prefer/use 2020-12
2. Modern features: Better validation capabilities and composition support
3. Community preference: Multiple maintainers and community members in PR #655 discussion advocated for 2020-12 over draft-07
4. Current standard: 2020-12 is the stable version as of 2025

Why allow explicit declaration?

• Supports migration paths for existing schemas
• Provides flexibility without protocol changes
• Follows JSON Schema best practices

Alternatives considered

• Draft-07 as default: Rejected after community feedback; older version with less capability
• No default: Rejected as unnecessarily verbose; adds boilerplate
• Multiple equal versions: Rejected; creates unpredictability and fragmentation

Backward Compatibility

This is technically a clarification, and not a breaking change:

• Existing schemas without $schema default to 2020-12
• Servers can add explicit $schema during transition
• Basic schemas (type, properties, required) work across versions

Migration may be needed for schemas assuming draft-07 by default:

• Schemas using dependencies (→ dependentSchemas + dependentRequired)
• Positional array validation (→ prefixItems)

Migration strategy: Add explicit $schema: "http://json-schema.org/draft-07/schema#" during transition, then update to 2020-12 features.

Reference Implementation

SDK Implementations

Python SDK - Already compatible:

• Uses Pydantic for schema generation
• Pydantic defaults to 2020-12 via .model_json_schema()

Go SDK - Implemented 2020-12:

• Explicit 2020-12 implementation completed
• Confirmed by @samthanawalla in PR #655 discussion

Other SDKs:

• May require updates but based on other examples, there should be straightforward or out-of-the-box options to support this. I can add more examples here or we can create issues to follow up on these after acceptance.

Security Implications

No specific security implications have been identified from establishing 2020-12 as the default dialect. The clarification reduces ambiguity that could lead to validation mismatches between implementations, which is a minor security improvement through increased predictability.

Implementations should use well-maintained JSON Schema validator libraries and keep them updated, as with any dependency.

Related Work

SEP-1330: Elicitation Enum Schema Improvements

SEP-1330 proposes deprecating the non-standard enumNames property in favor of JSON Schema 2020-12 compliant patterns. This work is directly enabled by establishing 2020-12 as the default dialect.

Implementation Consideration:
As noted in SEP-1330 discussion, there is some concern about parsing complexity with advanced JSON Schema features like oneOf and anyOf. However, these features are part of the JSON Schema standard and well-supported by mature validator libraries. Implementations can balance standards compliance with their parsing needs by using well-tested JSON Schema validation libraries.

SEP-834: Full JSON Schema 2020-12 Support

This SEP establishes the foundation (default dialect) while SEP-834 addresses comprehensive support for 2020-12 features.

Open Questions

The schema for the spec itself references draft-07 and the typescript-json-schema package we use to generate it only supports draft-07.

Options:

1. Update schema generation script to patch to 2020-12 after generation (this is what I did in the current PR)
2. Switch to a different schema generator that supports 2020-12
3. Leave as-is since it doesn't actually conflict with the spec?

Personally I'd prefer (1) in the short term and then (2) as a follow-up.

SEP-1686 Tasks

Final · Standards Track · Created 2025-10-20

• Status: Final
• Type: Standards Track
• Created: 2025-10-20
• Author(s): Surbhi Bansal, Luca Chang
• Issue: #1686

Abstract

This SEP is preserved as a historical record of the experimental tasks feature shipped in the 2025-11-25 specification. The code examples below are non-normative pseudocode written against the v1 SDKs. The draft specification moves tasks out of the core protocol and into the io.modelcontextprotocol/tasks extension (SEP-2663).

This SEP improves support for task-based workflows in the Model Context Protocol (MCP). It introduces both the task primitive and the associated task ID, which can be used to query the state and results of a task, up to a server-defined duration after the task has completed. This primitive is designed to augment other requests (such as tool calls) to enable call-now, fetch-later execution patterns across all requests for servers that support this primitive.

Motivation

The current MCP specification supports tool calls that execute a request and eventually receive a response, and tool calls can be passed a progress token to integrate with MCP’s progress-tracking functionality, enabling host applications to receive status updates for a tool call via notifications. However, there is no way for a client to explicitly request the status of a tool call, resulting in states where it is possible for a tool call to have been dropped on the server, and it is unknown if a response or a notification may ever arrive. Similarly, there is no way for a client to explicitly retrieve the result of a tool call after it has completed — if the result was dropped, clients must call the tool again, which is undesirable for tools expected to take minutes or more. This is particularly relevant for MCP servers abstracting existing workflow-based APIs, such as AWS Step Functions, Workflows for Google Cloud, or APIs representing CI/CD pipelines, among other applications.

Today, it is possible for individual MCP servers to represent tools in a way that enables this, with certain compromises. For example, a server may expose a long_running_tool and wish to support this pattern, splitting it into three separate tools to accommodate this:

1. start_long_running_tool: This would start the work represented by long_running_tool and return a tracking token of some kind, such as a job ID.
2. get_long_running_tool_status(token): This would accept the tracking token and return the current status of the tool call, informing the caller that the operation is still ongoing.
3. get_long_running_tool_result(token): This would accept the tracking token and return the result of the tool call, if it is available.

Representing a tool in this way seems to solve for the use case, but it introduces a new problem: Tools are generally-expected to be orchestrated by an agent, and agent-driven polling is both unnecessarily expensive and inconsistent — it relies on prompt engineering to steer an agent to poll at all. In the original long_running_tool case, the client had no way of knowing if a response would ever be received, while in the start_long_running_tool case, the application has no way of knowing if the agent will orchestrate tools according to the specific contract of the server.

It is also impossible for the host application to take ownership of this orchestration, as this tool-splitting is both conventions-based and may be implemented in different ways across MCP servers — one server may have three tools for one conceptual operation (as in our example), or it may have more, in the case of more complex, multi-step operations.

On the other hand, if active task polling is not needed, existing MCP servers can fully-wrap a workflow API in a single tool call that polls for a result, but this introduces an undesirable implementation cost: an MCP server wrapping an existing workflow API is a server that only exists for polling other systems.

Affected Customer Use Cases These concerns are backed by real use cases that Amazon has seen both internally and with their external customers (identities redacted where non-public):

1. Healthcare & Life Sciences Data Analysis Challenge: Amazon’s customers in the healthcare and life sciences industry are attempting to use MCP to wrap existing computational tools to analyze molecular properties and predict drug interactions, processing hundreds of thousands of data points per job from chemical libraries through multiple inference models simultaneously. These complex, multi-step workflows require a way to actively check statuses, as they take upwards of several hours, making retries undesirable. Current Workaround: Not yet determined. Impact: Cannot integrate with real-time research workflows, prevents interactive drug discovery platforms, and blocks automated research pipelines. These customers are looking for best practices for workflow-based tool calls and have noted the lack of first-class support in MCP as a concern. If these customers do not have a solution for long-running tool calls, they will likely forego MCP and continue using their existing platforms. Ideal: Concurrent and poll-able tool calls as an answer for operations executing in the range of a few minutes, and some form of push notification system to avoid blocking their agents on long analyses on the order of hours. This SEP supports the former use case, and offers a framework that could extend to support the latter.

2. Enterprise Automation Platforms Challenge: Amazon’s large enterprise customers are looking to develop internal MCP platforms to automate SDLC processes across their organizations, extending to sales, customer service, legal, HR, and cross-divisional teams. They have noted they have long-running agent and agent-tool interactions, supporting complex business process automation. Current Workaround: Not yet determined. Considering an application-level system outside of MCP backed by webhooks. Impact: Limitations related to the host application being unaware of tool execution state prevent complex business process automation and limit sophisticated multi-step operations. These customers want to dispatch processes concurrently and collect their results later, and are noting the lack of explicit late-retrieval as a concern — and are considering involved application-level notification systems as a possible workaround. Ideal: Built-in mechanisms for actively checking the status of ongoing work to avoid needing to implement notification systems specific to their own tool conventions themselves.

3. Code Migration Workflows Challenge: Amazon has automated code migration and transformation tools to perform upgrades across its own codebases and those of external customers, and is attempting to wrap those tools in MCP servers. These migrations analyze dependencies, transform code to avoid deprecated runtime features, and validate changes across multiple repositories. These migrations range from minutes to hours depending on migration scope, complexity, and validation requirements. Current Workaround: Developers implement manual tracking by splitting a job into create and get tools, forcing models to manage state and repeatedly poll for completion. Impact: Poor developer experience due to needing to replicate this hand-rolled polling mechanism across many tools. One team had to debug an issue where the model would hallucinate job names if it hadn’t listed them first. Validating that this does not happen across many tools in a large toolset is time-consuming and error-prone. Ideal: Support natively polling tool state at the data layer to support pushing a tool to the background and avoiding blocking other tasks in the chat session, while still supporting deterministic polling and result retrieval. The team needs the same pattern across many tools in their MCP servers, and wants a common solution across them, which this SEP directly supports.

4. Test Execution Platforms Challenge: Amazon’s internal test infrastructure executes comprehensive test suites including thousands of cases, integration tests across services, and performance benchmarks. They have built an MCP server wrapping this existing infrastructure. Current Workaround: For streaming test logs, the MCP server exposes a tool that can read a range of log lines, as it cannot effectively notify the client when the execution is complete. There is not yet any workaround for executing test runs. Impact: Cannot run a test suite and stream its logs simultaneously without a single hours-long tool call, which would time out on either the client or the server. This prevents agents from looking into test failures in an incomplete test run until the entire test suite has completed, potentially hours later. Ideal: Support host application-driven tool polling for intermediate results, so a client can be notified when a long-running tool is complete. This SEP does not fully-support this use case (it does enable polling), but the Task execution model can be extended to do so, as discussed in the “Future Work” section.

5. Deep Research Challenge: Deep research tools spawn multiple research agents to gather and summarize information about topics, going through several rounds of search and conversation turns internally to produce a final result for the caller application. The tool takes an extended amount of time to execute, and it is not always clear if the tool is still executing. Current Workaround: The research tool is split into a separate create tool to create a report job and a get tool to get the status/result of that job later. Impact: When using this with host applications, the agent sometimes runs into issues calling the get tool repeatedly — in particular, it calls the tool once before ending its conversation turn, claiming to be "waiting" before calling the tool again. It cannot resume until receiving a new user message. This also complicates expiration times, as it is not possible to predict when the client will retrieve the result when this occurs. It is possible to work around this by adding a wait tool for the model, but this prevents the model from doing anything else concurrently. Ideal: Support polling a tool call’s state in a deterministic way and notify the model when a result is ready, so the tool result can be immediately retrieved and deleted from the server. Other than notifying the model (a host application concern), this SEP fully supports this use case.

6. Agent-to-Agent Communication (Multi-Agent Systems) Challenge: One of Amazon’s internal multi-agent systems for customer question answering faces scenarios where agents require significant processing time for complex reasoning, research, or analysis. When agents communicate through MCP, slow agents cause cascading delays throughout this system, as agents are forced to wait on their peers to complete their work. Current Workaround: Not yet determined. Impact: Communication pattern creates cascading delays, prevents parallel agent processing, and degrades system responsiveness for other time-sensitive interactions. Ideal: Some method to allow agents to perform other work concurrently and get notified once long-running tasks complete. This SEP supports this use case by enabling host applications to implement background polling for select tool calls without blocking agents.

These use cases demonstrate that a mechanism to actively track tool calls and defer results is a real requirement for these types of MCP deployments in production environments.

Integration with Existing Architectures Many workflow-driven systems already provide active execution-tracking capabilities with built-in status metadata, monitoring, and data retention policies. This proposal enables MCP servers to expose these existing APIs with thin MCP wrappers while maintaining their existing reliability.

Benefits for Existing Architectures:

• Leverage Existing State Management: Systems like AWS Step Functions, Workflows for Google Cloud, and CI/CD platforms already maintain execution state, logs, and results. MCP servers can expose these systems' existing APIs without pushing the responsibility of polling to a fallible agent.
• Preserve Native Monitoring: Existing monitoring, alerting, and observability tools continue to work unchanged. The execution happens almost entirely within the existing workflow-management system.
• Reduce Implementation Overhead: Server implementers don't need to build new state management, persistence, or monitoring infrastructure. They can focus on the MCP protocol mapping of their existing APIs to tasks.

This SEP simplifies integration with existing workflows and allows workflow services to continue to manage their own state while delivering a quality customer experience, rather than offloading to agent-polling or building MCP servers that do nothing but poll other services.

Specification

This SEP introduces a mechanism for requestors (which can be either clients or servers, depending on the direction of communication) to augment their requests with tasks. Tasks are durable state machines that carry information about the underlying execution state of the request they wrap, and are intended for requestor polling and deferred result retrieval. Each task is uniquely identifiable by a requestor-generated task ID.

1. User Interaction Model

Tasks are designed to be application-driven—receivers tightly-control which requests (if any) support task-based execution and manage the lifecycles of those tasks; meanwhile, requestors own the responsibility for augmenting requests with tasks, and for polling on the results of those tasks.

Implementations are free to expose tasks through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model.

2. Capabilities

Servers and clients that support task-augmented requests MUST declare a tasks capability during initialization. The tasks capability is structured by request category, with boolean properties indicating which specific request types support task augmentation.

Refer to https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1732 for details.

3. Protocol Messages

3.1. Creating Tasks

To create a task, requestors send a request with the modelcontextprotocol.io/task key included in _meta, with a taskId value representing the task ID. Requestors MAY include a keepAlive, with a value representing how long after completion the requestor would like the task results to be kept for.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "some_method",
  "params": {
    "_meta": {
      "modelcontextprotocol.io/task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
        "keepAlive": 60000
      }
    }
  }
}

3.2. Getting Tasks

To retrieve the state of a task, requestors send a tasks/get request:

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tasks/get",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "keepAlive": 30000,
    "pollFrequency": 5000,
    "status": "submitted",
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

3.3. Retrieving Task Results

To retrieve the result of a completed task, requestors send a tasks/result request:

Request:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tasks/result",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
      }
    ],
    "isError": false,
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

3.4. Task Creation Notification

When a receiver creates a task, it MUST send a notifications/tasks/created notification to inform the requestor that the task has been created and polling can begin.

Notification:

{
  "jsonrpc": "2.0",
  "method": "notifications/tasks/created",
  "params": {
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

The task ID is conveyed through the modelcontextprotocol.io/related-task metadata key. The notification parameters are otherwise empty.

This notification resolves the race condition where a requestor might attempt to poll for a task before the receiver has finished creating it. By sending this notification immediately after task creation, the receiver signals that the task is ready to be queried via tasks/get.

Receivers that do not support tasks (and thus ignore task metadata in requests) will not send this notification, allowing requestors to fall back to waiting for the original request response.

3.5. Listing Tasks

To retrieve a list of tasks, requestors send a tasks/list request. This operation supports pagination.

Request:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tasks/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "tasks": [
      {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
        "status": "working",
        "keepAlive": 30000,
        "pollFrequency": 5000
      },
      {
        "taskId": "abc123-def456-ghi789",
        "status": "completed",
        "keepAlive": 60000
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

3.6 Deleting Tasks

To explicitly delete a task and its associated results, requestors send a tasks/delete request.

Request:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tasks/delete",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

4. Behavior Requirements

These requirements apply to all parties that support receiving task-augmented requests.

4.1. Task Support and Handling

1. Receivers that do not support task augmentation on a request MUST process the request normally, ignoring any task metadata in _meta.
2. Receivers that support task augmentation MAY choose which request types support tasks.

4.2. Task ID Requirements

1. Task IDs MUST be a string value.
2. Task IDs SHOULD be unique across all tasks controlled by the receiver.
3. The receiver of a request with a task ID in its _meta MAY validate that the provided task ID has not already been associated with a task controlled by that receiver.

4.3. Task Status Lifecycle

1. Tasks MUST begin in the submitted status when created.
2. Receivers MUST only transition tasks through the following valid paths:
   1. From submitted: may move to working, input_required, completed, failed, cancelled, or unknown
   2. From working: may move to input_required, completed, failed, cancelled, or unknown
   3. From input_required: may move to working, completed, failed, cancelled, or unknown
   4. Tasks in completed, failed, cancelled, or unknown status MUST NOT transition to any other status (terminal states)
3. Receivers MAY move directly from submitted to completed if execution completes immediately.
4. The unknown status is a terminal fallback state for unexpected error conditions. Receivers SHOULD use failed with an error message instead when possible.

Task Status State Diagram:

4.4. Input Required Status

1. When a receiver sends a request associated with a task (e.g., elicitation, sampling), the receiver MUST move the task to the input_required status.
2. The receiver MUST include the modelcontextprotocol.io/related-task metadata in the request to associate it with the task.
3. When the receiver receives all required responses, the task MAY transition out of input_required status (typically back to working).
4. If multiple related requests are pending, the task SHOULD remain in input_required status until all are resolved.

4.5. Keep-Alive and Resource Management

1. Receivers MAY override the requested keepAlive duration.
2. Receivers MUST include the actual keepAlive duration (or null for unlimited) in tasks/get responses.
3. After a task reaches a terminal status (completed, failed, or cancelled) and its keepAlive duration has elapsed, receivers MAY delete the task and its results.
4. Receivers MAY include a pollFrequency value (in milliseconds) in tasks/get responses to suggest polling intervals. Requestors SHOULD respect this value when provided.

4.6. Result Retrieval

1. Receivers MUST only return results from tasks/result when the task status is completed.
2. Receivers MUST return an error if tasks/result is called for a task in any other status.
3. Requestors MAY call tasks/result multiple times for the same task while it remains available.

4.7. Associating Task-Related Messages

1. All requests, notifications, and responses related to a task MUST include the modelcontextprotocol.io/related-task key in their _meta, with the value set to an object with a taskId matching the associated task ID.
2. For example, an elicitation that a task-augmented tool call depends on MUST share the same related task ID with that tool call's task.

4.8. Task Cancellation

1. When a receiver receives a notifications/cancelled notification for the JSON-RPC request ID of a task-augmented request, the receiver SHOULD immediately move the task to the cancelled status and cease all processing associated with that task.
2. Due to the asynchronous nature of notifications, receivers MAY not cancel task processing instantaneously. Receivers SHOULD make a best-effort attempt to halt execution as quickly as possible.
3. If a notifications/cancelled notification arrives after a task has already reached a terminal status (completed, failed, cancelled, or unknown), receivers SHOULD ignore the notification.
4. After a task reaches cancelled status and its keepAlive duration has elapsed, receivers MAY delete the task and its metadata.
5. Requestors MAY send notifications/cancelled at any time during task execution, including when the task is in input_required status. If a task is cancelled while in input_required status, receivers SHOULD also disregard any pending responses to associated requests.
6. Because notifications do not provide confirmation of receipt, requestors SHOULD continue to poll with tasks/get after sending a cancellation notification to confirm the task has transitioned to cancelled status. If the task does not transition to cancelled within a reasonable timeframe, requestors MAY assume the cancellation was not processed.

4.9. Task Listing

1. Receivers SHOULD use cursor-based pagination to limit the number of tasks returned in a single response.
2. Receivers MUST include a nextCursor in the response if more tasks are available.
3. Requestors MUST treat cursors as opaque tokens and not attempt to parse or modify them.
4. If a task is retrievable via tasks/get for a requestor, it MUST be retrievable via tasks/list for that requestor.

4.10 Task Deletion

1. Receivers MAY accept or reject delete requests for any task at their discretion.
2. If a receiver accepts a delete request, it SHOULD delete the task and all associated results and metadata.
3. Receivers MAY choose not to support deletion at all, or only support deletion for tasks in certain statuses (e.g., only terminal statuses).
4. Requestors SHOULD delete tasks containing sensitive data promptly rather than relying solely on keepAlive expiration for cleanup.

5. Message Flow

https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1686#issuecomment-3452378176

6. Data Types

Task

A task represents the execution state of a request. The task metadata includes:

• taskId: Unique identifier for the task
• keepAlive: Time in milliseconds that results will be kept available after completion
• pollFrequency: Suggested time in milliseconds between status checks
• status: Current state of the task execution

Task Status

Tasks can be in one of the following states:

• submitted: The request has been received and queued for execution
• working: The request is currently being processed
• input_required: The request is waiting on additional input from the requestor
• completed: The request completed successfully and results are available
• failed: The task lifecycle itself encountered an error, unrelated to the associated request logic
• cancelled: The request was cancelled before completion
• unknown: A terminal fallback state for unexpected error conditions when the receiver cannot determine the actual task state

Task Metadata

When augmenting a request with task execution, the modelcontextprotocol.io/task key is included in _meta:

{
  "modelcontextprotocol.io/task": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "keepAlive": 60000
  }
}

Fields:

• taskId (string, required): Client-generated unique identifier for the task
• keepAlive (number, optional): Requested duration in milliseconds to retain results after completion

Task Creation Notification

When a receiver creates a task, it sends a notifications/tasks/created notification to signal that the task is ready for polling. The notification has empty params, with the task ID conveyed through the modelcontextprotocol.io/related-task metadata key:

{
  "jsonrpc": "2.0",
  "method": "notifications/tasks/created",
  "params": {
    "_meta": {
      "modelcontextprotocol.io/related-task": {
        "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
      }
    }
  }
}

This notification enables requestors to begin polling without encountering race conditions where the task might not yet exist on the receiver.

Task Get Request

The tasks/get request retrieves the current state of a task:

{
  taskId: string; // The task identifier to query
}

Task Get Response

The tasks/get response includes:

{
  taskId: string; // The task identifier
  status: TaskStatus; // Current task state
  keepAlive: number | null; // Actual retention duration in milliseconds, null for unlimited
  pollFrequency?: number; // Suggested polling interval in milliseconds
  error?: string; // Error message if status is "failed"
}

Task Result Request

The tasks/result request retrieves the result of a completed task:

{
  taskId: string; // The task identifier to retrieve results for
}

Task Result Response

The tasks/result response returns the original result that would have been returned by the request:

{
  // The structure matches the result type of the original request
  // For example, a tools/call task would return CallToolResult structure
  [key: string]: unknown;
}

The result structure depends on the original request type. The receiver returns the same result structure that would have been returned if the request had been executed without task augmentation.

Task List Request

The tasks/list request retrieves a list of tasks:

{
  cursor?: string; // Optional cursor for pagination
}

Task List Response

The tasks/list response includes:

{
  tasks: Array<{
    taskId: string;           // The task identifier
    status: TaskStatus;       // Current task state
    keepAlive: number | null; // Retention duration in milliseconds, null for unlimited
    pollFrequency?: number;   // Suggested polling interval in milliseconds
    error?: string;           // Error message if status is "failed"
  }>;
  nextCursor?: string;        // Cursor for next page, absent if no more results
}

Related Task Metadata

All requests, responses, and notifications associated with a task MUST include the modelcontextprotocol.io/related-task key in _meta:

{
  "modelcontextprotocol.io/related-task": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840"
  }
}

This associates messages with their originating task across the entire request lifecycle.

7. Error Handling

Tasks use two error reporting mechanisms:

1. Protocol Errors: Standard JSON-RPC errors for protocol-level issues
2. Task Execution Errors: Errors in the underlying request execution, reported through task status

7.1. Protocol Errors

Receivers MUST return standard JSON-RPC errors for the following protocol error cases:

• Invalid or nonexistent taskId in tasks/get, tasks/list, or tasks/result: -32602 (Invalid params)
• Invalid or nonexistent cursor in tasks/list: -32602 (Invalid params)
• Request with a taskId that was already used for a different task (if the receiver validates task ID uniqueness): -32602 (Invalid params)
• Attempting to retrieve result when task is not in completed status: -32602 (Invalid params)
• Internal errors: -32603 (Internal error)

Receivers SHOULD provide informative error messages to describe the cause of errors.

Example: Task not found

{
  "jsonrpc": "2.0",
  "id": 70,
  "error": {
    "code": -32602,
    "message": "Failed to retrieve task: Task not found"
  }
}

Example: Task expired

{
  "jsonrpc": "2.0",
  "id": 71,
  "error": {
    "code": -32602,
    "message": "Failed to retrieve task: Task has expired"
  }
}

NOTE: Receivers are not obligated to retain task metadata indefinitely. It is compliant behavior for a receiver to return a "not-found" error if it has purged an expired task.

Example: Result requested for incomplete task

{
  "jsonrpc": "2.0",
  "id": 72,
  "error": {
    "code": -32602,
    "message": "Cannot retrieve result: Task status is 'working', not 'completed'"
  }
}

Example: Duplicate task ID (if receiver validates uniqueness)

{
  "jsonrpc": "2.0",
  "id": 73,
  "error": {
    "code": -32602,
    "message": "Task ID already exists: 786512e2-9e0d-44bd-8f29-789f320fe840"
  }
}

7.2. Task Execution Errors

When the underlying request fails during execution, the task moves to the failed status. The tasks/get response SHOULD include an error field with details about the failure:

{
  taskId: string;
  status: "failed";
  keepAlive: number | null;
  pollFrequency?: number;
  error?: string;  // Description of what went wrong
}

Example: Task with execution error

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "status": "failed",
    "keepAlive": 30000,
    "error": "Tool execution failed: API rate limit exceeded"
  }
}

For tasks that wrap requests with their own error semantics (like tools/call with isError: true), the task should still reach completed status, and the error information is conveyed through the result structure of the original request type.

8. Security Considerations

8.1. Task Isolation and Access Control

1. Receivers SHOULD scope task IDs to prevent unauthorized access:
   1. Bind tasks to the session that created them (if sessions are supported)
   2. Bind tasks to the authentication context (if authentication is used)
   3. Reject tasks/get, tasks/list, or tasks/result requests for tasks from different sessions or auth contexts
2. Receivers that do not implement session or authentication binding SHOULD document this limitation clearly, as task results may be accessible to any requestor that can guess the task ID.
3. Receivers SHOULD implement rate limiting on:
   1. Task creation to prevent resource exhaustion
   2. Task status polling to prevent denial of service
   3. Task result retrieval attempts
   4. Task listing requests to prevent denial of service

8.2. Resource Management

WARNING: Task results may persist longer than the original request execution time. For sensitive operations, requestors should carefully consider the security implications of extended result retention and may want to retrieve results promptly and request shorter keepAlive durations.

1. Receivers SHOULD:
   1. Enforce limits on concurrent tasks per requestor
   2. Enforce maximum keepAlive durations to prevent indefinite resource retention
   3. Clean up expired tasks promptly to free resources
2. Receivers SHOULD:
   1. Document maximum supported keepAlive duration
   2. Document maximum concurrent tasks per requestor
   3. Implement monitoring and alerting for resource usage

8.3. Audit and Logging

1. Receivers SHOULD:
   1. Log task creation, completion, and retrieval events for audit purposes
   2. Include session/auth context in logs when available
   3. Monitor for suspicious patterns (e.g., many failed task lookups, excessive polling)
2. Requestors SHOULD:
   1. Log task lifecycle events for debugging and audit purposes
   2. Track task IDs and their associated operations

Rationale

Design Decision: Generic Task Primitive

The decision to implement tasks as a generic request augmentation mechanism (rather than tool-specific or method-specific) was made to maximize protocol simplicity and flexibility.

Tasks are designed to work with any request type in the MCP protocol, not just tool calls. This means that resources/read, prompts/get, sampling/createMessage, and any future request types can all be augmented with task metadata. This approach provides significant benefits over a tool-specific design.

From a protocol perspective, this design eliminates the need for separate task implementations per request type. Instead of defining different async patterns for tools versus resources versus prompts, a single set of task management methods (tasks/get and tasks/result) works uniformly across all request types. This uniformity reduces cognitive load for implementers and creates a consistent experience for applications using the protocol.

The generic design also provides implementation flexibility. Servers can choose which requests support task augmentation without requiring protocol changes or version negotiation. If a server doesn't support tasks for a particular request type, it simply ignores the task metadata and processes the request normally. This allows servers to add task support to requests incrementally, starting with high-value operations and expanding over time based on actual usage patterns.

Architecturally, tasks are treated as metadata rather than a separate execution model. They augment existing requests rather than replacing them. The original request/response flow remains intact—the request still gets a response eventually. Tasks simply provide an additional polling-based mechanism for result retrieval. This design ensures that related messages (such as elicitations during task execution) can be associated consistently via the modelcontextprotocol.io/related-task metadata key, regardless of the underlying request type.

Design Decision: Metadata-Based Augmentation

Using _meta for task information rather than dedicated request parameters was chosen to maintain a clear separation of concerns between request semantics and execution tracking.

Task information is fundamentally orthogonal to request semantics. The task ID and keepAlive duration don't affect what the request does—they only affect how the result is retrieved and retained. A tools/call request performs the same operation whether or not it includes task metadata. The task metadata simply provides an alternative mechanism for accessing the result.

By placing task information in _meta, we create a clear architectural boundary between "what to execute" (request parameters) and "how to track execution" (task metadata). This boundary makes it easier for implementers to reason about the protocol. Request parameters define the operation being performed, while metadata provides orthogonal concerns like progress tracking, task management, and other execution-related information.

This approach also provides natural backward compatibility. Servers that don't support tasks can ignore the _meta content without breaking request processing. The request parameters remain valid and complete, so the operation can proceed normally. This means no protocol version negotiation is required—the new functionality is purely additive and non-disruptive.

SDKs can provide ergonomic abstractions over the task primitive while maintaining the separation of concerns, for example:

// === MCP SDK (Pseudocode based loosely on modelcontextprotocol/typescript-sdk) ===

/**
 * NEW: A request that resolves to a result, either directly or by polling a task.
 */
class PendingRequest<TResult> {
  constructor(readonly protocol: Protocol, readonly result: Promise<TResult>, readonly taskId?: string) {}

  /**
   * Waits for a result, calling onTaskStatus if provided and a task was created.
   */
  async result({ onTaskStatus }): Promise<TResult> => {
    if (!onTaskStatus || !this.taskId) {
      // No task listener or task ID provided, just block for the result
      return await result;
    }

    // Whichever is successful first (or a failure if all fail) is returned.
    return Promise.any([
      result, // Blocks for result
      (async () => {
        // Blocks for a notifications/tasks/created with the provided task ID
        await this.protocol.waitForTask(this.taskId);
        return await taskHandler(this.taskId);
      })(),
    ]);
  }

  /**
   * Encapsulates polling for a result, calling onTaskStatus after querying the task.
   */
  private async taskHandler({ onTaskStatus }): Promise<TResult> => {
    // Poll for completion
    let task: Task;
    do {
      task = await this.protocol.getTask(this.taskId);
      await onTaskStatus(task);
      await sleep(task.pollFrequency ?? DEFAULT_POLLING_INTERNAL);
    } while (!task.isTerminal());

    // Process result
    return await this.protocol.getTaskResult(this.taskId);
  }
}

/**
 * Simplified/partial client session implementation for illustration purposes.
 * Extends a base class it shares with the server.
 */
class Client extends Protocol {
  /**
   * Existing request method, but with most implementation refactored to beginCallTool
   */
  async callTool<TResult>(
    params: CallToolRequest['params'],
    resultSchema: Schema<TResult>,
  ) {
    // Existing request methods can be changed to reuse new methods exposed for
    // separating request/response flows.
    const request = await this.beginCallTool(params, resultSchema);
    return request.result();
  }

  /**
   * NEW: Low-level method that starts a tool call and returns a PendingRequest
   * object for more granular control.
   */
  async beginCallTool<TResult>(
    params: CallToolRequest['params'],
    resultSchema: Schema<TResult>,
  ) {
    const request = await this.beginRequest({ method: 'tools/call', params }, resultSchema, options);
    return request;
  }
}

// === HOST APPLICATION ===

// Begin a tool call with task support
const pending: PendingRequest<CallToolResult> = await client.beginCallTool(
  {
    name: "analyze_dataset",
    arguments: { dataset: "large_file.csv" },
  },
  CallToolResultSchema,
  {
    keepAlive: 3600000,
  },
);

// Client code can assume tasks are supported, and the fallback case can be handled internally
const result = await pending.result({
  onTaskStatus: async (task) => {
    await sendLatestStateSomewhere(task);
  },
});

As the design does not alter the basic request semantics, the existing form would continue to work as well:

const result = await client.callTool(
  {
    name: "analyze_dataset",
    arguments: { dataset: "large_file.csv" },
  },
  CallToolResultSchema,
);

Design Decision: Client-Generated Task IDs

The choice to have clients generate task IDs rather than having servers assign them provides several critical benefits:

Idempotency and Fault Tolerance: The primary benefit is enabling idempotent task creation. When a client generates the task ID, it can safely retry a task-augmented request if it doesn't receive a response, knowing that the server will recognize the duplicate task ID and return an error. This is essential for reliable operation over unreliable networks:

• If a request times out, the client can safely retry without creating duplicate tasks
• If a connection drops before the response arrives, the client can reconnect and retry
• The server validates task ID uniqueness and returns an error for duplicates, confirming whether the task was created

With server-generated task IDs, a timeout or connection failure creates uncertainty—the client doesn't know whether the task was created, and has no safe way to retry without potentially creating duplicate tasks.

Simplicity for Clients: Client-generated task IDs simplify the client's implementation by eliminating the need to correlate the initial response with a task identifier. The client can immediately begin polling for task status using the task ID it generated, without needing to parse the response to extract a server-assigned identifier. This is particularly valuable for asynchronous programming models where the client may want to store the task ID before the response arrives.

Trade-offs for Servers: The main trade-off is that servers wrapping existing workflow systems with their own task identifiers will generally handle this by maintaining a mapping between the client-provided task IDs and the underlying system's identifiers. For example, an MCP server wrapping AWS Step Functions might receive a client-generated task ID like "client-abc-123" and need to track that it corresponds to Step Functions execution ARN "arn:aws:states:...:exec-xyz".

This requires:

• Persistent storage for the task ID mapping (typically a simple key-value store)
• Maintaining the mapping for the task's keepAlive duration
• Handling mapping lookups for task status and result retrieval

However, this complexity is typically minor compared to the overall work of integrating an existing workflow system into MCP. Most workflow systems already require state management for tracking execution, and maintaining a task ID mapping is a straightforward addition. The mapping structure is simple (client task ID maps to an internal identifier), and can be implemented using existing databases or key-value stores such a server likely already uses for other state management.

Design Decision: Task Creation Notification

The decision to use a notifications/tasks/created notification rather than altering the response semantics (as #1391 proposed) acknowledges the asynchronous nature of task creation and enables efficient race patterns between task-based polling and traditional request/response flows.

When a server creates a task, it must signal to the client that the task is ready for polling. There are at least two possible approaches: (1) the initial request could return synchronously with task metadata, or (2) the server could send a notification. This proposal uses notifications for several key reasons:

1. Notifications enable fire-and-forget request processing. The server can accept the request, begin processing it, and send the notification once the task is created, without needing to block the initial request/response cycle. This is particularly important for servers that dispatch work to background systems or queues—they can acknowledge the request immediately and send the notification once the background system confirms task creation.
2. Notifications support the race pattern that enables graceful degradation. Clients can race between waiting for the original request's response and waiting for the notifications/tasks/created notification. If the server doesn't support tasks, no notification arrives and the original response wins. If the server does support tasks, the notification typically arrives first (or approximately simultaneously), enabling polling to begin. A synchronous response would force clients to wait for the response before knowing whether to poll or not.
3. Notifications avoid ambiguity with existing protocol semantics. If the initial request response included task metadata and the client then polled for results, it would change the implied meaning of existing notification types:
   1. Progress notifications: The current MCP specification requires that progress notifications reference tokens that "are associated with an in-progress operation." While "operation" is not formally defined, the implied understanding is that an operation is bounded by a request/response pair—progress notifications stop when the response is sent. With a synchronous response containing task metadata, progress notifications would need to continue while the task executes, expanding the implied meaning of "operation" to include asynchronous tasks that outlive the original request/response cycle. The notification-based approach avoids this semantic expansion by keeping progress notifications tied to the initial request's lifecycle, while future task-based progress can be cleanly associated via modelcontextprotocol.io/related-task metadata. We recommend that a future SEP clarify the definition of "operation" in the progress specification.
   2. Cancellation semantics: With the notification-based approach, notifications/cancelled clearly targets the original request ID and causes the associated task to move to cancelled status, maintaining a clean separation between request cancellation and task lifecycle management.

While the notification is required by the specification for servers that create tasks, there are edge cases where it may be unavailable:

• sHTTP without stream support: In environments where either the client or the server does not support SSE streams, notifications cannot be delivered. In such cases, clients may choose to proactively poll with tasks/get using exponential backoff, though this is nonstandard and may result in unnecessary polling attempts if the server doesn't support tasks.
• Degraded connection scenarios: If the notification is lost in transit, clients should implement reasonable timeout behavior and fall back to the original response.

The standard and recommended approach is to wait for the notifications/tasks/created notification before beginning polling. Proactive polling without waiting for the notification should be considered a fallback mechanism for constrained environments only.

Design Decision: No Capabilities Declaration

Unlike other protocol features such as tools, resources, and prompts, tasks do not require capability negotiation. This decision was made to enable graceful degradation and per-request flexibility.

Task support can be determined implicitly through usage rather than explicitly through capability declarations. When a client sends a task-augmented request, the server will process it according to its capabilities. If the server doesn't support tasks for that request type, it simply ignores the task metadata and returns the result normally through the original request/response flow. The client can then detect the lack of task support by attempting to call tasks/get and handling any errors that result.

This approach eliminates the need for complex handshakes or feature detection protocols. Clients can optimistically try task augmentation and gracefully fall back to direct response handling if needed. This makes the protocol more resilient and easier to implement.

Additionally, this design provides per-request flexibility that would be difficult to express through capabilities. A server might support tasks on some request types but not others, or support might vary based on runtime conditions such as resource availability or load. Requiring granular capability declarations per request type would significantly complicate the protocol without providing substantial benefits. The implicit detection model is simpler and more flexible.

Alternative Designs Considered

Tool-Specific Async Execution: An earlier version of this proposal (#1391) focused specifically on tool calls, introducing an invocationMode field on tool definitions to mark tools as supporting synchronous, asynchronous, or both execution modes. This approach would have added dedicated fields to the tool call request and response structures, with server-side capability declarations to indicate support for async tool execution.

While this design would have addressed the immediate need for long-running tool calls, it was rejected in favor of the more general task primitive for several reasons. First, it artificially limited the async execution pattern to tools when other request types have similar needs. Resources can be expensive to read, prompts can require complex processing, and sampling requests may involve lengthy user interactions. Creating separate async patterns for each request type would lead to protocol fragmentation and inconsistent implementation patterns.

Second, the tool-specific approach required more complex capability negotiation and version handling. Servers would need to filter tool lists based on client capabilities, and SDKs would need to manage different invocation patterns for sync versus async tools. This complexity would ripple through every layer of the implementation stack.

Finally, the tool-specific design didn't address the broader architectural need for deferred result retrieval across all MCP request types. By generalizing to a task primitive that augments any request, this proposal provides a consistent pattern that can be applied uniformly across the protocol. More importantly, this foundation is extensible to future protocol messages and features such as subtasks, making it a more appropriate building block for the protocol's evolution.

Transport-Layer Solutions: An alternative approach would be to solve for this purely at the transport layer, without introducing a new data-layer primitive. Several proposals (#1335, #1442, #1597) address transport-specific concerns such as connection resilience, request retry semantics, and stream management for sHTTP. These are valuable improvements that can mitigate many scaling and reliability challenges associated with requests that may take extended time to complete.

However, transport-layer solutions alone are insufficient for the use cases this SEP addresses. Even with perfect transport-layer reliability, several data-layer concerns remain:

First, servers and clients need a way to communicate expectations about execution patterns. Without this, host applications cannot make informed decisions about UX patterns—should they block, show a spinner, or allow the user to continue working? An annotation alone could signal that a request might take extended time, but provides no mechanism to actively check status or retrieve results later.

Second, transport-layer solutions cannot provide visibility into the execution state of a request that is still in progress. If a request stops sending progress notifications, the client cannot distinguish between "the server is doing expensive work" and "the request was lost." Transport-level retries can confirm the connection is alive, but cannot answer "is this specific request still executing?" This visibility is critical for operations where users need confidence their work is progressing.

Third, different transports would require different mechanisms for these concerns. The sHTTP proposals adjust stream management and retry semantics to fulfill these requirements, but stdio has no equivalent extension points. This creates transport-specific fragmentation where implementers must solve the same problems differently depending on their choice of transport. Data-layer operations provides consistent semantics across all transports.

Finally, deferred result retrieval and active status checks are data-layer concerns that cannot be addressed by transport improvements alone. The ability to retrieve a result multiple times, specify retention duration, and handle cleanup is orthogonal to how the underlying messages are delivered.

Resource-Based Approaches: Another possible approach would be to leverage existing MCP resources for tracking long-running operations. For example, a tool could return a linked resource that communicates operation status, and clients could subscribe to that resource to receive updates when the operation completes. This would allow servers to represent task state using the resource primitive, potentially with annotations for suggested polling frequency.

While this approach is technically feasible and servers remain free to adopt such conventions, it suffers from similar limitations as the tool-splitting pattern described in the Motivation section. Like the start_tool and get_tool convention, a resource-based tracking system would be convention-based rather than standardized, creating several challenges:

The most fundamental issue is the lack of a consistent way for clients to distinguish between ordinary resources (meant to be exposed to models) and status-tracking resources (meant to be polled by the application). Should a status resource be presented to the model? How should the client correlate a returned resource with the original tool call? Without standardization, different servers would implement different conventions, forcing clients/hosts/models to handle each server's particular approach. Extending resources with task-like semantics (such as polling frequency, keepalive durations, and explicit status states) would create a new and distinct purpose for resources that would be difficult to distinguish from their existing purpose as model-accessible content.

The resource subscription model has one additional issue: as it is push-based, it requires clients to wait for notifications of resource changes rather than actively polling for status. While this works for some use cases, it doesn't address scenarios where clients need to actively check status—for example, proactively and deterministically checking if work is still progressing, which is the original intent of this proposal.

The task primitive addresses these concerns by providing a standardized, protocol-level mechanism specifically designed for this use case, with consistent semantics that any client can leverage without host applications needing to understand server-specific conventions. While resource-based tracking remains possible for servers that prefer it and/or are already using it, this SEP provides a first-class alternative that solves the broader set of requirements identified previously.

Backward Compatibility

This SEP introduces no backward incompatibilities. All existing MCP functionality remains unchanged:

Compatibility Guarantees:

• Existing requests work identically with or without task metadata
• Servers that don't understand tasks process requests normally
• No protocol version negotiation required
• No capability declarations needed

Graceful Degradation:

• Clients race between waiting for the original request's response and waiting for the notifications/tasks/created notification followed by polling
• Whichever completes first (original response or task-based retrieval) is used by the client
• If a server doesn't support tasks, no notifications/tasks/created is sent, and the original request's response is used
• If a server supports tasks, the notifications/tasks/created notification is sent, enabling the client to begin polling for results
• This race pattern ensures graceful degradation without requiring capability negotiation or version detection
• Partial support is possible—servers can support tasks on some requests but not others

Adoption Path:

• Servers can implement task support incrementally, starting with high-value request types
• Clients can opportunistically use tasks where supported
• No coordination required between client and server updates

Future Work

The task primitive introduced in this SEP provides a foundation for several important extensions that will enhance MCP's workflow capabilities.

Push Notifications

While this SEP focuses on client-driven polling, future work could introduce server-initiated notifications for task state changes. This would be particularly valuable for operations that take hours or longer, where continuous polling becomes impractical.

A notification-based approach would allow servers to proactively inform clients when:

• A task completes or fails
• A task reaches a milestone or significant state transition
• A task requires input (complementing the input_required status)

This could be implemented through webhook-style mechanisms or persistent notification channels, depending on the transport capabilities. The proposed task ID and status model provides the necessary infrastructure for servers to identify which tasks warrant notifications and for clients to correlate notifications with their outstanding tasks.

Intermediate Results

The current task model returns results only upon completion. Future extensions could enable tasks to report intermediate results or progress artifacts during execution. This would support use cases where servers can produce partial outputs before final completion, such as:

• Streaming analysis results as they become available
• Reporting completed phases of multi-step operations
• Providing preview data while full processing continues

Intermediate results would build on the proposed task ID association mechanism, allowing servers to send multiple result notifications or response messages tied to the same task ID throughout its lifecycle.

Nested Task Execution

A significant future enhancement is support for hierarchical task relationships, where a task can spawn subtasks as part of its execution. This would enable complex, multi-step workflows orchestrated by the server.

In a nested task model, a server could:

• Create subtasks in response to a parent task reaching a state that requires additional operations
• Communicate subtask requirements to the client, potentially including required tool calls or sampling requests
• Track subtask completion and use subtask results to advance the parent task
• Maintain provenance through task ID hierarchies, showing the relationship between parent and child tasks

For example, a complex analysis task might spawn several subtasks for data gathering, each represented by its own task ID but associated with the parent task. The parent task would remain in a pending state (potentially in a new tool_required status) until all required subtasks complete.

This hierarchical model would support sophisticated server-controlled workflows while maintaining the client's ability to monitor and retrieve results at any level of the task tree.

{
  taskId: string;
  status: TaskStatus;
  keepAlive: number | null;
  pollFrequency?: number;
  error?: string;

  // Extensions for nested tasks
  parentTaskId?: string;        // ID of parent task, if this is a subtask
  childTasks?: Array<{          // Subtasks required by this task
    taskId: string;             // Pre-generated task ID for the subtask
    toolName: string;           // Tool to call for this subtask
    arguments?: object;         // Arguments for the tool call
  }>;
}

SEP-1699 Support SSE polling via server-side disconnect

Final · Standards Track · Created 2025-10-22

• Status: Final
• Type: Standards Track
• Created: 2025-10-22
• Author(s): Jonathan Hefner (@jonathanhefner)
• Issue: #1699

Abstract

This SEP proposes changes to the Streamable HTTP transport in order to mitigate issues regarding long-running connections and resumability.

Motivation

The Streamable HTTP transport spec does not allow servers to close a connection while computing a result. In other words, barring client-side disconnection, servers must maintain potentially long-running connections.

Specification

When a server starts an SSE stream, it MUST immediately send an SSE event consisting of an id and an empty data string in order to prime the client to reconnect with that event ID as the Last-Event-ID.

Note that the SSE standard explicitly permits setting data to an empty string, and says that the appropriate client-side handling is to record the id for Last-Event-ID but otherwise ignore the event (i.e., not call the event handler callback).

At any point after the server has sent an event ID to the client, the server MAY disconnect at will. Specifically, this part of the MCP spec will be changed from:

The server SHOULD NOT close the SSE stream before sending the JSON-RPC response for the received JSON-RPC request

To:

The server MAY close the connection before sending the JSON-RPC response if it has sent an SSE event with an event ID to the client

If a server disconnects, the client will interpret the disconnection the same as a network failure, and will attempt to reconnect. In order to prevent clients from reconnecting / polling excessively, the server SHOULD send an SSE event with a retry field indicating how long the client should wait before reconnecting. Clients MUST respect the retry field.

Rationale

Servers may disconnect at will, avoiding long-running connections. Sending a retry field will prevent the client from hammering the server with inappropriate reconnection attempts.

Backward Compatibility

• New Client + Old Server: No changes. No backward incompatibility.
• Old Client + New Server: Client should interpret an at-will disconnect the same as a network failure. retry field is part of the SSE standard. No backward incompatibility if client already implements proper SSE resuming logic.

Additional Information

This SEP supersedes (in part) SEP-1335.

SEP-1730 SDKs Tiering System

Final · Standards Track · Created 2025-10-29

• Status: Final
• Type: Standards Track
• Created: 2025-10-29
• Author(s): Inna Harper, Felix Weinberger
• Issue: #1730

Abstract

This SEP proposes a tiering system for Model Context Protocol (MCP) SDKs to establish clear expectations for feature support, maintenance commitments, and quality standards. The system defines three tiers of SDK support with objective, measurable criteria for classification.

Motivation

The MCP ecosystem needs SDK harmonization to help users make informed decisions. Users currently face challenges:

• Feature Support Uncertainty: No standardized way to know which SDKs support specific MCP features (OAuth, client/server/system features, like sampling, transports)
• Maintenance Expectations: Unclear commitment levels for bug fixes, security patches, and feature updates
• Implementation Timelines: No visibility into when SDKs will support new protocol versions and features

Specification

Tier Definitions

Tier 1: fully supported

SDKs in this tier provides full protocol implementation and is well supported

Requirements:

• Feature complete and full support of the protocol
  • All conformance tests pass
  • New protocol features before the new spec version release. (There is two week window between Release Candidate and the new protocol version release)
• SDK maintenance
  • Acknowledge and triage issues within two business days
  • Resolve security and critical bugs within seven days
  • Stable release and SDK versioning clearly documented
• Documentation
  • Comprehensive documentation with examples for all features
  • Published dependency update policy

Tier 2: commitment to be fully supported

SDKs with established implementations actively working toward full protocol support.

Requirements:

• Feature complete and full support of the protocol
  • 80% of conformance tests pass
  • New protocol features implemented within six months
• SDK maintenance
  • Active issue tracking and management
  • At least one stable release
• Documentation
  • Basic documentation covering core features
  • Published dependency update policy
• Commitment to move to Tier1
  • Published roadmap showing intent to achieve Tier 1 or, if SDK will remain in Tier 2 indefinitely, a transparent roadmap about the direction of the SDK and reasons for not being feature complete

Tier 3: Experimental

Early-stage or specialized SDKs exploring the protocol space.

Characteristics:

• No feature completeness guarantees
• No stable release requirement
• May focus on specific use cases or experimental features
• No timeline commitments for updates
• Suitable for niche implementations that may remain at this tier

Conformance Testing

All SDKs must undergo conformance testing using protocol trace validation: for details see Conformance Testing RFC (forthcoming). This SEP is not focusing on Conformance testing. For the initial version of tiering, we will go with the simplified version where we would have an Example server for each SDK and run simplified conformance tests against those.

Compliance Scoring:

• SDKs receive a percentage score based on test results
• Scores can be displayed as badges (e.g., "90% MCP Compliant")
• Tier 1: 100% compliance required
• Tier 2: 80% compliance required
• Tier 3: No minimum requirement

Tier Advancement Process

1. Self-Assessment: Maintainers evaluate their SDK against tier criteria
2. Application: Submit tier advancement request with evidence
3. Review: Community review period (2 weeks)
4. Validation: Automated conformance testing, github stats on issues
5. Decision: Tier assignment by MCP maintainers

Tier Relegation Process

1. Auto validation:
   1. compliance tests continuously not passing for four week for Tier 1
   2. 20% of compliance tests continuously not passing for four week for Tier 2
2. Issues:
   1. Issues are not addressed within two months

Requirements matrix

Rationale

Why Three Tiers?

• Tier 1 ensures users have well supported, fully-featured SDK
• Tier 2 provides a clear pathway for improving SDKs
• Tier 3 allows experimentation without creating barriers to entry

Why Time-Based Commitments?

While the community raised concerns about rigid timelines, they provide:

• Clear expectations for users
• Measurable goals for maintainers
• Flexibility through tier progression

Why Not Just Feature Matrices?

Feature matrices alone don't communicate:

• Maintenance commitment
• Quality standards
• Support expectations

The tiering system combines feature support with quality guarantees.

Alternatives Considered

1. Feature Matrix Only

Rejected because: Doesn't communicate maintenance commitments or quality standards

2. Percentage-Based Scoring

Rejected because: Too granular and doesn't capture qualitative aspects like support

3. Properties-Based System

Rejected because: Multiple overlapping properties could confuse users

4. Latest Version Listing Only

Rejected because: Simply listing "supports MCP date" fails to capture critical information:

• Version support may be incomplete (e.g., supports <date> except OAuth)
• No indication of maintenance commitment or issue response times
• Lacks information about security patch timelines
• Doesn't communicate dependency update policies
• Version numbers alone don't indicate production readiness

5. No Formal System

Rejected because: Current ad-hoc approach creates uncertainty for users

Backward Compatibility

This proposal introduces a new classification system with no breaking changes:

• Existing SDKs continue to function
• Classification is opt-in initially
• Grace period for existing SDKs to achieve tier status

Security Implications

• Tier 1 SDKs must address security issues within 7 days
• All tiers encouraged to follow security best practices
• Conformance tests include security validation

Implementation Plan

• Finalize simplified conformance test suite - Nov 4, 2025
• SDK maintainers self-assess and apply for tiers - Nov 14, 2025
• Initial tier assignments - before the November spec release
• Implement full compliance tests
• Implement automatic issue tracking analysis for SDKs

Community Impact

SDK Maintainers

• Clear goals for improvement
• Recognition for quality implementations
• Structured pathway for advancement

SDK Users

• Informed selection of SDKs
• Clear expectations for support
• Confidence in tier 1 implementations

Ecosystem

• Improved overall SDK quality
• Standardized feature support
• Healthy competition between implementations

References

• SDK Maintainer Meeting Notes (#1648)
• SDK Harmonization Goals (#1444)
• Conformance Testing SEP (DRAFT)

Appendix

Simplified conformance tests

While we are working on a comprehensive proposal for conformance testing which will take some time to implement, we want to move forward with at least some automated way to check if SDK has a full set of features. We will start from Servers features set, as we have many more servers than clients and the vast majority of developers using SDKs are Server implementers.

The most straightforward approach is to have an Example Server for each SDK, similar to to Everything Server. Then we will have Conformance Test Client with all the test cases we want to be able to test, for example:

• execute “hello world” tool
• Get prompt
• Get completion
• Get resource template
• Receive notifications

What is needed form SDKs maintainers: implement everything server based on a spec. Spec will look like:

• Tool “say_hello” to return simple text
• Tool “show_image” to return and image
• Tool “tool_with_logging” to return structured output in a format <> and log three events: start, process, end
• Tool "tool_with_notifications" to return structured output in a format <> and have two notifications <>

Given well defined spec for the server and SDK documentation, it should be easy to implement it with the help of any coding agent. We want to check it into each SDKs repo as it will serve as an example for server implementers.

Once each SDK has an Everything server, we will run the Conformance Test Client against it.

SEP-1850 PR-Based SEP Workflow

Final · Process · Created 2025-11-20

• Status: Final
• Type: Process
• Created: 2025-11-20
• Accepted: 2025-11-28, 8 Yes, 0 No, 0 Absent per vote in Discord.
• Author(s): Nick Cooper (@nickcoai), David Soria Parra (@davidsp)
• Sponsor: David Soria Parra (@davidsp)
• PR: https://github.com/modelcontextprotocol/specification/pull/1850

Abstract

This SEP formalizes the pull request-based SEP workflow that stores proposals as markdown files in the seps/ directory of the Model Context Protocol specification repository. The workflow assigns SEP numbers from pull request numbers, maintains version history in Git, and replaces the previous GitHub Issues-based process. This establishes a file-based approach as the canonical way to author, review, and accept SEPs.

Motivation

The issue-based SEP process introduced several challenges:

• Dispersed content: Proposal content was scattered across GitHub issues, linked documents, and pull requests, making review and archival difficult.
• Difficult collaboration: Maintaining long-form specifications in issue bodies made iterative edits and multi-contributor collaboration harder.
• Limited version control: GitHub issues don't provide the same version control capabilities as Git-managed files.
• Unclear status management: The process lacked clear mechanisms for tracking status transitions and ensuring consistency between different sources of truth.

A file-based workflow addresses these issues by:

• Keeping every SEP in version control alongside the specification itself
• Providing Git's built-in review tooling, history, and searchability
• Linking SEP numbers to pull requests to eliminate manual bookkeeping
• Surfacing all discussion in the pull request thread
• Using PR labels in conjunction with file status for better discoverability

Specification

1. Canonical Location

• Every SEP lives in seps/{NUMBER}-{slug}.md in the specification repository
• The SEP number is always the pull request number that introduces the SEP file
• The seps/ directory serves as the single source of truth for all SEPs

2. Author Workflow

1. Draft the proposal in seps/0000-{slug}.md using 0000 as a placeholder number
2. Open a pull request containing the draft SEP and any supporting materials
3. Request a sponsor from the Maintainers list; tag potential sponsors from MAINTAINERS.md
4. After the PR number is known, amend the commit to rename the file to {PR-number}-{slug}.md and update the header (SEP-{PR-number} and PR: #{PR-number})
5. Wait for sponsor assignment: Once a sponsor agrees, they will assign themselves and update the status to Draft

3. Sponsor Responsibilities

A Sponsor is a Core Maintainer or Maintainer who champions the SEP through the review process. The sponsor's responsibilities include:

• Reviewing the proposal and providing constructive feedback
• Requesting changes based on community input
• Managing status transitions by:
  • Ensuring that the Status field in the SEP markdown file is accurate
  • Applying matching PR labels to keep them in sync with the file status
  • Communicating status changes via PR comments
• Initiating formal review when the SEP is ready (moving from Draft to In-Review)
• Raising to Core-Maintainers ensuring the SEP is presented at the Core Maintainer meeting and that author and sponsor present.
• Ensuring quality standards are met before advancing the proposal
• Tracking implementation progress and ensuring reference implementations are complete before Final status

4. Review Flow

Status progression follows: Draft → In-Review → Accepted → Final

Additional terminal states: Rejected, Withdrawn, Superseded, Dormant

Dormant status: If a SEP does not find a sponsor within six months, Core Maintainers may close the PR and mark the SEP as dormant.

Reference implementations must be tracked via linked pull requests or issues and must be complete before marking a SEP as Final.

5. Documentation

• docs/community/sep-guidelines.mdx serves as the contributor-facing instructions
• seps/README.md provides the concise reference for formatting, naming, sponsor responsibilities, and acceptance criteria
• Both documents must reflect this workflow and be kept in sync

6. SEP File Structure

Each SEP must include:

# SEP-{NUMBER}: {Title}

- **Status**: Draft | In-Review | Accepted | Rejected | Withdrawn | Final | Superseded | Dormant
- **Type**: Standards Track | Informational | Process
- **Created**: YYYY-MM-DD
- **Author(s)**: Name <email> (@github-username)
- **Sponsor**: @github-username (or "None" if seeking sponsor)
- **PR**: https://github.com/modelcontextprotocol/specification/pull/{NUMBER}

## Abstract

## Motivation

## Specification

## Rationale

## Backward Compatibility

## Security Implications

## Reference Implementation

7. Status Management via PR Labels

To improve discoverability and filtering:

• Sponsors must apply PR labels that match the SEP status (draft, in-review, accepted, final, etc.)
• Both the markdown Status field and PR labels should be kept in sync
• The markdown file serves as the canonical record (versioned with the proposal)
• PR labels enable easy filtering and searching for SEPs by status
• Only sponsors should modify status fields and labels; authors should request changes through their sponsor

8. Legacy Considerations

• Contributors may optionally open a GitHub Issue for early discussion, but the authoritative SEP text lives in seps/
• Issues should link to the relevant file once a pull request exists
• SEP numbers are derived from PR numbers, not issue numbers

Rationale

Why File-Based?

Storing SEPs as files keeps authoritative specs versioned with the code, mirroring successful processes used by PEPs (Python Enhancement Proposals) and other standards bodies. This approach:

• Provides built-in version control via Git
• Enables standard code review workflows
• Maintains clear history of all changes
• Supports multi-contributor collaboration
• Integrates naturally with the specification repository

Why PR Numbers?

Using pull request numbers:

• Eliminates race conditions around manual numbering
• Creates natural traceability between proposal and discussion
• Prevents number conflicts
• Simplifies the contribution process
• Maintains a single discussion thread for review

Why PR Labels?

Adding PR labels alongside the file status:

• Enables quick filtering of SEPs by status without opening files
• Provides immediate visibility of SEP states in PR lists
• Supports GitHub's search and filter capabilities
• Complements the canonical markdown status field
• Reduces friction for maintainers managing multiple SEPs

Making This the Primary Process

Maintaining two overlapping canonical processes risked divergence and created confusion for contributors. Establishing the file-based approach as the primary method:

• Reduces cognitive overhead for new contributors
• Ensures consistency in the SEP corpus
• Simplifies maintenance for sponsors
• Aligns with industry best practices

Backward Compatibility

• Existing issue-based SEPs remain valid and require no migration
• Historical GitHub Issue links continue to work
• Future SEPs should reference the new file locations in seps/
• Maintainers may optionally backfill historical SEPs into seps/ for archival purposes

Security Implications

No new security considerations beyond the standard code review process for pull requests.

Reference Implementation

• This pull request (#1850) implements the canonical instructions in both seps/README.md and docs/community/sep-guidelines.mdx
• The process has been updated to reflect the PR-based workflow with status management via labels
• This SEP document itself serves as an example of the new format

Vote

This SEP was accepted unanimously by the MCP Core Maintainers with a vote of 8 yes's, 0 no's and 0 absent votes on Friday December 28th, 2025 in a Discord poll.

SEP-1865 MCP Apps - Interactive User Interfaces for MCP

Final · Extensions Track · Created 2025-11-21

• Status: Final
• Type: Extensions Track
• Created: 2025-11-21
• Author(s): Ido Salomon (@idosal), Liad Yosef (@liadyosef), Olivier Chafik (@olivierchafik), Jerome Swannack (@jeromeswannack), Jonathan Hefner (@jonathanhefner), Anton Pidkuiko (@antonpidkuiko), Nick Cooper (@nickcooper), Bryan Ashley (@bryanashley), Alexi Christakis (@alexichristakis)
• Sponsor: None (seeking sponsor)
• PR: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865

Abstract

This SEP proposes an extension to MCP (per SEP-1724) that enables servers to deliver interactive user interfaces to hosts. MCP Apps introduces a standardized pattern for declaring UI resources via the ui:// URI scheme, associating them with tools through metadata, and facilitating bi-directional communication between the UI and the host using MCP's JSON-RPC base protocol. This extension addresses the growing community need for rich, interactive experiences in MCP-enabled applications, maintaining security, auditability, and alignment with MCP's core architecture. The initial specification focuses on HTML resources (text/html;profile=mcp-app) with a clear path for future extensions.

Motivation

MCP lacks a standardized way for servers to deliver rich, interactive user interfaces to hosts. This gap blocks many use cases that require visual presentation and interactivity that go beyond plain text or structured data. As more hosts adopt this capability, the risk of fragmentation and interoperability challenges grows.

MCP-UI has demonstrated the viability and value of MCP apps built on UI resources and serves as a community playground for the UI spec and SDK. Fueled by a dedicated community, it developed the bi-directional communication model and the HTML, external URL, and remote DOM content types. MCP-UI's adopters, including hosts and providers such as Postman, HuggingFace, Shopify, Goose, and ElevenLabs, have provided critical insights and contributions to the community.

OpenAI's Apps SDK, launched in November 2025, further validated the demand for rich UI experiences within conversational AI interfaces. The Apps SDK enables developers to build rich, interactive applications inside ChatGPT using MCP as its backbone.

The architecture of both the Apps SDK and MCP-UI has significantly informed the design of this specification.

However, without formal standardization:

• Servers cannot reliably expect UI support via MCP
• Each host may implement slightly different behaviors
• Security and auditability patterns are inconsistent
• Developers must maintain separate implementations or adapters for different hosts (e.g., MCP-UI vs. Apps SDK)

This SEP addresses the current limitations through an optional, backwards-compatible extension that unifies the approaches pioneered by MCP-UI and the Apps SDK into a single, open standard.

Specification

The full specification can be found at modelcontextprotocol/ext-apps.

At a high level, MCP Apps extends the Model Context Protocol to enable servers to deliver interactive user interfaces to hosts. This extension introduces:

• UI Resources: Predeclared resources using the ui:// URI scheme
• Resource Discovery: Tools reference UI resources via metadata
• Bi-directional Communication: UI iframes communicate with hosts using standard MCP JSON-RPC protocol
• Security Model: Mandatory iframe sandboxing with auditable communication

This specification focuses on HTML content (text/html;profile=mcp-app) as the initial content type, with extensibility for future formats.

As an extension, MCP Apps is optional and must be explicitly negotiated between clients and servers through the extension capabilities mechanism (see Capability Negotiation section in the full specification).

Rationale

Predeclared resources vs. inline embedding

UI is modeled as predeclared resources (ui://), referenced by tools via metadata. This allows:

• Hosts to prefetch templates before tool execution, improving performance
• Separation of presentation (template) from data (tool results), facilitating caching
• Security review of UI resources

Alternatives considered:

• Embedded resources: Current MCP-UI approach, where resources are returned in tool results. Although it's more convenient for server development, it was deferred due to the gaps in performance optimization and the challenges in the UI review process.
• Resource links: Predeclare the resources but return links in tool results. Deferred due to the gaps in performance optimization.

Reusing MCP JSON-RPC instead of a custom protocol

Reuses existing MCP infrastructure (type definitions, SDKs, etc.). JSON-RPC offers advanced capabilities (timeouts, errors, etc.).

Alternatives considered:

• Custom message protocol: Current MCP-UI approach with message types like tool, intent, prompt, etc. These message types can be translated to a subset of the proposed JSON-RPC messages.
• Global API object: Rejected because it requires host-specific injection and doesn't work with external iframe sources. Syntactic sugar may still be added on the server/UI side.

HTML-only MVP

• HTML is universally supported and well-understood
• Simplest security model (standard iframe sandbox)
• Allows screenshot/preview generation (e.g., via html2canvas)
• Sufficient for most observed use cases
• Provides a clear baseline for future extensions

Alternatives considered:

• Include external URLs in MVP: This is one of the easiest content types for servers to adopt, as it's possible to embed regular apps. However, it was deferred due to concerns around model visibility, inability to screenshot content, and review process. It may effectively be supported with the SEP's new externalIframes capability.

Backward Compatibility

The proposal is an optional extension to the core protocol. Existing implementations continue working without changes.

Security Implications

Hosting interactive UI content from potentially untrusted MCP servers requires careful security consideration.

Based on the threat model, MCP Apps proposes the following mitigations:

• Iframe sandboxing: All UI content runs in sandboxed iframes with restricted permissions
• Predeclared templates: Hosts can review HTML content before rendering
• Auditable messages: All UI-to-host communication goes through loggable JSON-RPC
• User consent: Hosts can require explicit approval for UI-initiated tool calls

A full threat model analysis and mitigations are available in the full specification.

Reference Implementation

• MCP-UI client and server SDKs support the patterns proposed in this spec.
• ext-apps repository contains a prototype implementation by Olivier Chafik.

SEP-1913 Trust and Sensitivity Annotations

Draft · Standards Track · Created 2025-06-11

• Status: Draft
• Type: Standards Track
• Created: 2025-06-11
• Author(s): Sam Morrow (@SamMorrowDrums), Rob Reichel (@rreichel3)
• PR: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1913

Imported from upstream. Proposed as modelcontextprotocol#1913 by @SamMorrowDrums on 2025-11-27, where it was still open on 2026-09-25. Accepted into omcp on its technical merit. The text is the author's; only the status, the sponsor field, and documentation links were changed on import.

Reviewed 2026-09-25 — not yet accepted. Held as a draft because no prototype a reviewer can run is cited. Acceptance needs a prototype a reviewer can run, with its setup and the data to run it; Final also needs conformance tests and the reference documentation chapter.

Related Issue: #711

Abstract

This SEP proposes a unified security metadata model for MCP that combines trust annotations (data-in-transit) with action security metadata (tool behavior, including sensitivity categories). Together, these primitives allow clients and servers to track, propagate, and enforce trust boundaries on data as it flows through tool invocations, while also declaring what tools are allowed to do with that data.

The proposal introduces:

1. Extended tool annotations with declarable annotation sets for pre-execution metadata via Tool Resolution
2. Action security metadata describing input destinations, output sources, and real-world outcomes
3. Result annotations for marking data characteristics in tool responses
4. Request annotations for propagating trust context to servers
5. Propagation rules ensuring trust markers persist across session boundaries
6. Malicious activity signaling for security alerting and compliance

This pattern enables:

• Deterministic enforcement through declarative contracts for tool behavior
• Data exfiltration prevention by tracking when sensitive data flows to open-world destinations
• Prompt injection defense by marking untrusted data sources
• Compliance workflows via human-in-the-loop escalation for risky operations
• Attribution tracking for audit trails and provenance
• Pre-execution assessment via integration with Tool Resolution (#1862) for argument-derived annotations

Note: This SEP provides primitives, not a complete security solution. It enables host applications and registries to define situation-specific policies while avoiding over-specification of universal rules.

Reviewed 2026-09-25 — not yet accepted. Held as a draft because no prototype a reviewer can run is cited. Acceptance needs a prototype a reviewer can run, with its setup and data; Final also needs conformance tests and the reference documentation chapter.

This draft incorporates the Action Security Metadata proposal (SEP-2061) by adding inputMetadata and returnMetadata to ToolAnnotations.

Motivation

The Problem with Untracked Data Flow

As MCP adoption grows, data flows across tool boundaries without standardized trust metadata:

1. Indirect Prompt Injection

Data from untrusted sources (web pages, emails, user-generated content) enters the context without markers indicating its origin. An attacker can embed instructions in this data that the model may execute.

Recent research demonstrates the severity: Trail of Bits showed how hidden content in GitHub issues can inject invisible prompt attacks that cause agents to insert backdoors in pull requests. The IBM/Google/Microsoft "Design Patterns for Securing LLM Agents" paper (arXiv:2506.08837) states:

"Once an LLM agent has ingested untrusted input, it must be constrained so that it is impossible for that input to trigger any consequential actions."

2. Data Exfiltration

Sensitive information (credentials, PII, proprietary data) can be passed to tools that write to external destinations. Without declared data classifications and action metadata, clients cannot enforce policies like "don't email private repo content to external addresses."

3. Cross-Organization Boundaries

In multi-organization scenarios, what's "internal" in one context may be "external" in another. Current MCP has no way to express or propagate these distinctions.

4. Compliance Requirements

Regulated industries (healthcare, finance) need audit trails and sensitivity classifications. Without standardized annotations, each implementation reinvents this wheel.

The Problem with Undeclared Tool Actions

MCP today treats all tool calls as equivalent at the protocol level. A tool that reads drafts and a tool that sends emails are indistinguishable (other than the most basic static Annotations), even though their security and privacy implications are radically different. Implementations fall back to heuristics or model inference to decide when to request user consent or block operations.

This creates concrete risks:

• Prompt injection can trigger destructive or irreversible actions using untrusted input.
• Data exfiltration can occur when sensitive data is passed to tools that transmit externally.
• User consent cannot be meaningfully enforced without knowing a tool's real-world impact.
• Distrust by default leads to confirmation fatigue and bad user experience.

Action security metadata provides a declarative contract that describes where inputs go, where outputs originate, and what outcomes the tool can cause. This complements trust annotations, which track data characteristics in transit.

Enabling Security Architecture Patterns

Recent research proposes several design patterns for secure LLM agents. Trust annotations provide the primitives these patterns need at protocol boundaries:

Without protocol-level annotations, each security architecture must reinvent data classification.

Critical: Malicious Activity Detection

MCP servers are increasingly implementing detection for:

• Prompt injection attempts
• Secret/credential leakage
• Anomalous request patterns

Without standardized signaling, these security findings are lost between tool boundaries. The maliciousActivityHint annotation is essential for:

• User/admin alerting in compliance scenarios
• Human-in-the-loop review and escalation
• Audit logging of suspicious activity

Example: Email MCP Scenario

Consider a user asking an AI to: "Take the salary spreadsheet and email it to my accountant"

With annotations:

1. File MCP resolves returnMetadata to indicate internal origin (and sensitivity: "financial" for this path)
2. Email MCP declares inputMetadata.destination: "public" and outcomes: "irreversible"
3. Policy triggers: block, escalate, or require user confirmation

Without trust annotations: The email goes through with no checks.

Specification

Terminology

Agent session (or simply "session" in this SEP): A client-side concept representing a sequence of user interactions where subsequent requests share the same agent context window. This is the conversation or task boundary as perceived by the user—for example, a chat thread in an AI assistant or a task execution in an agentic workflow.

This is distinct from MCP session, which refers to the protocol-level connection between a client and server (as defined in the MCP specification). Trust annotations propagate across an agent session, which may span multiple MCP sessions or interact with multiple MCP servers.

Annotation Types

Extended Tool Annotations

This SEP extends the existing ToolAnnotations interface with trust-related fields. This unified approach means:

• Static declarations: Tools declare the set of annotations they might return in tools/list
• Resolved declarations: tools/resolve selects concrete annotations for specific arguments
• Response declarations: CallToolResult includes annotations describing actual returned data

In tools/list, annotation fields express possible values. For boolean hints, true means the hint may be set; false or omission means it will never be set. For enum-like fields (for example inputMetadata.outcomes), tools MAY declare a set of possible values using an array; tools/resolve and responses SHOULD return a single resolved value.

/**
 * Extended ToolAnnotations with trust and security metadata fields.
 * These fields follow a possible-set → resolved-value pattern:
 * tools/list declares potential annotations, tools/resolve resolves them.
 */
interface ToolAnnotations {
  // Existing hints (unchanged)
  title?: string;
  readOnlyHint?: boolean;
  destructiveHint?: boolean;
  idempotentHint?: boolean;
  openWorldHint?: boolean;

  // NEW: Trust extensions

  /**
   * Indicates detected or suspected malicious activity in the request
   * or response content. Clients SHOULD surface this to users and
   * MAY invoke elicitation for user review.
   */
  maliciousActivityHint?: boolean;

  /**
   * Attribution for data provenance. Lists sources contributing to
   * this response for audit and compliance purposes.
   *
   * Attribution strings SHOULD use URIs that meaningfully identify the source:
   * - MCP server origins: "mcp://server-name.domain/path/to/resource"
   * - HTTPS sources: "https://api.example.com/endpoint"
   * - Known local files with domain context: "local://WORKSTATION.corp.acme.com/path/file"
   * - Anonymous local files (unknown origin): "local:anonymous/path/file"
   * - Organization resources: "urn:org:acme:hr:salaries"
   *
   * Avoid opaque file:// URIs that don't convey meaningful provenance.
   */
  attribution?: string[];

  /**
   * Declarative contract for how the tool handles input data.
   */
  inputMetadata?: InputMetadata;

  /**
   * Declarative contract for the origin and sensitivity of outputs.
   */
  returnMetadata?: ReturnMetadata;
}

Note on openWorldHint: This existing field gains additional meaning in the trust context:

• Tool-level (static): "This tool may access external systems"
• Resolved (via tools/resolve): "This specific operation will access external/untrusted sources"
• Response-level: "This response contains data from untrusted sources"

Examples of untrusted sources requiring openWorldHint: true:

• Web page content (potential invisible prompt injection)
• Email bodies (user-controlled content)
• GitHub issues, PR descriptions, comments (attacker-controlled)
• User-generated content from any platform
• Search results from Bing, Google, or other web searches
• Database query results with user-supplied data

Action Security Metadata

Action security metadata declares a tool's behavioral contract: where inputs may be stored or transmitted, where outputs originate, and what outcomes the tool can cause. These fields live on ToolAnnotations and follow the same possible-set → resolved-value pattern as other tool annotations:

• Static declarations in tools/list describe the set of possible behaviors
• Resolved declarations in tools/resolve select concrete values based on specific arguments

Unlike trust annotations (which describe actual data in transit), action metadata is declarative and describes what the tool is allowed to do with data.

interface InputMetadata {
  /**
   * Where input data may be stored or transmitted.
   */
  destination:
    | "ephemeral"
    | "system"
    | "user"
    | "internal"
    | "public"
    | Array<"ephemeral" | "system" | "user" | "internal" | "public">;

  /**
   * Sensitivity class(es) the tool may accept.
   */
  sensitivity: DataClass | DataClass[];

  /**
   * Real-world impact of invoking the tool.
   */
  outcomes:
    | "benign"
    | "consequential"
    | "irreversible"
    | Array<"benign" | "consequential" | "irreversible">;
}

interface ReturnMetadata {
  /**
   * Origin of returned data.
   */
  source:
    | "untrustedPublic"
    | "trustedPublic"
    | "internal"
    | "user"
    | "system"
    | Array<
        "untrustedPublic" | "trustedPublic" | "internal" | "user" | "system"
      >;

  /**
   * Sensitivity class(es) the tool may return.
   */
  sensitivity: DataClass | DataClass[];
}

type DataClass =
  | "none"
  | "user"
  | "pii"
  | "financial"
  | "credentials"
  | { regulated: { scopes: RegulatoryScope[] } };

type RegulatoryScope = string;

DataClass keeps sensitivity simple for common cases while allowing regulated data to be scoped. The regulated form declares applicable regimes; it does not assert compliance.

RegulatoryScope accepts arbitrary strings. The following are suggested examples for common regimes: GDPR, CCPA, HIPAA, GLBA, PCI-DSS, FERPA, COPPA, SOX.

For action metadata, enum-valued fields MAY be arrays in tools/list to indicate possible values; tools/resolve SHOULD return a single resolved value.

Destination

Specifies where input data may be stored or transmitted.

• ephemeral — Data received will not be stored in any way.
• system — Data is stored by the platform and not accessible to users or developers.
• user — Data is stored and visible only to the end user.
• internal — Data is stored and visible to a restricted internal audience.
• public — Data may be transmitted to or stored in publicly accessible systems.

Outcomes

Describes the real-world impact of invoking the tool.

• benign — No persistent state change outside the tool's execution context, or changes limited to private drafts that are not transmitted or shared.
• consequential — Creates, updates, or deletes persistent state that is visible outside the tool's private context and can be programmatically reversed.
• irreversible — Produces effects that cannot be undone through the same API or that trigger external side effects (e.g., sending messages, deleting data, publishing content).

Source

Indicates the origin of returned data.

• untrustedPublic — Public but unverified sources.
• trustedPublic — Public but curated or verified sources.
• internal — Internal systems or datasets.
• user — User-provided or user-owned data.
• system — Generated or derived by the platform itself.

Result Annotations

Tools MAY include annotations in their results to describe data characteristics:

Clients MAY include annotations in requests to communicate trust context:

interface RequestAnnotations {
  /**
   * Whether prior context includes open-world (untrusted) data.
   */
  openWorldHint?: boolean;

  /**
   * Aggregated attribution from prior context.
   */
  attribution?: string[];
}

Protocol Changes

Tool Call Request Extension

The CallToolRequest params MAY include trust annotations:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_email",
    "arguments": {
      "to": "external@example.com",
      "subject": "Report",
      "body": "..."
    },
    "_meta": {
      "annotations": {
        "attribution": ["mcp://file-server.acme.local/hr/salaries.xlsx"]
      }
    }
  }
}

Tool Call Result Extension

The CallToolResult MAY include trust annotations at the response level:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "File contents..."
      }
    ],
    "_meta": {
      "annotations": {
        "attribution": ["mcp://file-server.acme.local/hr/salaries.xlsx"]
      }
    }
  }
}

Response Annotations Scope

Response annotations describe the entire response as a unit. Servers MUST aggregate annotations across all content:

• openWorldHint: If any content is open-world, the response has that hint
• maliciousActivityHint: If any content is flagged, the response has that hint
• attribution: Union of all sources contributing to the response

Note: Per-item annotations (marking individual content items differently) are explicitly out of scope for this SEP. This simplifies implementation and avoids complexity around item-level tracking. If needed, per-item annotations can be proposed in a future SEP.

Schema Definitions

ToolAnnotations Extension

The following fields are added to the existing ToolAnnotations interface:

/**
 * Extended ToolAnnotations with trust and security metadata fields.
 */
export interface ToolAnnotations {
  // ... existing fields ...

  // Trust extensions
  maliciousActivityHint?: boolean;
  attribution?: string[];

  // Action security metadata
  inputMetadata?: InputMetadata;
  returnMetadata?: ReturnMetadata;
}

Array forms indicate possible values and are intended for tools/list (and tools/resolve when it cannot fully resolve). Responses should return single concrete values.

JSON Schema Additions

Add to the existing ToolAnnotations definition in schema.json, and introduce new $defs for action metadata:

{
  "ToolAnnotations": {
    "properties": {
      "maliciousActivityHint": {
        "description": "Indicates detected or suspected malicious activity.",
        "type": "boolean"
      },
      "attribution": {
        "description": "Sources contributing to this data for audit purposes.",
        "type": "array",
        "items": { "type": "string" }
      },
      "inputMetadata": { "$ref": "#/$defs/InputMetadata" },
      "returnMetadata": { "$ref": "#/$defs/ReturnMetadata" }
    }
  },
  "InputMetadata": {
    "type": "object",
    "properties": {
      "destination": {
        "oneOf": [
          {
            "type": "string",
            "enum": ["ephemeral", "system", "user", "internal", "public"]
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["ephemeral", "system", "user", "internal", "public"]
            }
          }
        ]
      },
      "sensitivity": { "$ref": "#/$defs/DataClassOrArray" },
      "outcomes": {
        "oneOf": [
          {
            "type": "string",
            "enum": ["benign", "consequential", "irreversible"]
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["benign", "consequential", "irreversible"]
            }
          }
        ]
      }
    },
    "required": ["destination", "sensitivity", "outcomes"],
    "additionalProperties": false
  },
  "ReturnMetadata": {
    "type": "object",
    "properties": {
      "source": {
        "oneOf": [
          {
            "type": "string",
            "enum": [
              "untrustedPublic",
              "trustedPublic",
              "internal",
              "user",
              "system"
            ]
          },
          {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "untrustedPublic",
                "trustedPublic",
                "internal",
                "user",
                "system"
              ]
            }
          }
        ]
      },
      "sensitivity": { "$ref": "#/$defs/DataClassOrArray" }
    },
    "required": ["source", "sensitivity"],
    "additionalProperties": false
  },
  "DataClassOrArray": {
    "oneOf": [
      { "$ref": "#/$defs/DataClass" },
      { "type": "array", "items": { "$ref": "#/$defs/DataClass" } }
    ]
  },
  "DataClass": {
    "oneOf": [
      {
        "type": "string",
        "enum": ["none", "user", "pii", "financial", "credentials"]
      },
      {
        "type": "object",
        "properties": {
          "regulated": {
            "type": "object",
            "properties": {
              "scopes": {
                "type": "array",
                "items": { "$ref": "#/$defs/RegulatoryScope" }
              }
            },
            "required": ["scopes"],
            "additionalProperties": false
          }
        },
        "required": ["regulated"],
        "additionalProperties": false
      }
    ]
  },
  "RegulatoryScope": {
    "type": "string",
    "examples": [
      "GDPR",
      "CCPA",
      "HIPAA",
      "GLBA",
      "PCI-DSS",
      "FERPA",
      "COPPA",
      "SOX"
    ]
  }
}

Integration with Tool Resolution

When used with the Tool Resolution mechanism (SEP #1862), trust annotations can be derived from arguments before tool execution. The same applies to action security metadata: servers MAY refine inputMetadata and returnMetadata based on the specific arguments. This enables clients to make policy decisions without invoking the tool.

Pre-execution Annotation Refinement

Servers supporting tools/resolve MAY return trust annotations in the resolved tool's annotations field. This follows the same pattern as other tool annotations: the tool declares the set of possible annotations in tools/list, and tools/resolve selects concrete values for the given arguments.

// Request: What annotations will apply if I read this file?
{
  "method": "tools/resolve",
  "params": {
    "name": "read_file",
    "arguments": { "path": "/internal/salaries.xlsx" }
  }
}

// Response: Server knows this path is internal and classified as financial
{
  "tool": {
    "name": "read_file",
    "annotations": {
      "readOnlyHint": true,
      "openWorldHint": false,
      "attribution": ["mcp://file-server.acme.local/hr/salaries.xlsx"],
      "returnMetadata": {
        "source": "internal",
        "sensitivity": "financial"
      }
    }
  }
}

This allows clients to:

1. Apply policies before execution (block, escalate, require confirmation)
2. Avoid unnecessary tool calls when policy would reject the result anyway
3. Inform users upfront about action metadata implications (destination, source, outcomes)

Limitations for Dynamic Content

Pre-execution annotations work best when metadata can be determined from arguments alone (e.g., file paths, database names). For tools that search or aggregate content:

• Search tools: Results may contain mixed sources—annotations cannot be fully determined until results are parsed
• List operations: Individual items may have different sensitivity levels
• Aggregation tools: Combined results inherit the maximum sensitivity of all inputs

In these cases, servers SHOULD return the narrowest possible set at resolve time, and MAY fall back to conservative single values if they cannot determine a precise resolution. Actual results should still include concrete annotations.

Action Metadata Examples

Read Email Drafts Action

{
  "name": "read_drafts",
  "description": "Read the user's email drafts.",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false,
  },
  "annotations": {
    "inputMetadata": {
      "destination": "ephemeral",
      "sensitivity": "none",
      "outcomes": "benign",
    },
    "returnMetadata": {
      "source": "user",
      "sensitivity": "pii",
    },
  },
}