From 451b70d1cb9fd95c970611db8f62c931bc3daf5f Mon Sep 17 00:00:00 2001 From: Em H Date: Sat, 9 Aug 2025 13:00:12 -0400 Subject: [PATCH 1/2] feat: Enhanced security model --- ENHANCED_SCHEMA.md | 192 ++ README.md | 6 + docs/docs.json | 11 +- docs/specification/2025-08-09/examples.mdx | 105 + docs/specification/2025-08-09/migration.mdx | 114 + docs/specification/2025-08-09/schema.mdx | 528 ++++ schema/2025-08-09/schema.json | 3159 +++++++++++++++++++ schema/2025-08-09/schema.ts | 1768 +++++++++++ tsconfig.json | 4 +- 9 files changed, 5885 insertions(+), 2 deletions(-) create mode 100644 ENHANCED_SCHEMA.md create mode 100644 docs/specification/2025-08-09/examples.mdx create mode 100644 docs/specification/2025-08-09/migration.mdx create mode 100644 docs/specification/2025-08-09/schema.mdx create mode 100644 schema/2025-08-09/schema.json create mode 100644 schema/2025-08-09/schema.ts diff --git a/ENHANCED_SCHEMA.md b/ENHANCED_SCHEMA.md new file mode 100644 index 000000000..358424bec --- /dev/null +++ b/ENHANCED_SCHEMA.md @@ -0,0 +1,192 @@ +# Enhanced, Security-Focused MCP Schema (2025-08-09) + +This document summarizes the security-focused enhancements added in `schema/2025-08-09/schema.ts`, how they improve MCP security, and how to adopt them. + +## High-level changes + +- First-class message security envelope via `_meta.security` on requests, notifications, and results +- Capability-based authorization with fine-grained scopes and short-lived, non-transferable tokens +- Message-level cryptography: identities (signatures), integrity hashes, replay protection, and optional encryption +- Security capability negotiation in `initialize` +- Dedicated security error codes (4900-4907) +- Capability issuance RPC: `security/issue` + +## `_meta.security` envelope + +Attach to each message under `params._meta.security` (and optionally on results/notifications): + +- identity: `{ keyId, alg, jws, publicKey?, certificateChain? }` + - Cryptographic sender authentication per message; supports PKI or key IDs +- capabilities: `(string | CapabilityToken)[]` + - Least-privilege, time-boxed authorization per request (no ambient permissions) +- replay: `{ nonce, timestamp }` + - Prevents replay within a bounded window; enables zero-trust +- integrity: `{ alg, hash, canonicalization? }` + - Tamper detection on canonical payload; defense-in-depth if transport is compromised +- encryption: `{ alg, keyId?, iv?, aad?, ciphertext, tag? }` + - Optional end-to-end confidentiality of `params` beyond TLS +- audit: `{ traceId?, requestId? }` + - End-to-end traceability and incident response + +### Example: signed + capability-bearing request + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "resources/read", + "params": { + "_meta": { + "security": { + "replay": { "nonce": "3XbV...", "timestamp": "2025-08-09T12:00:00Z" }, + "integrity": { "alg": "SHA-256", "hash": "base64-hash" }, + "capabilities": ["eyJhbGciOiJFZERTQSIs..."], + "identity": { + "keyId": "kid:client", + "alg": "EdDSA", + "jws": "" + }, + "audit": { "traceId": "trace-123", "requestId": "req-abc" } + } + }, + "uri": "file:///project/README.md" + } +} +``` + +### Example: encrypted parameters + +```json +{ + "jsonrpc": "2.0", + "id": 12, + "method": "resources/read", + "params": { + "_meta": { + "security": { + "replay": { "nonce": "v2t4...", "timestamp": "2025-08-09T12:02:00Z" }, + "encryption": { + "alg": "A256GCM", + "keyId": "kid:server", + "iv": "Q2hhbmdlbWU=", + "aad": "eyJqd3QiOnRydWV9", + "ciphertext": "X1c+...", + "tag": "bG9naW4=" + } + } + } + } +} +``` + +## Capability model + +- CapabilityToken: either a compact `token` (JWT, PASETO, CWT) or a structured `claims` object +- CapabilityClaims: + - scope: array of fine-grained entries + - resource: `{ type: "resource", actions: ["read"|"subscribe"|"unsubscribe"|"list"|"templates_list"], uri?, uriTemplate? }` + - tool: `{ type: "tool", actions: ["call"|"list"], name?, namePattern? }` + - prompt: `{ type: "prompt", actions: ["get"|"list"], name?, namePattern? }` + - constraints: `{ notBefore?, expiresAt?, audience?, issuer?, subject?, context? }` + - nonTransferable: boolean (binds token to presenter) + +### Issuance RPC: `security/issue` + +Servers validate identity proof and policy, then issue scoped, short-lived capabilities. + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "security/issue", + "params": { + "requested": [ + { + "scope": [ + { + "type": "resource", + "actions": ["read"], + "uriTemplate": "file://*/README.md" + } + ], + "constraints": { "expiresAt": "2025-08-09T12:05:00Z" }, + "nonTransferable": true + } + ], + "proof": { "keyId": "kid:client", "alg": "EdDSA", "jws": "" }, + "audience": "urn:mcp:server" + } +} +``` + +Response (example): + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "result": { + "capabilities": ["eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...."], + "expiresAt": "2025-08-09T12:05:00Z" + } +} +``` + +## Security capability negotiation (initialize) + +- `ClientCapabilities.security` / `ServerCapabilities.security`: + - `requireSignedRequests`, `requireSignedResponses`, `requireCapabilities` + - `supportedSignatureAlgs`, `supportedEncryptionAlgs` + - `acceptCapabilityFormats` ("jwt", "paseto", "cwt", "object") + - `maxReplayWindowSeconds` + +Benefit: progressive rollout and explicit policy expectations before enforcement. + +## Security error codes + +- 4900 UNAUTHORIZED: missing or invalid identity/capabilities +- 4901 FORBIDDEN: capability present but not sufficient for this action +- 4902 REPLAY_DETECTED: nonce/timestamp outside window or reused +- 4903 INVALID_SIGNATURE: signature or integrity failure +- 4904 INVALID_CAPABILITY: malformed token/claims +- 4905 EXPIRED_CAPABILITY: token expired or not yet valid +- 4906 ENCRYPTION_REQUIRED: policy requires encryption but absent +- 4907 DECRYPTION_FAILED: could not decrypt (e.g., wrong key) + +## Why this improves security + +- Authentication-first: message-level identity proof supports mutual auth and key rotation +- Stateless by default: each message stands alone with its own authZ/authN; no session hijacking +- Least privilege: capabilities scope precisely to resources/tools/prompts with tight lifetimes +- Zero-trust: do not rely on "trusted networks"; validate per-message invariants +- Defense-in-depth: integrity and optional encryption protect even if transport is compromised +- Auditability: `traceId`/`requestId` enable robust forensics and correlation +- Verifiability: small, explicit invariants lend themselves to formal checks + +## Recommended rollout (progressive hardening) + +1. Negotiate: advertise `security` capabilities during `initialize` +2. Start verifying: enforce `replay` and `integrity` (log failures), continue to allow requests +3. Introduce capabilities: require tokens for privileged methods; soft-fail on missing signatures +4. Require signatures: enforce identity on all requests/responses +5. Encrypt sensitive: require message-level `encryption` for sensitive methods/parameters + +## Validation checklist (server side) + +- Replay: `timestamp` within `maxReplayWindowSeconds`, `nonce` unique per keyId +- Integrity: recompute canonical payload hash; return 4903 on mismatch +- Identity: verify `identity.jws` and `keyId`/PKI; apply revocation/rotation policy +- Capabilities: validate scope/constraints; return 4901 (or 4905/4904) as appropriate +- Encryption: if required, enforce presence and decrypt; return 4906/4907 on violations +- Audit: propagate and log `traceId`/`requestId` + +--- + +See also: + +- Schema: `schema/2025-08-09/schema.ts` +- Generated docs: `docs/specification/2025-08-09/schema.mdx` +- Migration guide: `docs/specification/2025-08-09/migration.mdx` +- Examples: `docs/specification/2025-08-09/examples.mdx` diff --git a/README.md b/README.md index 7ffee9f2a..2b9778e62 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,12 @@ compatibility. The official MCP documentation is built using Mintlify and available at [modelcontextprotocol.io](https://modelcontextprotocol.io). +## Enhanced Security Schema + +For a summary of the new security-focused MCP schema with examples and rollout guidance, see +[ENHANCED_SCHEMA.md](ENHANCED_SCHEMA.md). The corresponding TypeScript schema is at +[`schema/2025-08-09/schema.ts`](schema/2025-08-09/schema.ts). + ## Contributing See [CONTRIBUTING.md](./CONTRIBUTING.md). diff --git a/docs/docs.json b/docs/docs.json index bee08c7cc..74c7c142f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -43,7 +43,8 @@ "group": "Using MCP", "pages": [ "docs/tutorials/use-remote-mcp-server", - "quickstart/user" + "quickstart/user", + "quickstart/running-mcp-servers" ] }, { @@ -67,6 +68,14 @@ { "tab": "Specification", "versions": [ + { + "version": "Security Preview 2025-08-09", + "pages": [ + "specification/2025-08-09/schema", + "specification/2025-08-09/migration", + "specification/2025-08-09/examples" + ] + }, { "version": "Version 2025-06-18 (latest)", "pages": [ diff --git a/docs/specification/2025-08-09/examples.mdx b/docs/specification/2025-08-09/examples.mdx new file mode 100644 index 000000000..615d75300 --- /dev/null +++ b/docs/specification/2025-08-09/examples.mdx @@ -0,0 +1,105 @@ +--- +title: Secure MCP Examples (2025-08-09) +--- + +This page provides end‑to‑end examples for `_meta.security`, capability issuance, and message‑level encryption. + +### Signed request with capabilities and replay protection + +```json +{ + "jsonrpc": "2.0", + "id": 10, + "method": "tools/call", + "params": { + "_meta": { + "security": { + "replay": { + "nonce": "jW9Qf7oC0fE=", + "timestamp": "2025-08-09T12:00:00Z" + }, + "integrity": { "alg": "SHA-256", "hash": "pZr2a5kq...=" }, + "capabilities": ["eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...."], + "identity": { + "keyId": "kid:client", + "alg": "EdDSA", + "jws": "eyJhbGciOiJFZERTQSJ9..signature" + }, + "audit": { "traceId": "trace-123", "requestId": "req-abc" } + } + }, + "name": "search_web", + "arguments": { "query": "mcp security" } + } +} +``` + +### Capability issuance (`security/issue`) + +```json +{ + "jsonrpc": "2.0", + "id": 11, + "method": "security/issue", + "params": { + "requested": [ + { + "scope": [ + { "type": "tool", "actions": ["call"], "name": "search_web" } + ], + "constraints": { + "expiresAt": "2025-08-09T12:10:00Z", + "audience": "urn:mcp:server:tools" + }, + "nonTransferable": true + } + ], + "proof": { "keyId": "kid:client", "alg": "EdDSA", "jws": "" } + } +} +``` + +### Encrypted params (_message‑level encryption_) + +When `encryption` is present, `params` MAY contain only `_meta.security.encryption` and the receiver decrypts to recover the original parameters. + +```json +{ + "jsonrpc": "2.0", + "id": 12, + "method": "resources/read", + "params": { + "_meta": { + "security": { + "replay": { "nonce": "v2t4...", "timestamp": "2025-08-09T12:02:00Z" }, + "encryption": { + "alg": "A256GCM", + "keyId": "kid:server", + "iv": "Q2hhbmdlbWU=", + "aad": "eyJqd3QiOnRydWV9", + "ciphertext": "X1c+...", + "tag": "bG9naW4=" + } + } + } + } +} +``` + +### Security‑aware error responses + +```json +{ + "jsonrpc": "2.0", + "id": 13, + "error": { "code": 4902, "message": "Replay window exceeded" } +} +``` + +### Validation checklist + +- Verify `timestamp` within replay window; ensure `nonce` uniqueness per sender key. +- Verify `integrity.hash` against canonical payload; reject on mismatch (4903). +- Verify JWS signature and `keyId`; apply revocation/rotation policy. +- Validate capability scopes/constraints; reject unauthorized (4901) or expired (4905). +- If `encryption` is required, reject unencrypted (4906); on failure to decrypt, return (4907). diff --git a/docs/specification/2025-08-09/migration.mdx b/docs/specification/2025-08-09/migration.mdx new file mode 100644 index 000000000..ce1a73e68 --- /dev/null +++ b/docs/specification/2025-08-09/migration.mdx @@ -0,0 +1,114 @@ +--- +title: Migrating to Security-Focused MCP (2025-08-09) +--- + +This guide explains how to adopt the security-focused enhancements introduced in the 2025-08-09 schema, while maintaining backward compatibility with earlier MCP versions. + +### Goals + +- Strong identity on every message +- Fine‑grained, time‑boxed capability tokens +- Replay protection and payload integrity +- Optional message‑level encryption (beyond TLS) + +### 1) Negotiate capabilities during initialize + +- Ensure clients and servers advertise `security` in `ClientCapabilities`/`ServerCapabilities`. +- Do not hard‑require security features on day one; start by accepting unsigned messages and progressively tighten policy based on `security` capabilities. + +```json +{ + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2025-08-09", + "capabilities": { + "security": { + "requireSignedRequests": false, + "supportedSignatureAlgs": ["EdDSA", "ES256"], + "acceptCapabilityFormats": ["jwt", "paseto", "object"], + "maxReplayWindowSeconds": 300 + } + }, + "clientInfo": { "name": "my-client", "version": "1.0.0" } + } +} +``` + +### 2) Issue short‑lived capabilities + +- Use `security/issue` to mint scoped, non‑transferable tokens. +- Begin by issuing tokens for low‑risk actions, then expand. + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "security/issue", + "params": { + "requested": [ + { + "scope": [ + { + "type": "resource", + "actions": ["read"], + "uriTemplate": "file://*/README.md" + } + ], + "constraints": { "expiresAt": "2025-08-09T12:05:00Z" }, + "nonTransferable": true + } + ], + "proof": { "keyId": "kid:client", "alg": "EdDSA", "jws": "" } + } +} +``` + +### 3) Attach `_meta.security` to requests + +- Start with `replay` and `integrity`; add `identity` and `capabilities` next; finally enable `encryption`. +- Roll out per‑method allowlists to reduce blast radius. + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "resources/read", + "params": { + "_meta": { + "security": { + "replay": { "nonce": "3XbV...", "timestamp": "2025-08-09T12:00:00Z" }, + "integrity": { "alg": "SHA-256", "hash": "base64-hash" }, + "capabilities": ["eyJhbGciOiJFZERTQSIs..."], + "identity": { + "keyId": "kid:client", + "alg": "EdDSA", + "jws": "" + } + } + }, + "uri": "file:///project/README.md" + } +} +``` + +### 4) Progressive enforcement + +- Phase A: Log & allow unsigned/uncap requests, enforce replay windows. +- Phase B: Require capabilities for privileged methods; continue soft‑fail on missing signatures. +- Phase C: Require signatures for all requests; return `UNAUTHORIZED`/`FORBIDDEN` on violations. +- Phase D: Require encryption for sensitive payloads; reject with `ENCRYPTION_REQUIRED` when absent. + +### 5) Backward compatibility + +- Keep accepting legacy versions during transition. +- For mixed fleets, issue dual tokens and accept both JWT and object formats. +- Use error codes: `4900 UNAUTHORIZED`, `4901 FORBIDDEN`, `4902 REPLAY_DETECTED`, `4903 INVALID_SIGNATURE`, `4906 ENCRYPTION_REQUIRED`. + +### 6) Operational guidance + +- Audit: propagate `traceId`/`requestId` via `_meta.security.audit`. +- Key rotation: maintain multiple `keyId`s concurrently; overlap validity windows. +- Clock skew: allow small grace periods within `maxReplayWindowSeconds`. +- Rate‑limit: throttle invalid signature and decryption failures. diff --git a/docs/specification/2025-08-09/schema.mdx b/docs/specification/2025-08-09/schema.mdx new file mode 100644 index 000000000..e6744d965 --- /dev/null +++ b/docs/specification/2025-08-09/schema.mdx @@ -0,0 +1,528 @@ +--- +title: Schema Reference +--- + +
+ +## Common Types + +### `Annotations` + +
interface Annotations {
  audience?: Role[];
  lastModified?: string;
  priority?: number;
}

Optional annotations for the client. The client can use annotations to inform how objects are used or displayed

audience?: Role[]

Describes who the intended customer of this object or data is.

It can include multiple entries to indicate content useful for multiple audiences (e.g., ["user", "assistant"]).

lastModified?: string

The moment the resource was last modified, as an ISO 8601 formatted string.

Should be an ISO 8601 formatted string (e.g., "2025-01-12T15:00:58Z").

Examples: last activity timestamp in an open file, timestamp when the resource +was attached, etc.

priority?: number

Describes how important this data is for operating the server.

A value of 1 means "most important," and indicates that the data is +effectively required, while 0 means "least important," and indicates that +the data is entirely optional.

+ +### `AudioContent` + +
interface AudioContent {
  _meta?: { [key: string]: unknown };
  annotations?: Annotations;
  data: string;
  mimeType: string;
  type: "audio";
}

Audio provided to or from an LLM.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

annotations?: Annotations

Optional annotations for the client.

data: string

The base64-encoded audio data.

mimeType: string

The MIME type of the audio. Different providers may support different audio types.

+ +### `BlobResourceContents` + +
interface BlobResourceContents {
  _meta?: { [key: string]: unknown };
  blob: string;
  mimeType?: string;
  uri: string;
}

The contents of a specific resource or sub-resource.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

blob: string

A base64-encoded string representing the binary data of the item.

mimeType?: string

The MIME type of this resource, if known.

uri: string

The URI of this resource.

+ +### `BooleanSchema` + +
interface BooleanSchema {
  default?: boolean;
  description?: string;
  title?: string;
  type: "boolean";
}
+ +### `CapabilityClaims` + +
interface CapabilityClaims {
  constraints?: CapabilityConstraints;
  nonTransferable?: boolean;
  scope: CapabilityScope[];
}

Capability claims represent fine-grained authorization with constraints.

constraints?: CapabilityConstraints

Temporal and contextual constraints.

nonTransferable?: boolean

Indicates token is bound to the presenter and is non-transferable.

scope: CapabilityScope[]

Actions and targets this token authorizes.

+ +### `CapabilityConstraints` + +
interface CapabilityConstraints {
  audience?: string;
  context?: { [key: string]: unknown };
  expiresAt?: string;
  issuer?: string;
  notBefore?: string;
  subject?: string;
}

Constraints limiting when/where a capability is valid.

audience?: string

Intended audience identifier.

context?: { [key: string]: unknown }

Optional additional constraint context.

expiresAt?: string

Expiration time (ISO 8601).

issuer?: string

Issuer identifier.

notBefore?: string

Not valid before (ISO 8601).

subject?: string

Subject identifier (e.g., client id).

+ +### `CapabilityScope` + +
CapabilityScope: ResourceScope | ToolScope | PromptScope

Capability scopes for resources, tools, or prompts.

+ +### `CapabilityToken` + +
interface CapabilityToken {
  claims?: CapabilityClaims;
  format?: "object" | "jwt" | "cwt" | "paseto";
  id?: string;
  token?: string;
}

A structured capability token.

claims?: CapabilityClaims

Structured claims for object-encoded capabilities.

format?: "object" | "jwt" | "cwt" | "paseto"

Encoding format when represented as a string.

id?: string

Token identifier for audit/revocation.

token?: string

Opaque representation for compact encodings; preferred when present.

+ +### `ClientCapabilities` + +
interface ClientCapabilities {
  elicitation?: object;
  experimental?: { [key: string]: object };
  roots?: { listChanged?: boolean };
  sampling?: object;
  security?: SecurityCapabilities;
}

Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.

elicitation?: object

Present if the client supports elicitation from the server.

experimental?: { [key: string]: object }

Experimental, non-standard capabilities that the client supports.

roots?: { listChanged?: boolean }

Present if the client supports listing roots.

Type declaration
  • OptionallistChanged?: boolean

    Whether the client supports notifications for changes to the roots list.

sampling?: object

Present if the client supports sampling from an LLM.

security?: SecurityCapabilities

Security capabilities.

+ +### `ContentBlock` + +
ContentBlock:
  | TextContent
  | ImageContent
  | AudioContent
  | ResourceLink
  | EmbeddedResource
+ +### `Cursor` + +
Cursor: string

An opaque token used to represent a cursor for pagination.

+ +### `DECRYPTION_FAILED` + +
DECRYPTION_FAILED: 4907

Decryption failed (e.g., wrong key)

+ +### `EmbeddedResource` + +
interface EmbeddedResource {
  _meta?: { [key: string]: unknown };
  annotations?: Annotations;
  resource: TextResourceContents | BlobResourceContents;
  type: "resource";
}

The contents of a resource, embedded into a prompt or tool call result.

It is up to the client how best to render embedded resources for the benefit +of the LLM and/or the user.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

annotations?: Annotations

Optional annotations for the client.

+ +### `EmptyResult` + +
EmptyResult: Result

A response that indicates success but carries no data.

+ +### `EncryptedPayload` + +
interface EncryptedPayload {
  aad?: string;
  alg: string;
  ciphertext: string;
  iv?: string;
  keyId?: string;
  tag?: string;
}

JWE-like encrypted payload container for message-level encryption.

aad?: string

Base64-encoded additional authenticated data (AAD) if used.

alg: string

Encryption algorithm (e.g., A256GCM, XC20P).

ciphertext: string

Base64-encoded ciphertext of the original JSON params.

iv?: string

Base64-encoded initialization vector/nonce.

keyId?: string

Key identifier for decryption.

tag?: string

Base64-encoded authentication tag (if not implicit in ciphertext).

+ +### `ENCRYPTION_REQUIRED` + +
ENCRYPTION_REQUIRED: 4906

Encryption required but not provided

+ +### `EnumSchema` + +
interface EnumSchema {
  description?: string;
  enum: string[];
  enumNames?: string[];
  title?: string;
  type: "string";
}
enumNames?: string[]

Display names for enum values

+ +### `EXPIRED_CAPABILITY` + +
EXPIRED_CAPABILITY: 4905

Capability token expired or not yet valid

+ +### `FORBIDDEN` + +
FORBIDDEN: 4901

Forbidden: capability present but does not allow this action

+ +### `IdentityProof` + +
interface IdentityProof {
  alg?: string;
  certificateChain?: string[];
  jws?: string;
  keyId?: string;
  publicKey?: string;
}

Identity proof carried alongside a message.

alg?: string

Signature algorithm (e.g., EdDSA, ES256).

certificateChain?: string[]

Optional X.509 certificate chain (PEM) when using PKI.

jws?: string

JOSE compact JWS with a detached payload over the canonical request envelope.

keyId?: string

Key identifier understood by the receiver.

publicKey?: string

Public key material (PEM or JWK) if out-of-band distribution is not available.

+ +### `ImageContent` + +
interface ImageContent {
  _meta?: { [key: string]: unknown };
  annotations?: Annotations;
  data: string;
  mimeType: string;
  type: "image";
}

An image provided to or from an LLM.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

annotations?: Annotations

Optional annotations for the client.

data: string

The base64-encoded image data.

mimeType: string

The MIME type of the image. Different providers may support different image types.

+ +### `Implementation` + +
interface Implementation {
  name: string;
  title?: string;
  version: string;
}

Describes the name and version of an MCP implementation, with an optional title for UI representation.

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, +even by those unfamiliar with domain-specific terminology.

If not provided, the name should be used for display (except for Tool, +where annotations.title should be given precedence over using name, +if present).

+ +### `INVALID_CAPABILITY` + +
INVALID_CAPABILITY: 4904

Capability token malformed

+ +### `INVALID_SIGNATURE` + +
INVALID_SIGNATURE: 4903

Invalid signature or integrity hash

+ +### `IssueCapabilitiesResult` + +
interface IssueCapabilitiesResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  capabilities: (string | CapabilityToken)[];
  expiresAt?: string;
  [key: string]: unknown;
}

Result of a capability issuance request.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

capabilities: (string | CapabilityToken)[]

Issued capability tokens.

expiresAt?: string

Optional common expiration for all returned tokens.

+ +### `JSONRPCError` + +
interface JSONRPCError {
  error: { code: number; data?: unknown; message: string };
  id: RequestId;
  jsonrpc: "2.0";
}

A response to a request that indicates an error occurred.

error: { code: number; data?: unknown; message: string }
Type declaration
  • code: number

    The error type that occurred.

  • Optionaldata?: unknown

    Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.).

  • message: string

    A short description of the error. The message SHOULD be limited to a concise single sentence.

+ +### `JSONRPCNotification` + +
interface JSONRPCNotification {
  jsonrpc: "2.0";
  method: string;
  params?: {
    _meta?: { security?: SecurityMeta; [key: string]: unknown };
    [key: string]: unknown;
  };
}

A notification which does not expect a response.

params?: {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  [key: string]: unknown;
}
Type declaration
  • [key: string]: unknown
  • Optional_meta?: { security?: SecurityMeta; [key: string]: unknown }

    See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

+ +### `JSONRPCRequest` + +
interface JSONRPCRequest {
  id: RequestId;
  jsonrpc: "2.0";
  method: string;
  params?: {
    _meta?: {
      progressToken?: ProgressToken;
      security?: SecurityMeta;
      [key: string]: unknown;
    };
    [key: string]: unknown;
  };
}

A request that expects a response.

params?: {
  _meta?: {
    progressToken?: ProgressToken;
    security?: SecurityMeta;
    [key: string]: unknown;
  };
  [key: string]: unknown;
}
Type declaration
  • [key: string]: unknown
  • Optional_meta?: {
      progressToken?: ProgressToken;
      security?: SecurityMeta;
      [key: string]: unknown;
    }

    See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

    • OptionalprogressToken?: ProgressToken

      If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications.

    • Optionalsecurity?: SecurityMeta

      Security envelope for this request. When present, receivers SHOULD validate according to their +security policy before processing the request.

+ +### `JSONRPCResponse` + +
interface JSONRPCResponse {
  id: RequestId;
  jsonrpc: "2.0";
  result: Result;
}

A successful (non-error) response to a request.

+ +### `LoggingLevel` + +
LoggingLevel:
  | "debug"
  | "info"
  | "notice"
  | "warning"
  | "error"
  | "critical"
  | "alert"
  | "emergency"

The severity of a log message.

These map to syslog message severities, as specified in RFC-5424: https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1

+ +### `ModelHint` + +
interface ModelHint {
  name?: string;
}

Hints to use for model selection.

name?: string

A hint for a model name.

+ +### `ModelPreferences` + +
interface ModelPreferences {
  costPriority?: number;
  hints?: ModelHint[];
  intelligencePriority?: number;
  speedPriority?: number;
}

The server's preferences for model selection, requested of the client during sampling.

costPriority?: number

How much to prioritize cost when selecting a model. A value of 0 means cost +is not important, while a value of 1 means cost is the most important +factor.

hints?: ModelHint[]

Optional hints to use for model selection.

If multiple hints are specified, the client MUST evaluate them in order +(such that the first match is taken).

The client SHOULD prioritize these hints over the numeric priorities, but +MAY still use the priorities to select from ambiguous matches.

intelligencePriority?: number

How much to prioritize intelligence and capabilities when selecting a +model. A value of 0 means intelligence is not important, while a value of 1 +means intelligence is the most important factor.

speedPriority?: number

How much to prioritize sampling speed (latency) when selecting a model. A +value of 0 means speed is not important, while a value of 1 means speed is +the most important factor.

+ +### `NumberSchema` + +
interface NumberSchema {
  description?: string;
  maximum?: number;
  minimum?: number;
  title?: string;
  type: "number" | "integer";
}
+ +### `PrimitiveSchemaDefinition` + +
PrimitiveSchemaDefinition:
  | StringSchema
  | NumberSchema
  | BooleanSchema
  | EnumSchema

Restricted schema definitions that only allow primitive types +without nested objects or arrays.

+ +### `ProgressToken` + +
ProgressToken: string | number

A progress token, used to associate progress notifications with the original request.

+ +### `Prompt` + +
interface Prompt {
  _meta?: { [key: string]: unknown };
  arguments?: PromptArgument[];
  description?: string;
  name: string;
  title?: string;
}

A prompt or prompt template that the server offers.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

arguments?: PromptArgument[]

A list of arguments to use for templating the prompt.

description?: string

An optional description of what this prompt provides

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, +even by those unfamiliar with domain-specific terminology.

If not provided, the name should be used for display (except for Tool, +where annotations.title should be given precedence over using name, +if present).

+ +### `PromptArgument` + +
interface PromptArgument {
  description?: string;
  name: string;
  required?: boolean;
  title?: string;
}

Describes an argument that a prompt can accept.

description?: string

A human-readable description of the argument.

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

required?: boolean

Whether this argument must be provided.

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, +even by those unfamiliar with domain-specific terminology.

If not provided, the name should be used for display (except for Tool, +where annotations.title should be given precedence over using name, +if present).

+ +### `PromptMessage` + +
interface PromptMessage {
  content: ContentBlock;
  role: Role;
}

Describes a message returned as part of a prompt.

This is similar to SamplingMessage, but also supports the embedding of +resources from the MCP server.

+ +### `PromptReference` + +
interface PromptReference {
  name: string;
  title?: string;
  type: "ref/prompt";
}

Identifies a prompt.

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, +even by those unfamiliar with domain-specific terminology.

If not provided, the name should be used for display (except for Tool, +where annotations.title should be given precedence over using name, +if present).

+ +### `PromptScope` + +
interface PromptScope {
  actions: ("list" | "get")[];
  name?: string;
  namePattern?: string;
  type: "prompt";
}
name?: string

Specific prompt name or pattern.

+ +### `REPLAY_DETECTED` + +
REPLAY_DETECTED: 4902

Replay detected based on nonce/timestamp

+ +### `RequestId` + +
RequestId: string | number

A uniquely identifying ID for a request in JSON-RPC.

+ +### `Resource` + +
interface Resource {
  _meta?: { [key: string]: unknown };
  annotations?: Annotations;
  description?: string;
  mimeType?: string;
  name: string;
  size?: number;
  title?: string;
  uri: string;
}

A known resource that the server is capable of reading.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

annotations?: Annotations

Optional annotations for the client.

description?: string

A description of what this resource represents.

This can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a "hint" to the model.

mimeType?: string

The MIME type of this resource, if known.

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

size?: number

The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.

This can be used by Hosts to display file sizes and estimate context window usage.

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, +even by those unfamiliar with domain-specific terminology.

If not provided, the name should be used for display (except for Tool, +where annotations.title should be given precedence over using name, +if present).

uri: string

The URI of this resource.

+ +### `ResourceContents` + +
interface ResourceContents {
  _meta?: { [key: string]: unknown };
  mimeType?: string;
  uri: string;
}

The contents of a specific resource or sub-resource.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

mimeType?: string

The MIME type of this resource, if known.

uri: string

The URI of this resource.

+ +### `ResourceLink` + +
interface ResourceLink {
  _meta?: { [key: string]: unknown };
  annotations?: Annotations;
  description?: string;
  mimeType?: string;
  name: string;
  size?: number;
  title?: string;
  type: "resource_link";
  uri: string;
}

A resource that the server is capable of reading, included in a prompt or tool call result.

Note: resource links returned by tools are not guaranteed to appear in the results of resources/list requests.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

annotations?: Annotations

Optional annotations for the client.

description?: string

A description of what this resource represents.

This can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a "hint" to the model.

mimeType?: string

The MIME type of this resource, if known.

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

size?: number

The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.

This can be used by Hosts to display file sizes and estimate context window usage.

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, +even by those unfamiliar with domain-specific terminology.

If not provided, the name should be used for display (except for Tool, +where annotations.title should be given precedence over using name, +if present).

uri: string

The URI of this resource.

+ +### `ResourceScope` + +
interface ResourceScope {
  actions: (
    "read"
    | "subscribe"
    | "unsubscribe"
    | "list"
    | "templates_list"
  )[];
  type: "resource";
  uri?: string;
  uriTemplate?: string;
}
uri?: string

Exact URI or template this scope applies to.

uriTemplate?: string

RFC 6570 URI template or glob-like pattern.

+ +### `ResourceTemplate` + +
interface ResourceTemplate {
  _meta?: { [key: string]: unknown };
  annotations?: Annotations;
  description?: string;
  mimeType?: string;
  name: string;
  title?: string;
  uriTemplate: string;
}

A template description for resources available on the server.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

annotations?: Annotations

Optional annotations for the client.

description?: string

A description of what this template is for.

This can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a "hint" to the model.

mimeType?: string

The MIME type for all resources that match this template. This should only be included if all resources matching this template have the same type.

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, +even by those unfamiliar with domain-specific terminology.

If not provided, the name should be used for display (except for Tool, +where annotations.title should be given precedence over using name, +if present).

uriTemplate: string

A URI template (according to RFC 6570) that can be used to construct resource URIs.

+ +### `ResourceTemplateReference` + +
interface ResourceTemplateReference {
  type: "ref/resource";
  uri: string;
}

A reference to a resource or resource template definition.

uri: string

The URI or URI template of the resource.

+ +### `Result` + +
interface Result {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  [key: string]: unknown;
}
Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

+ +### `Role` + +
Role: "user" | "assistant"

The sender or recipient of messages and data in a conversation.

+ +### `Root` + +
interface Root {
  _meta?: { [key: string]: unknown };
  name?: string;
  uri: string;
}

Represents a root directory or file that the server can operate on.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

name?: string

An optional name for the root. This can be used to provide a human-readable +identifier for the root, which may be useful for display purposes or for +referencing the root in other parts of the application.

uri: string

The URI identifying the root. This must start with file:// for now. +This restriction may be relaxed in future versions of the protocol to allow +other URI schemes.

+ +### `SamplingMessage` + +
interface SamplingMessage {
  content: TextContent | ImageContent | AudioContent;
  role: Role;
}

Describes a message issued to or received from an LLM API.

+ +### `SecurityCapabilities` + +
interface SecurityCapabilities {
  acceptCapabilityFormats?: ("object" | "jwt" | "cwt" | "paseto")[];
  maxReplayWindowSeconds?: number;
  requireCapabilities?: boolean;
  requireSignedRequests?: boolean;
  requireSignedResponses?: boolean;
  supportedEncryptionAlgs?: string[];
  supportedSignatureAlgs?: string[];
}

Supported security features and expectations for the connection.

acceptCapabilityFormats?: ("object" | "jwt" | "cwt" | "paseto")[]

Accepted capability token encodings.

maxReplayWindowSeconds?: number

Maximum allowable replay window in seconds.

requireCapabilities?: boolean

If true, the endpoint requires capability tokens for privileged operations.

requireSignedRequests?: boolean

If true, the endpoint requires signed requests.

requireSignedResponses?: boolean

If true, the endpoint requires signed responses.

supportedEncryptionAlgs?: string[]

Supported encryption algorithms for payload-level encryption (JOSE/JWE name).

supportedSignatureAlgs?: string[]

Supported signature algorithms (JOSE name, e.g., "EdDSA", "ES256").

+ +### `SecurityMeta` + +
interface SecurityMeta {
  audit?: { requestId?: string; traceId?: string };
  capabilities?: (string | CapabilityToken)[];
  encryption?: EncryptedPayload;
  identity?: IdentityProof;
  integrity?: { alg: string; canonicalization?: string; hash: string };
  replay?: { nonce: string; timestamp: string };
}

A structured security envelope attached to messages via _meta.security.

audit?: { requestId?: string; traceId?: string }

Optional audit/tracing context propagated end-to-end.

capabilities?: (string | CapabilityToken)[]

Capability tokens authorizing this specific request. Each entry may be an opaque string (e.g., JWT) +or a structured object for constrained environments.

encryption?: EncryptedPayload

Optional message-level encryption container. When present, params MAY be omitted +and the receiver is expected to decrypt to recover the plaintext parameters.

identity?: IdentityProof

Proof of the sender's identity (e.g., JWS over a canonical request representation).

integrity?: { alg: string; canonicalization?: string; hash: string }

Integrity information for the payload (e.g., payload hash over params after canonicalization, or over the decrypted plaintext when encrypted).

Type declaration
  • alg: string

    Hash algorithm identifier (e.g., "SHA-256").

  • Optionalcanonicalization?: string

    Optional canonicalization method identifier.

  • hash: string

    Base64-encoded hash of the canonical payload.

replay?: { nonce: string; timestamp: string }

Replay protection parameters.

Type declaration
  • nonce: string

    Unique nonce for this message.

  • timestamp: string

    Creation time in ISO 8601, used for replay windows.

+ +### `ServerCapabilities` + +
interface ServerCapabilities {
  completions?: object;
  experimental?: { [key: string]: object };
  logging?: object;
  prompts?: { listChanged?: boolean };
  resources?: { listChanged?: boolean; subscribe?: boolean };
  security?: SecurityCapabilities;
  tools?: { listChanged?: boolean };
}

Capabilities that a server may support. Known capabilities are defined here, in this schema, but this is not a closed set: any server can define its own, additional capabilities.

completions?: object

Present if the server supports argument autocompletion suggestions.

experimental?: { [key: string]: object }

Experimental, non-standard capabilities that the server supports.

logging?: object

Present if the server supports sending log messages to the client.

prompts?: { listChanged?: boolean }

Present if the server offers any prompt templates.

Type declaration
  • OptionallistChanged?: boolean

    Whether this server supports notifications for changes to the prompt list.

resources?: { listChanged?: boolean; subscribe?: boolean }

Present if the server offers any resources to read.

Type declaration
  • OptionallistChanged?: boolean

    Whether this server supports notifications for changes to the resource list.

  • Optionalsubscribe?: boolean

    Whether this server supports subscribing to resource updates.

security?: SecurityCapabilities

Security capabilities.

tools?: { listChanged?: boolean }

Present if the server offers any tools to call.

Type declaration
  • OptionallistChanged?: boolean

    Whether this server supports notifications for changes to the tool list.

+ +### `StringSchema` + +
interface StringSchema {
  description?: string;
  format?: "uri" | "email" | "date" | "date-time";
  maxLength?: number;
  minLength?: number;
  title?: string;
  type: "string";
}
+ +### `TextContent` + +
interface TextContent {
  _meta?: { [key: string]: unknown };
  annotations?: Annotations;
  text: string;
  type: "text";
}

Text provided to or from an LLM.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

annotations?: Annotations

Optional annotations for the client.

text
text: string

The text content of the message.

+ +### `TextResourceContents` + +
interface TextResourceContents {
  _meta?: { [key: string]: unknown };
  mimeType?: string;
  text: string;
  uri: string;
}

The contents of a specific resource or sub-resource.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

mimeType?: string

The MIME type of this resource, if known.

text
text: string

The text of the item. This must only be set if the item can actually be represented as text (not binary data).

uri: string

The URI of this resource.

+ +### `Tool` + +
interface Tool {
  _meta?: { [key: string]: unknown };
  annotations?: ToolAnnotations;
  description?: string;
  inputSchema: {
    properties?: { [key: string]: object };
    required?: string[];
    type: "object";
  };
  name: string;
  outputSchema?: {
    properties?: { [key: string]: object };
    required?: string[];
    type: "object";
  };
  title?: string;
}

Definition for a tool the client can call.

Optional_meta
_meta?: { [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

annotations?: ToolAnnotations

Optional additional tool information.

Display name precedence order is: title, annotations.title, then name.

description?: string

A human-readable description of the tool.

This can be used by clients to improve the LLM's understanding of available tools. It can be thought of like a "hint" to the model.

inputSchema: {
  properties?: { [key: string]: object };
  required?: string[];
  type: "object";
}

A JSON Schema object defining the expected parameters for the tool.

name: string

Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).

outputSchema?: {
  properties?: { [key: string]: object };
  required?: string[];
  type: "object";
}

An optional JSON Schema object defining the structure of the tool's output returned in +the structuredContent field of a CallToolResult.

title?: string

Intended for UI and end-user contexts — optimized to be human-readable and easily understood, +even by those unfamiliar with domain-specific terminology.

If not provided, the name should be used for display (except for Tool, +where annotations.title should be given precedence over using name, +if present).

+ +### `ToolAnnotations` + +
interface ToolAnnotations {
  destructiveHint?: boolean;
  idempotentHint?: boolean;
  openWorldHint?: boolean;
  readOnlyHint?: boolean;
  title?: string;
}

Additional properties describing a Tool to clients.

NOTE: all properties in ToolAnnotations are hints. +Clients should never make tool use decisions based on ToolAnnotations +received from untrusted servers.

destructiveHint?: boolean

If true, the tool may perform destructive updates to its environment. +If false, the tool performs only additive updates.

(This property is meaningful only when readOnlyHint == false)

Default: true

idempotentHint?: boolean

If true, calling the tool repeatedly with the same arguments +will have no additional effect on the its environment.

(This property is meaningful only when readOnlyHint == false)

Default: false

openWorldHint?: boolean

If true, this tool may interact with an "open world" of external +entities. If false, the tool's domain of interaction is closed.

Default: true

readOnlyHint?: boolean

If true, the tool does not modify its environment.

Default: false

title?: string

A human-readable title for the tool.

+ +### `ToolScope` + +
interface ToolScope {
  actions: ("list" | "call")[];
  name?: string;
  namePattern?: string;
  type: "tool";
}
name?: string

Specific tool name or pattern.

+ +### `UNAUTHORIZED` + +
UNAUTHORIZED: 4900

Unauthorized: missing or invalid identity/capabilities

+ +## `completion/complete` + +### `CompleteRequest` + +
interface CompleteRequest {
  method: "completion/complete";
  params: {
    argument: { name: string; value: string };
    context?: { arguments?: { [key: string]: string } };
    ref: PromptReference | ResourceTemplateReference;
  };
}

A request from the client to the server, to ask for completion options.

params: {
  argument: { name: string; value: string };
  context?: { arguments?: { [key: string]: string } };
  ref: PromptReference | ResourceTemplateReference;
}
Type declaration
  • argument: { name: string; value: string }

    The argument's information

    • name: string

      The name of the argument

    • value: string

      The value of the argument to use for completion matching.

  • Optionalcontext?: { arguments?: { [key: string]: string } }

    Additional, optional context for completions

    • Optionalarguments?: { [key: string]: string }

      Previously-resolved variables in a URI template or prompt.

+ +### `CompleteResult` + +
interface CompleteResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  completion: { hasMore?: boolean; total?: number; values: string[] };
  [key: string]: unknown;
}

The server's response to a completion/complete request

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

completion: { hasMore?: boolean; total?: number; values: string[] }
Type declaration
  • OptionalhasMore?: boolean

    Indicates whether there are additional completion options beyond those provided in the current response, even if the exact total is unknown.

  • Optionaltotal?: number

    The total number of completion options available. This can exceed the number of values actually sent in the response.

  • values: string[]

    An array of completion values. Must not exceed 100 items.

+ +## `elicitation/create` + +### `ElicitRequest` + +
interface ElicitRequest {
  method: "elicitation/create";
  params: {
    message: string;
    requestedSchema: {
      properties: { [key: string]: PrimitiveSchemaDefinition };
      required?: string[];
      type: "object";
    };
  };
}

A request from the server to elicit additional information from the user via the client.

params: {
  message: string;
  requestedSchema: {
    properties: { [key: string]: PrimitiveSchemaDefinition };
    required?: string[];
    type: "object";
  };
}
Type declaration
  • message: string

    The message to present to the user.

  • requestedSchema: {
      properties: { [key: string]: PrimitiveSchemaDefinition };
      required?: string[];
      type: "object";
    }

    A restricted subset of JSON Schema. +Only top-level properties are allowed, without nesting.

+ +### `ElicitResult` + +
interface ElicitResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  action: "accept" | "decline" | "cancel";
  content?: { [key: string]: string | number | boolean };
  [key: string]: unknown;
}

The client's response to an elicitation request.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

action: "accept" | "decline" | "cancel"

The user action in response to the elicitation.

  • "accept": User submitted the form/confirmed the action
  • "decline": User explicitly declined the action
  • "cancel": User dismissed without making an explicit choice
Optionalcontent
content?: { [key: string]: string | number | boolean }

The submitted form data, only present when action is "accept". +Contains values matching the requested schema.

+ +## `initialize` + +### `InitializeRequest` + +
interface InitializeRequest {
  method: "initialize";
  params: {
    capabilities: ClientCapabilities;
    clientInfo: Implementation;
    protocolVersion: string;
  };
}

This request is sent from the client to the server when it first connects, asking it to begin initialization.

params: {
  capabilities: ClientCapabilities;
  clientInfo: Implementation;
  protocolVersion: string;
}
Type declaration
  • capabilities: ClientCapabilities
  • clientInfo: Implementation
  • protocolVersion: string

    The latest version of the Model Context Protocol that the client supports. The client MAY decide to support older versions as well.

+ +### `InitializeResult` + +
interface InitializeResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  capabilities: ServerCapabilities;
  instructions?: string;
  protocolVersion: string;
  serverInfo: Implementation;
  [key: string]: unknown;
}

After receiving an initialize request from the client, the server sends this response.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

instructions?: string

Instructions describing how to use the server and its features.

This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt.

protocolVersion: string

The version of the Model Context Protocol that the server wants to use. This may not match the version that the client requested. If the client cannot support this version, it MUST disconnect.

+ +## `logging/setLevel` + +### `SetLevelRequest` + +
interface SetLevelRequest {
  method: "logging/setLevel";
  params: { level: LoggingLevel };
}

A request from the client to the server, to enable or adjust logging.

params: { level: LoggingLevel }
Type declaration

  • The level of logging that the client wants to receive from the server. The server should send all logs at this level and higher (i.e., more severe) to the client as notifications/message.

+ +## `notifications/cancelled` + +### `CancelledNotification` + +
interface CancelledNotification {
  method: "notifications/cancelled";
  params: { reason?: string; requestId: RequestId };
}

This notification can be sent by either side to indicate that it is cancelling a previously-issued request.

The request SHOULD still be in-flight, but due to communication latency, it is always possible that this notification MAY arrive after the request has already finished.

This notification indicates that the result will be unused, so any associated processing SHOULD cease.

A client MUST NOT attempt to cancel its initialize request.

params: { reason?: string; requestId: RequestId }
Type declaration
  • Optionalreason?: string

    An optional string describing the reason for the cancellation. This MAY be logged or presented to the user.

  • requestId: RequestId

    The ID of the request to cancel.

    This MUST correspond to the ID of a request previously issued in the same direction.

+ +## `notifications/initialized` + +### `InitializedNotification` + +
interface InitializedNotification {
  method: "notifications/initialized";
  params?: {
    _meta?: { security?: SecurityMeta; [key: string]: unknown };
    [key: string]: unknown;
  };
}

This notification is sent from the client to the server after initialization has finished.

params?: {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  [key: string]: unknown;
}
Type declaration
  • [key: string]: unknown
  • Optional_meta?: { security?: SecurityMeta; [key: string]: unknown }

    See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

+ +## `notifications/message` + +### `LoggingMessageNotification` + +
interface LoggingMessageNotification {
  method: "notifications/message";
  params: { data: unknown; level: LoggingLevel; logger?: string };
}

Notification of a log message passed from server to client. If no logging/setLevel request has been sent from the client, the server MAY decide which messages to send automatically.

params: { data: unknown; level: LoggingLevel; logger?: string }
Type declaration
  • data: unknown

    The data to be logged, such as a string message or an object. Any JSON serializable type is allowed here.

  • The severity of this log message.

  • Optionallogger?: string

    An optional name of the logger issuing this message.

+ +## `notifications/progress` + +### `ProgressNotification` + +
interface ProgressNotification {
  method: "notifications/progress";
  params: {
    message?: string;
    progress: number;
    progressToken: ProgressToken;
    total?: number;
  };
}

An out-of-band notification used to inform the receiver of a progress update for a long-running request.

params: {
  message?: string;
  progress: number;
  progressToken: ProgressToken;
  total?: number;
}
Type declaration
  • Optionalmessage?: string

    An optional message describing the current progress.

  • progress: number

    The progress thus far. This should increase every time progress is made, even if the total is unknown.

  • progressToken: ProgressToken

    The progress token which was given in the initial request, used to associate this notification with the request that is proceeding.

  • Optionaltotal?: number

    Total number of items to process (or total progress required), if known.

+ +## `notifications/prompts/list_changed` + +### `PromptListChangedNotification` + +
interface PromptListChangedNotification {
  method: "notifications/prompts/list_changed";
  params?: {
    _meta?: { security?: SecurityMeta; [key: string]: unknown };
    [key: string]: unknown;
  };
}

An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.

params?: {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  [key: string]: unknown;
}
Type declaration
  • [key: string]: unknown
  • Optional_meta?: { security?: SecurityMeta; [key: string]: unknown }

    See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

+ +## `notifications/resources/list_changed` + +### `ResourceListChangedNotification` + +
interface ResourceListChangedNotification {
  method: "notifications/resources/list_changed";
  params?: {
    _meta?: { security?: SecurityMeta; [key: string]: unknown };
    [key: string]: unknown;
  };
}

An optional notification from the server to the client, informing it that the list of resources it can read from has changed. This may be issued by servers without any previous subscription from the client.

params?: {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  [key: string]: unknown;
}
Type declaration
  • [key: string]: unknown
  • Optional_meta?: { security?: SecurityMeta; [key: string]: unknown }

    See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

+ +## `notifications/resources/updated` + +### `ResourceUpdatedNotification` + +
interface ResourceUpdatedNotification {
  method: "notifications/resources/updated";
  params: { uri: string };
}

A notification from the server to the client, informing it that a resource has changed and may need to be read again. This should only be sent if the client previously sent a resources/subscribe request.

params: { uri: string }
Type declaration
  • uri: string

    The URI of the resource that has been updated. This might be a sub-resource of the one that the client actually subscribed to.

+ +## `notifications/roots/list_changed` + +### `RootsListChangedNotification` + +
interface RootsListChangedNotification {
  method: "notifications/roots/list_changed";
  params?: {
    _meta?: { security?: SecurityMeta; [key: string]: unknown };
    [key: string]: unknown;
  };
}

A notification from the client to the server, informing it that the list of roots has changed.

params?: {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  [key: string]: unknown;
}
Type declaration
  • [key: string]: unknown
  • Optional_meta?: { security?: SecurityMeta; [key: string]: unknown }

    See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

+ +## `notifications/tools/list_changed` + +### `ToolListChangedNotification` + +
interface ToolListChangedNotification {
  method: "notifications/tools/list_changed";
  params?: {
    _meta?: { security?: SecurityMeta; [key: string]: unknown };
    [key: string]: unknown;
  };
}

An optional notification from the server to the client, informing it that the list of tools it offers has changed. This may be issued by servers without any previous subscription from the client.

params?: {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  [key: string]: unknown;
}
Type declaration
  • [key: string]: unknown
  • Optional_meta?: { security?: SecurityMeta; [key: string]: unknown }

    See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

+ +## `ping` + +### `PingRequest` + +
interface PingRequest {
  method: "ping";
  params?: {
    _meta?: {
      progressToken?: ProgressToken;
      security?: SecurityMeta;
      [key: string]: unknown;
    };
    [key: string]: unknown;
  };
}

A ping, issued by either the server or the client, to check that the other party is still alive. The receiver must promptly respond, or else may be disconnected.

params?: {
  _meta?: {
    progressToken?: ProgressToken;
    security?: SecurityMeta;
    [key: string]: unknown;
  };
  [key: string]: unknown;
}
Type declaration
  • [key: string]: unknown
  • Optional_meta?: {
      progressToken?: ProgressToken;
      security?: SecurityMeta;
      [key: string]: unknown;
    }

    See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

    • OptionalprogressToken?: ProgressToken

      If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications.

    • Optionalsecurity?: SecurityMeta

      Security envelope for this request. When present, receivers SHOULD validate according to their +security policy before processing the request.

+ +## `prompts/get` + +### `GetPromptRequest` + +
interface GetPromptRequest {
  method: "prompts/get";
  params: { arguments?: { [key: string]: string }; name: string };
}

Used by the client to get a prompt provided by the server.

params: { arguments?: { [key: string]: string }; name: string }
Type declaration
  • Optionalarguments?: { [key: string]: string }

    Arguments to use for templating the prompt.

  • name: string

    The name of the prompt or prompt template.

+ +### `GetPromptResult` + +
interface GetPromptResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  description?: string;
  messages: PromptMessage[];
  [key: string]: unknown;
}

The server's response to a prompts/get request from the client.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

description?: string

An optional description for the prompt.

+ +## `prompts/list` + +### `ListPromptsRequest` + +
interface ListPromptsRequest {
  method: "prompts/list";
  params?: { cursor?: string };
}

Sent from the client to request a list of prompts and prompt templates the server has.

params?: { cursor?: string }
Type declaration
  • Optionalcursor?: string

    An opaque token representing the current pagination position. +If provided, the server should return results starting after this cursor.

+ +### `ListPromptsResult` + +
interface ListPromptsResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  nextCursor?: string;
  prompts: Prompt[];
  [key: string]: unknown;
}

The server's response to a prompts/list request from the client.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

nextCursor?: string

An opaque token representing the pagination position after the last returned result. +If present, there may be more results available.

+ +## `resources/list` + +### `ListResourcesRequest` + +
interface ListResourcesRequest {
  method: "resources/list";
  params?: { cursor?: string };
}

Sent from the client to request a list of resources the server has.

params?: { cursor?: string }
Type declaration
  • Optionalcursor?: string

    An opaque token representing the current pagination position. +If provided, the server should return results starting after this cursor.

+ +### `ListResourcesResult` + +
interface ListResourcesResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  nextCursor?: string;
  resources: Resource[];
  [key: string]: unknown;
}

The server's response to a resources/list request from the client.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

nextCursor?: string

An opaque token representing the pagination position after the last returned result. +If present, there may be more results available.

+ +## `resources/read` + +### `ReadResourceRequest` + +
interface ReadResourceRequest {
  method: "resources/read";
  params: { uri: string };
}

Sent from the client to the server, to read a specific resource URI.

params: { uri: string }
Type declaration
  • uri: string

    The URI of the resource to read. The URI can use any protocol; it is up to the server how to interpret it.

+ +### `ReadResourceResult` + +
interface ReadResourceResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  contents: (TextResourceContents | BlobResourceContents)[];
  [key: string]: unknown;
}

The server's response to a resources/read request from the client.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

+ +## `resources/subscribe` + +### `SubscribeRequest` + +
interface SubscribeRequest {
  method: "resources/subscribe";
  params: { uri: string };
}

Sent from the client to request resources/updated notifications from the server whenever a particular resource changes.

params: { uri: string }
Type declaration
  • uri: string

    The URI of the resource to subscribe to. The URI can use any protocol; it is up to the server how to interpret it.

+ +## `resources/templates/list` + +### `ListResourceTemplatesRequest` + +
interface ListResourceTemplatesRequest {
  method: "resources/templates/list";
  params?: { cursor?: string };
}

Sent from the client to request a list of resource templates the server has.

params?: { cursor?: string }
Type declaration
  • Optionalcursor?: string

    An opaque token representing the current pagination position. +If provided, the server should return results starting after this cursor.

+ +### `ListResourceTemplatesResult` + +
interface ListResourceTemplatesResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  nextCursor?: string;
  resourceTemplates: ResourceTemplate[];
  [key: string]: unknown;
}

The server's response to a resources/templates/list request from the client.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

nextCursor?: string

An opaque token representing the pagination position after the last returned result. +If present, there may be more results available.

+ +## `resources/unsubscribe` + +### `UnsubscribeRequest` + +
interface UnsubscribeRequest {
  method: "resources/unsubscribe";
  params: { uri: string };
}

Sent from the client to request cancellation of resources/updated notifications from the server. This should follow a previous resources/subscribe request.

params: { uri: string }
Type declaration
  • uri: string

    The URI of the resource to unsubscribe from.

+ +## `roots/list` + +### `ListRootsRequest` + +
interface ListRootsRequest {
  method: "roots/list";
  params?: {
    _meta?: {
      progressToken?: ProgressToken;
      security?: SecurityMeta;
      [key: string]: unknown;
    };
    [key: string]: unknown;
  };
}

Sent from the server to request a list of root URIs from the client.

params?: {
  _meta?: {
    progressToken?: ProgressToken;
    security?: SecurityMeta;
    [key: string]: unknown;
  };
  [key: string]: unknown;
}
Type declaration
  • [key: string]: unknown
  • Optional_meta?: {
      progressToken?: ProgressToken;
      security?: SecurityMeta;
      [key: string]: unknown;
    }

    See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

    • OptionalprogressToken?: ProgressToken

      If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications.

    • Optionalsecurity?: SecurityMeta

      Security envelope for this request. When present, receivers SHOULD validate according to their +security policy before processing the request.

+ +### `ListRootsResult` + +
interface ListRootsResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  roots: Root[];
  [key: string]: unknown;
}

The client's response to a roots/list request from the server.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

+ +## `sampling/createMessage` + +### `CreateMessageRequest` + +
interface CreateMessageRequest {
  method: "sampling/createMessage";
  params: {
    includeContext?: "none" | "thisServer" | "allServers";
    maxTokens: number;
    messages: SamplingMessage[];
    metadata?: object;
    modelPreferences?: ModelPreferences;
    stopSequences?: string[];
    systemPrompt?: string;
    temperature?: number;
  };
}

A request from the server to sample an LLM via the client. The client has full discretion over which model to select. The client should also inform the user before beginning sampling, to allow them to inspect the request (human in the loop) and decide whether to approve it.

params: {
  includeContext?: "none" | "thisServer" | "allServers";
  maxTokens: number;
  messages: SamplingMessage[];
  metadata?: object;
  modelPreferences?: ModelPreferences;
  stopSequences?: string[];
  systemPrompt?: string;
  temperature?: number;
}
Type declaration
  • OptionalincludeContext?: "none" | "thisServer" | "allServers"

    A request to include context from one or more MCP servers (including the caller), to be attached to the prompt. The client MAY ignore this request.

  • maxTokens: number

    The maximum number of tokens to sample, as requested by the server. The client MAY choose to sample fewer tokens than requested.

  • messages: SamplingMessage[]
  • Optionalmetadata?: object

    Optional metadata to pass through to the LLM provider. The format of this metadata is provider-specific.

  • OptionalmodelPreferences?: ModelPreferences

    The server's preferences for which model to select. The client MAY ignore these preferences.

  • OptionalstopSequences?: string[]
  • OptionalsystemPrompt?: string

    An optional system prompt the server wants to use for sampling. The client MAY modify or omit this prompt.

  • Optionaltemperature?: number
+ +### `CreateMessageResult` + +
interface CreateMessageResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  content: TextContent | ImageContent | AudioContent;
  model: string;
  role: Role;
  stopReason?: string;
  [key: string]: unknown;
}

The client's response to a sampling/create_message request from the server. The client should inform the user before returning the sampled message, to allow them to inspect the response (human in the loop) and decide whether to allow the server to see it.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

model: string

The name of the model that generated the message.

stopReason?: string

The reason why sampling stopped, if known.

+ +## `security/issue` + +### `IssueCapabilitiesRequest` + +
interface IssueCapabilitiesRequest {
  method: "security/issue";
  params: {
    audience?: string;
    proof: IdentityProof;
    requested: CapabilityClaims[];
  };
}

Request capabilities from the server. Servers SHOULD validate the caller's identity proof and policy +before issuing any capabilities. Returned tokens are typically short-lived and fine-grained.

params: {
  audience?: string;
  proof: IdentityProof;
  requested: CapabilityClaims[];
}
Type declaration
  • Optionalaudience?: string

    Optional intended audience for the issued capabilities.

  • Identity proof binding this request to the caller.

  • requested: CapabilityClaims[]

    A list of requested capabilities. Servers MAY downscope or deny.

+ +## `tools/call` + +### `CallToolRequest` + +
interface CallToolRequest {
  method: "tools/call";
  params: { arguments?: { [key: string]: unknown }; name: string };
}

Used by the client to invoke a tool provided by the server.

+ +### `CallToolResult` + +
interface CallToolResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  content: ContentBlock[];
  isError?: boolean;
  structuredContent?: { [key: string]: unknown };
  [key: string]: unknown;
}

The server's response to a tool call.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

content
content: ContentBlock[]

A list of content objects that represent the unstructured result of the tool call.

isError?: boolean

Whether the tool call ended in an error.

If not set, this is assumed to be false (the call was successful).

Any errors that originate from the tool SHOULD be reported inside the result +object, with isError set to true, not as an MCP protocol-level error +response. Otherwise, the LLM would not be able to see that an error occurred +and self-correct.

However, any errors in finding the tool, an error indicating that the +server does not support tool calls, or any other exceptional conditions, +should be reported as an MCP error response.

structuredContent?: { [key: string]: unknown }

An optional JSON object that represents the structured result of the tool call.

+ +## `tools/list` + +### `ListToolsRequest` + +
interface ListToolsRequest {
  method: "tools/list";
  params?: { cursor?: string };
}

Sent from the client to request a list of tools the server has.

params?: { cursor?: string }
Type declaration
  • Optionalcursor?: string

    An opaque token representing the current pagination position. +If provided, the server should return results starting after this cursor.

+ +### `ListToolsResult` + +
interface ListToolsResult {
  _meta?: { security?: SecurityMeta; [key: string]: unknown };
  nextCursor?: string;
  tools: Tool[];
  [key: string]: unknown;
}

The server's response to a tools/list request from the client.

Optional_meta
_meta?: { security?: SecurityMeta; [key: string]: unknown }

See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.

nextCursor?: string

An opaque token representing the pagination position after the last returned result. +If present, there may be more results available.

diff --git a/schema/2025-08-09/schema.json b/schema/2025-08-09/schema.json new file mode 100644 index 000000000..d05e79358 --- /dev/null +++ b/schema/2025-08-09/schema.json @@ -0,0 +1,3159 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "definitions": { + "Annotations": { + "description": "Optional annotations for the client. The client can use annotations to inform how objects are used or displayed", + "properties": { + "audience": { + "description": "Describes who the intended customer of this object or data is.\n\nIt can include multiple entries to indicate content useful for multiple audiences (e.g., `[\"user\", \"assistant\"]`).", + "items": { + "$ref": "#/definitions/Role" + }, + "type": "array" + }, + "lastModified": { + "description": "The moment the resource was last modified, as an ISO 8601 formatted string.\n\nShould be an ISO 8601 formatted string (e.g., \"2025-01-12T15:00:58Z\").\n\nExamples: last activity timestamp in an open file, timestamp when the resource\nwas attached, etc.", + "type": "string" + }, + "priority": { + "description": "Describes how important this data is for operating the server.\n\nA value of 1 means \"most important,\" and indicates that the data is\neffectively required, while 0 means \"least important,\" and indicates that\nthe data is entirely optional.", + "maximum": 1, + "minimum": 0, + "type": "number" + } + }, + "type": "object" + }, + "AudioContent": { + "description": "Audio provided to or from an LLM.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "data": { + "description": "The base64-encoded audio data.", + "format": "byte", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of the audio. Different providers may support different audio types.", + "type": "string" + }, + "type": { + "const": "audio", + "type": "string" + } + }, + "required": [ + "data", + "mimeType", + "type" + ], + "type": "object" + }, + "BaseMetadata": { + "description": "Base interface for metadata with name (identifier) and title (display name) properties.", + "properties": { + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "BlobResourceContents": { + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "blob": { + "description": "A base64-encoded string representing the binary data of the item.", + "format": "byte", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "blob", + "uri" + ], + "type": "object" + }, + "BooleanSchema": { + "properties": { + "default": { + "type": "boolean" + }, + "description": { + "type": "string" + }, + "title": { + "type": "string" + }, + "type": { + "const": "boolean", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "CallToolRequest": { + "description": "Used by the client to invoke a tool provided by the server.", + "properties": { + "method": { + "const": "tools/call", + "type": "string" + }, + "params": { + "properties": { + "arguments": { + "additionalProperties": {}, + "type": "object" + }, + "name": { + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "CallToolResult": { + "description": "The server's response to a tool call.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "content": { + "description": "A list of content objects that represent the unstructured result of the tool call.", + "items": { + "$ref": "#/definitions/ContentBlock" + }, + "type": "array" + }, + "isError": { + "description": "Whether the tool call ended in an error.\n\nIf not set, this is assumed to be false (the call was successful).\n\nAny errors that originate from the tool SHOULD be reported inside the result\nobject, with `isError` set to true, _not_ as an MCP protocol-level error\nresponse. Otherwise, the LLM would not be able to see that an error occurred\nand self-correct.\n\nHowever, any errors in _finding_ the tool, an error indicating that the\nserver does not support tool calls, or any other exceptional conditions,\nshould be reported as an MCP error response.", + "type": "boolean" + }, + "structuredContent": { + "additionalProperties": {}, + "description": "An optional JSON object that represents the structured result of the tool call.", + "type": "object" + } + }, + "required": [ + "content" + ], + "type": "object" + }, + "CancelledNotification": { + "description": "This notification can be sent by either side to indicate that it is cancelling a previously-issued request.\n\nThe request SHOULD still be in-flight, but due to communication latency, it is always possible that this notification MAY arrive after the request has already finished.\n\nThis notification indicates that the result will be unused, so any associated processing SHOULD cease.\n\nA client MUST NOT attempt to cancel its `initialize` request.", + "properties": { + "method": { + "const": "notifications/cancelled", + "type": "string" + }, + "params": { + "properties": { + "reason": { + "description": "An optional string describing the reason for the cancellation. This MAY be logged or presented to the user.", + "type": "string" + }, + "requestId": { + "$ref": "#/definitions/RequestId", + "description": "The ID of the request to cancel.\n\nThis MUST correspond to the ID of a request previously issued in the same direction." + } + }, + "required": [ + "requestId" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "CapabilityClaims": { + "description": "Capability claims represent fine-grained authorization with constraints.", + "properties": { + "constraints": { + "$ref": "#/definitions/CapabilityConstraints", + "description": "Temporal and contextual constraints." + }, + "nonTransferable": { + "description": "Indicates token is bound to the presenter and is non-transferable.", + "type": "boolean" + }, + "scope": { + "description": "Actions and targets this token authorizes.", + "items": { + "$ref": "#/definitions/CapabilityScope" + }, + "type": "array" + } + }, + "required": [ + "scope" + ], + "type": "object" + }, + "CapabilityConstraints": { + "description": "Constraints limiting when/where a capability is valid.", + "properties": { + "audience": { + "description": "Intended audience identifier.", + "type": "string" + }, + "context": { + "additionalProperties": {}, + "description": "Optional additional constraint context.", + "type": "object" + }, + "expiresAt": { + "description": "Expiration time (ISO 8601).", + "type": "string" + }, + "issuer": { + "description": "Issuer identifier.", + "type": "string" + }, + "notBefore": { + "description": "Not valid before (ISO 8601).", + "type": "string" + }, + "subject": { + "description": "Subject identifier (e.g., client id).", + "type": "string" + } + }, + "type": "object" + }, + "CapabilityScope": { + "anyOf": [ + { + "$ref": "#/definitions/ResourceScope" + }, + { + "$ref": "#/definitions/ToolScope" + }, + { + "$ref": "#/definitions/PromptScope" + } + ], + "description": "Capability scopes for resources, tools, or prompts." + }, + "CapabilityToken": { + "description": "A structured capability token.", + "properties": { + "claims": { + "$ref": "#/definitions/CapabilityClaims", + "description": "Structured claims for object-encoded capabilities." + }, + "format": { + "description": "Encoding format when represented as a string.", + "enum": [ + "cwt", + "jwt", + "object", + "paseto" + ], + "type": "string" + }, + "id": { + "description": "Token identifier for audit/revocation.", + "type": "string" + }, + "token": { + "description": "Opaque representation for compact encodings; preferred when present.", + "type": "string" + } + }, + "type": "object" + }, + "ClientCapabilities": { + "description": "Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities.", + "properties": { + "elicitation": { + "additionalProperties": true, + "description": "Present if the client supports elicitation from the server.", + "properties": {}, + "type": "object" + }, + "experimental": { + "additionalProperties": { + "additionalProperties": true, + "properties": {}, + "type": "object" + }, + "description": "Experimental, non-standard capabilities that the client supports.", + "type": "object" + }, + "roots": { + "description": "Present if the client supports listing roots.", + "properties": { + "listChanged": { + "description": "Whether the client supports notifications for changes to the roots list.", + "type": "boolean" + } + }, + "type": "object" + }, + "sampling": { + "additionalProperties": true, + "description": "Present if the client supports sampling from an LLM.", + "properties": {}, + "type": "object" + }, + "security": { + "$ref": "#/definitions/SecurityCapabilities", + "description": "Security capabilities." + } + }, + "type": "object" + }, + "ClientNotification": { + "anyOf": [ + { + "$ref": "#/definitions/CancelledNotification" + }, + { + "$ref": "#/definitions/InitializedNotification" + }, + { + "$ref": "#/definitions/ProgressNotification" + }, + { + "$ref": "#/definitions/ResourceListChangedNotification" + }, + { + "$ref": "#/definitions/ResourceUpdatedNotification" + }, + { + "$ref": "#/definitions/PromptListChangedNotification" + }, + { + "$ref": "#/definitions/ToolListChangedNotification" + }, + { + "$ref": "#/definitions/LoggingMessageNotification" + }, + { + "$ref": "#/definitions/RootsListChangedNotification" + } + ] + }, + "ClientRequest": { + "anyOf": [ + { + "$ref": "#/definitions/InitializeRequest" + }, + { + "$ref": "#/definitions/PingRequest" + }, + { + "$ref": "#/definitions/ListResourcesRequest" + }, + { + "$ref": "#/definitions/ListResourceTemplatesRequest" + }, + { + "$ref": "#/definitions/ReadResourceRequest" + }, + { + "$ref": "#/definitions/SubscribeRequest" + }, + { + "$ref": "#/definitions/UnsubscribeRequest" + }, + { + "$ref": "#/definitions/ListPromptsRequest" + }, + { + "$ref": "#/definitions/GetPromptRequest" + }, + { + "$ref": "#/definitions/ListToolsRequest" + }, + { + "$ref": "#/definitions/CallToolRequest" + }, + { + "$ref": "#/definitions/SetLevelRequest" + }, + { + "$ref": "#/definitions/CompleteRequest" + }, + { + "$ref": "#/definitions/IssueCapabilitiesRequest" + } + ] + }, + "ClientResult": { + "anyOf": [ + { + "$ref": "#/definitions/Result" + }, + { + "$ref": "#/definitions/ListResourcesResult" + }, + { + "$ref": "#/definitions/ListResourceTemplatesResult" + }, + { + "$ref": "#/definitions/ReadResourceResult" + }, + { + "$ref": "#/definitions/ListPromptsResult" + }, + { + "$ref": "#/definitions/GetPromptResult" + }, + { + "$ref": "#/definitions/ListToolsResult" + }, + { + "$ref": "#/definitions/CallToolResult" + }, + { + "$ref": "#/definitions/CreateMessageResult" + }, + { + "$ref": "#/definitions/CompleteResult" + }, + { + "$ref": "#/definitions/ListRootsResult" + }, + { + "$ref": "#/definitions/ElicitResult" + }, + { + "$ref": "#/definitions/IssueCapabilitiesResult" + } + ] + }, + "CompleteRequest": { + "description": "A request from the client to the server, to ask for completion options.", + "properties": { + "method": { + "const": "completion/complete", + "type": "string" + }, + "params": { + "properties": { + "argument": { + "description": "The argument's information", + "properties": { + "name": { + "description": "The name of the argument", + "type": "string" + }, + "value": { + "description": "The value of the argument to use for completion matching.", + "type": "string" + } + }, + "required": [ + "name", + "value" + ], + "type": "object" + }, + "context": { + "description": "Additional, optional context for completions", + "properties": { + "arguments": { + "additionalProperties": { + "type": "string" + }, + "description": "Previously-resolved variables in a URI template or prompt.", + "type": "object" + } + }, + "type": "object" + }, + "ref": { + "anyOf": [ + { + "$ref": "#/definitions/PromptReference" + }, + { + "$ref": "#/definitions/ResourceTemplateReference" + } + ] + } + }, + "required": [ + "argument", + "ref" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "CompleteResult": { + "description": "The server's response to a completion/complete request", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "completion": { + "properties": { + "hasMore": { + "description": "Indicates whether there are additional completion options beyond those provided in the current response, even if the exact total is unknown.", + "type": "boolean" + }, + "total": { + "description": "The total number of completion options available. This can exceed the number of values actually sent in the response.", + "type": "integer" + }, + "values": { + "description": "An array of completion values. Must not exceed 100 items.", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "values" + ], + "type": "object" + } + }, + "required": [ + "completion" + ], + "type": "object" + }, + "ContentBlock": { + "anyOf": [ + { + "$ref": "#/definitions/TextContent" + }, + { + "$ref": "#/definitions/ImageContent" + }, + { + "$ref": "#/definitions/AudioContent" + }, + { + "$ref": "#/definitions/ResourceLink" + }, + { + "$ref": "#/definitions/EmbeddedResource" + } + ] + }, + "CreateMessageRequest": { + "description": "A request from the server to sample an LLM via the client. The client has full discretion over which model to select. The client should also inform the user before beginning sampling, to allow them to inspect the request (human in the loop) and decide whether to approve it.", + "properties": { + "method": { + "const": "sampling/createMessage", + "type": "string" + }, + "params": { + "properties": { + "includeContext": { + "description": "A request to include context from one or more MCP servers (including the caller), to be attached to the prompt. The client MAY ignore this request.", + "enum": [ + "allServers", + "none", + "thisServer" + ], + "type": "string" + }, + "maxTokens": { + "description": "The maximum number of tokens to sample, as requested by the server. The client MAY choose to sample fewer tokens than requested.", + "type": "integer" + }, + "messages": { + "items": { + "$ref": "#/definitions/SamplingMessage" + }, + "type": "array" + }, + "metadata": { + "additionalProperties": true, + "description": "Optional metadata to pass through to the LLM provider. The format of this metadata is provider-specific.", + "properties": {}, + "type": "object" + }, + "modelPreferences": { + "$ref": "#/definitions/ModelPreferences", + "description": "The server's preferences for which model to select. The client MAY ignore these preferences." + }, + "stopSequences": { + "items": { + "type": "string" + }, + "type": "array" + }, + "systemPrompt": { + "description": "An optional system prompt the server wants to use for sampling. The client MAY modify or omit this prompt.", + "type": "string" + }, + "temperature": { + "type": "number" + } + }, + "required": [ + "maxTokens", + "messages" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "CreateMessageResult": { + "description": "The client's response to a sampling/create_message request from the server. The client should inform the user before returning the sampled message, to allow them to inspect the response (human in the loop) and decide whether to allow the server to see it.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "content": { + "anyOf": [ + { + "$ref": "#/definitions/TextContent" + }, + { + "$ref": "#/definitions/ImageContent" + }, + { + "$ref": "#/definitions/AudioContent" + } + ] + }, + "model": { + "description": "The name of the model that generated the message.", + "type": "string" + }, + "role": { + "$ref": "#/definitions/Role" + }, + "stopReason": { + "description": "The reason why sampling stopped, if known.", + "type": "string" + } + }, + "required": [ + "content", + "model", + "role" + ], + "type": "object" + }, + "Cursor": { + "description": "An opaque token used to represent a cursor for pagination.", + "type": "string" + }, + "ElicitRequest": { + "description": "A request from the server to elicit additional information from the user via the client.", + "properties": { + "method": { + "const": "elicitation/create", + "type": "string" + }, + "params": { + "properties": { + "message": { + "description": "The message to present to the user.", + "type": "string" + }, + "requestedSchema": { + "description": "A restricted subset of JSON Schema.\nOnly top-level properties are allowed, without nesting.", + "properties": { + "properties": { + "additionalProperties": { + "$ref": "#/definitions/PrimitiveSchemaDefinition" + }, + "type": "object" + }, + "required": { + "items": { + "type": "string" + }, + "type": "array" + }, + "type": { + "const": "object", + "type": "string" + } + }, + "required": [ + "properties", + "type" + ], + "type": "object" + } + }, + "required": [ + "message", + "requestedSchema" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "ElicitResult": { + "description": "The client's response to an elicitation request.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "action": { + "description": "The user action in response to the elicitation.\n- \"accept\": User submitted the form/confirmed the action\n- \"decline\": User explicitly declined the action\n- \"cancel\": User dismissed without making an explicit choice", + "enum": [ + "accept", + "cancel", + "decline" + ], + "type": "string" + }, + "content": { + "additionalProperties": { + "type": [ + "string", + "integer", + "boolean" + ] + }, + "description": "The submitted form data, only present when action is \"accept\".\nContains values matching the requested schema.", + "type": "object" + } + }, + "required": [ + "action" + ], + "type": "object" + }, + "EmbeddedResource": { + "description": "The contents of a resource, embedded into a prompt or tool call result.\n\nIt is up to the client how best to render embedded resources for the benefit\nof the LLM and/or the user.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "resource": { + "anyOf": [ + { + "$ref": "#/definitions/TextResourceContents" + }, + { + "$ref": "#/definitions/BlobResourceContents" + } + ] + }, + "type": { + "const": "resource", + "type": "string" + } + }, + "required": [ + "resource", + "type" + ], + "type": "object" + }, + "EmptyResult": { + "$ref": "#/definitions/Result" + }, + "EncryptedPayload": { + "description": "JWE-like encrypted payload container for message-level encryption.", + "properties": { + "aad": { + "description": "Base64-encoded additional authenticated data (AAD) if used.", + "type": "string" + }, + "alg": { + "description": "Encryption algorithm (e.g., A256GCM, XC20P).", + "type": "string" + }, + "ciphertext": { + "description": "Base64-encoded ciphertext of the original JSON params.", + "type": "string" + }, + "iv": { + "description": "Base64-encoded initialization vector/nonce.", + "type": "string" + }, + "keyId": { + "description": "Key identifier for decryption.", + "type": "string" + }, + "tag": { + "description": "Base64-encoded authentication tag (if not implicit in ciphertext).", + "type": "string" + } + }, + "required": [ + "alg", + "ciphertext" + ], + "type": "object" + }, + "EnumSchema": { + "properties": { + "description": { + "type": "string" + }, + "enum": { + "items": { + "type": "string" + }, + "type": "array" + }, + "enumNames": { + "description": "Display names for enum values", + "items": { + "type": "string" + }, + "type": "array" + }, + "title": { + "type": "string" + }, + "type": { + "const": "string", + "type": "string" + } + }, + "required": [ + "enum", + "type" + ], + "type": "object" + }, + "GetPromptRequest": { + "description": "Used by the client to get a prompt provided by the server.", + "properties": { + "method": { + "const": "prompts/get", + "type": "string" + }, + "params": { + "properties": { + "arguments": { + "additionalProperties": { + "type": "string" + }, + "description": "Arguments to use for templating the prompt.", + "type": "object" + }, + "name": { + "description": "The name of the prompt or prompt template.", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "GetPromptResult": { + "description": "The server's response to a prompts/get request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "description": { + "description": "An optional description for the prompt.", + "type": "string" + }, + "messages": { + "items": { + "$ref": "#/definitions/PromptMessage" + }, + "type": "array" + } + }, + "required": [ + "messages" + ], + "type": "object" + }, + "IdentityProof": { + "description": "Identity proof carried alongside a message.", + "properties": { + "alg": { + "description": "Signature algorithm (e.g., EdDSA, ES256).", + "type": "string" + }, + "certificateChain": { + "description": "Optional X.509 certificate chain (PEM) when using PKI.", + "items": { + "type": "string" + }, + "type": "array" + }, + "jws": { + "description": "JOSE compact JWS with a detached payload over the canonical request envelope.", + "type": "string" + }, + "keyId": { + "description": "Key identifier understood by the receiver.", + "type": "string" + }, + "publicKey": { + "description": "Public key material (PEM or JWK) if out-of-band distribution is not available.", + "type": "string" + } + }, + "type": "object" + }, + "ImageContent": { + "description": "An image provided to or from an LLM.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "data": { + "description": "The base64-encoded image data.", + "format": "byte", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of the image. Different providers may support different image types.", + "type": "string" + }, + "type": { + "const": "image", + "type": "string" + } + }, + "required": [ + "data", + "mimeType", + "type" + ], + "type": "object" + }, + "Implementation": { + "description": "Describes the name and version of an MCP implementation, with an optional title for UI representation.", + "properties": { + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + }, + "version": { + "type": "string" + } + }, + "required": [ + "name", + "version" + ], + "type": "object" + }, + "InitializeRequest": { + "description": "This request is sent from the client to the server when it first connects, asking it to begin initialization.", + "properties": { + "method": { + "const": "initialize", + "type": "string" + }, + "params": { + "properties": { + "capabilities": { + "$ref": "#/definitions/ClientCapabilities" + }, + "clientInfo": { + "$ref": "#/definitions/Implementation" + }, + "protocolVersion": { + "description": "The latest version of the Model Context Protocol that the client supports. The client MAY decide to support older versions as well.", + "type": "string" + } + }, + "required": [ + "capabilities", + "clientInfo", + "protocolVersion" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "InitializeResult": { + "description": "After receiving an initialize request from the client, the server sends this response.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "capabilities": { + "$ref": "#/definitions/ServerCapabilities" + }, + "instructions": { + "description": "Instructions describing how to use the server and its features.\n\nThis can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a \"hint\" to the model. For example, this information MAY be added to the system prompt.", + "type": "string" + }, + "protocolVersion": { + "description": "The version of the Model Context Protocol that the server wants to use. This may not match the version that the client requested. If the client cannot support this version, it MUST disconnect.", + "type": "string" + }, + "serverInfo": { + "$ref": "#/definitions/Implementation" + } + }, + "required": [ + "capabilities", + "protocolVersion", + "serverInfo" + ], + "type": "object" + }, + "InitializedNotification": { + "description": "This notification is sent from the client to the server after initialization has finished.", + "properties": { + "method": { + "const": "notifications/initialized", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "IssueCapabilitiesRequest": { + "description": "Request capabilities from the server. Servers SHOULD validate the caller's identity proof and policy\nbefore issuing any capabilities. Returned tokens are typically short-lived and fine-grained.", + "properties": { + "method": { + "const": "security/issue", + "type": "string" + }, + "params": { + "properties": { + "audience": { + "description": "Optional intended audience for the issued capabilities.", + "type": "string" + }, + "proof": { + "$ref": "#/definitions/IdentityProof", + "description": "Identity proof binding this request to the caller." + }, + "requested": { + "description": "A list of requested capabilities. Servers MAY downscope or deny.", + "items": { + "$ref": "#/definitions/CapabilityClaims" + }, + "type": "array" + } + }, + "required": [ + "proof", + "requested" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "IssueCapabilitiesResult": { + "description": "Result of a capability issuance request.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "capabilities": { + "description": "Issued capability tokens.", + "items": { + "anyOf": [ + { + "$ref": "#/definitions/CapabilityToken" + }, + { + "type": "string" + } + ] + }, + "type": "array" + }, + "expiresAt": { + "description": "Optional common expiration for all returned tokens.", + "type": "string" + } + }, + "required": [ + "capabilities" + ], + "type": "object" + }, + "JSONRPCError": { + "description": "A response to a request that indicates an error occurred.", + "properties": { + "error": { + "properties": { + "code": { + "description": "The error type that occurred.", + "type": "integer" + }, + "data": { + "description": "Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.)." + }, + "message": { + "description": "A short description of the error. The message SHOULD be limited to a concise single sentence.", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "type": "object" + }, + "id": { + "$ref": "#/definitions/RequestId" + }, + "jsonrpc": { + "const": "2.0", + "type": "string" + } + }, + "required": [ + "error", + "id", + "jsonrpc" + ], + "type": "object" + }, + "JSONRPCMessage": { + "anyOf": [ + { + "$ref": "#/definitions/JSONRPCRequest" + }, + { + "$ref": "#/definitions/JSONRPCNotification" + }, + { + "$ref": "#/definitions/JSONRPCResponse" + }, + { + "$ref": "#/definitions/JSONRPCError" + } + ], + "description": "Refers to any valid JSON-RPC object that can be decoded off the wire, or encoded to be sent." + }, + "JSONRPCNotification": { + "description": "A notification which does not expect a response.", + "properties": { + "jsonrpc": { + "const": "2.0", + "type": "string" + }, + "method": { + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "jsonrpc", + "method" + ], + "type": "object" + }, + "JSONRPCRequest": { + "description": "A request that expects a response.", + "properties": { + "id": { + "$ref": "#/definitions/RequestId" + }, + "jsonrpc": { + "const": "2.0", + "type": "string" + }, + "method": { + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "progressToken": { + "$ref": "#/definitions/ProgressToken", + "description": "If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications." + }, + "security": { + "$ref": "#/definitions/SecurityMeta", + "description": "Security envelope for this request. When present, receivers SHOULD validate according to their\nsecurity policy before processing the request." + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "id", + "jsonrpc", + "method" + ], + "type": "object" + }, + "JSONRPCResponse": { + "description": "A successful (non-error) response to a request.", + "properties": { + "id": { + "$ref": "#/definitions/RequestId" + }, + "jsonrpc": { + "const": "2.0", + "type": "string" + }, + "result": { + "$ref": "#/definitions/Result" + } + }, + "required": [ + "id", + "jsonrpc", + "result" + ], + "type": "object" + }, + "ListPromptsRequest": { + "description": "Sent from the client to request a list of prompts and prompt templates the server has.", + "properties": { + "method": { + "const": "prompts/list", + "type": "string" + }, + "params": { + "properties": { + "cursor": { + "description": "An opaque token representing the current pagination position.\nIf provided, the server should return results starting after this cursor.", + "type": "string" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ListPromptsResult": { + "description": "The server's response to a prompts/list request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "nextCursor": { + "description": "An opaque token representing the pagination position after the last returned result.\nIf present, there may be more results available.", + "type": "string" + }, + "prompts": { + "items": { + "$ref": "#/definitions/Prompt" + }, + "type": "array" + } + }, + "required": [ + "prompts" + ], + "type": "object" + }, + "ListResourceTemplatesRequest": { + "description": "Sent from the client to request a list of resource templates the server has.", + "properties": { + "method": { + "const": "resources/templates/list", + "type": "string" + }, + "params": { + "properties": { + "cursor": { + "description": "An opaque token representing the current pagination position.\nIf provided, the server should return results starting after this cursor.", + "type": "string" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ListResourceTemplatesResult": { + "description": "The server's response to a resources/templates/list request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "nextCursor": { + "description": "An opaque token representing the pagination position after the last returned result.\nIf present, there may be more results available.", + "type": "string" + }, + "resourceTemplates": { + "items": { + "$ref": "#/definitions/ResourceTemplate" + }, + "type": "array" + } + }, + "required": [ + "resourceTemplates" + ], + "type": "object" + }, + "ListResourcesRequest": { + "description": "Sent from the client to request a list of resources the server has.", + "properties": { + "method": { + "const": "resources/list", + "type": "string" + }, + "params": { + "properties": { + "cursor": { + "description": "An opaque token representing the current pagination position.\nIf provided, the server should return results starting after this cursor.", + "type": "string" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ListResourcesResult": { + "description": "The server's response to a resources/list request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "nextCursor": { + "description": "An opaque token representing the pagination position after the last returned result.\nIf present, there may be more results available.", + "type": "string" + }, + "resources": { + "items": { + "$ref": "#/definitions/Resource" + }, + "type": "array" + } + }, + "required": [ + "resources" + ], + "type": "object" + }, + "ListRootsRequest": { + "description": "Sent from the server to request a list of root URIs from the client.", + "properties": { + "method": { + "const": "roots/list", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "progressToken": { + "$ref": "#/definitions/ProgressToken", + "description": "If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications." + }, + "security": { + "$ref": "#/definitions/SecurityMeta", + "description": "Security envelope for this request. When present, receivers SHOULD validate according to their\nsecurity policy before processing the request." + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ListRootsResult": { + "description": "The client's response to a roots/list request from the server.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "roots": { + "items": { + "$ref": "#/definitions/Root" + }, + "type": "array" + } + }, + "required": [ + "roots" + ], + "type": "object" + }, + "ListToolsRequest": { + "description": "Sent from the client to request a list of tools the server has.", + "properties": { + "method": { + "const": "tools/list", + "type": "string" + }, + "params": { + "properties": { + "cursor": { + "description": "An opaque token representing the current pagination position.\nIf provided, the server should return results starting after this cursor.", + "type": "string" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ListToolsResult": { + "description": "The server's response to a tools/list request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "nextCursor": { + "description": "An opaque token representing the pagination position after the last returned result.\nIf present, there may be more results available.", + "type": "string" + }, + "tools": { + "items": { + "$ref": "#/definitions/Tool" + }, + "type": "array" + } + }, + "required": [ + "tools" + ], + "type": "object" + }, + "LoggingLevel": { + "description": "The severity of a log message.\n\nThese map to syslog message severities, as specified in RFC-5424:\nhttps://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1", + "enum": [ + "alert", + "critical", + "debug", + "emergency", + "error", + "info", + "notice", + "warning" + ], + "type": "string" + }, + "LoggingMessageNotification": { + "description": "Notification of a log message passed from server to client. If no logging/setLevel request has been sent from the client, the server MAY decide which messages to send automatically.", + "properties": { + "method": { + "const": "notifications/message", + "type": "string" + }, + "params": { + "properties": { + "data": { + "description": "The data to be logged, such as a string message or an object. Any JSON serializable type is allowed here." + }, + "level": { + "$ref": "#/definitions/LoggingLevel", + "description": "The severity of this log message." + }, + "logger": { + "description": "An optional name of the logger issuing this message.", + "type": "string" + } + }, + "required": [ + "data", + "level" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "ModelHint": { + "description": "Hints to use for model selection.", + "properties": { + "name": { + "description": "A hint for a model name.", + "type": "string" + } + }, + "type": "object" + }, + "ModelPreferences": { + "description": "The server's preferences for model selection, requested of the client during sampling.", + "properties": { + "costPriority": { + "description": "How much to prioritize cost when selecting a model. A value of 0 means cost\nis not important, while a value of 1 means cost is the most important\nfactor.", + "maximum": 1, + "minimum": 0, + "type": "number" + }, + "hints": { + "description": "Optional hints to use for model selection.\n\nIf multiple hints are specified, the client MUST evaluate them in order\n(such that the first match is taken).\n\nThe client SHOULD prioritize these hints over the numeric priorities, but\nMAY still use the priorities to select from ambiguous matches.", + "items": { + "$ref": "#/definitions/ModelHint" + }, + "type": "array" + }, + "intelligencePriority": { + "description": "How much to prioritize intelligence and capabilities when selecting a\nmodel. A value of 0 means intelligence is not important, while a value of 1\nmeans intelligence is the most important factor.", + "maximum": 1, + "minimum": 0, + "type": "number" + }, + "speedPriority": { + "description": "How much to prioritize sampling speed (latency) when selecting a model. A\nvalue of 0 means speed is not important, while a value of 1 means speed is\nthe most important factor.", + "maximum": 1, + "minimum": 0, + "type": "number" + } + }, + "type": "object" + }, + "Notification": { + "properties": { + "method": { + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "NumberSchema": { + "properties": { + "description": { + "type": "string" + }, + "maximum": { + "type": "integer" + }, + "minimum": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "type": { + "enum": [ + "integer", + "number" + ], + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "PaginatedRequest": { + "properties": { + "method": { + "type": "string" + }, + "params": { + "properties": { + "cursor": { + "description": "An opaque token representing the current pagination position.\nIf provided, the server should return results starting after this cursor.", + "type": "string" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "PaginatedResult": { + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "nextCursor": { + "description": "An opaque token representing the pagination position after the last returned result.\nIf present, there may be more results available.", + "type": "string" + } + }, + "type": "object" + }, + "PingRequest": { + "description": "A ping, issued by either the server or the client, to check that the other party is still alive. The receiver must promptly respond, or else may be disconnected.", + "properties": { + "method": { + "const": "ping", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "progressToken": { + "$ref": "#/definitions/ProgressToken", + "description": "If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications." + }, + "security": { + "$ref": "#/definitions/SecurityMeta", + "description": "Security envelope for this request. When present, receivers SHOULD validate according to their\nsecurity policy before processing the request." + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "PrimitiveSchemaDefinition": { + "anyOf": [ + { + "$ref": "#/definitions/StringSchema" + }, + { + "$ref": "#/definitions/NumberSchema" + }, + { + "$ref": "#/definitions/BooleanSchema" + }, + { + "$ref": "#/definitions/EnumSchema" + } + ], + "description": "Restricted schema definitions that only allow primitive types\nwithout nested objects or arrays." + }, + "ProgressNotification": { + "description": "An out-of-band notification used to inform the receiver of a progress update for a long-running request.", + "properties": { + "method": { + "const": "notifications/progress", + "type": "string" + }, + "params": { + "properties": { + "message": { + "description": "An optional message describing the current progress.", + "type": "string" + }, + "progress": { + "description": "The progress thus far. This should increase every time progress is made, even if the total is unknown.", + "type": "number" + }, + "progressToken": { + "$ref": "#/definitions/ProgressToken", + "description": "The progress token which was given in the initial request, used to associate this notification with the request that is proceeding." + }, + "total": { + "description": "Total number of items to process (or total progress required), if known.", + "type": "number" + } + }, + "required": [ + "progress", + "progressToken" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "ProgressToken": { + "description": "A progress token, used to associate progress notifications with the original request.", + "type": [ + "string", + "integer" + ] + }, + "Prompt": { + "description": "A prompt or prompt template that the server offers.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "arguments": { + "description": "A list of arguments to use for templating the prompt.", + "items": { + "$ref": "#/definitions/PromptArgument" + }, + "type": "array" + }, + "description": { + "description": "An optional description of what this prompt provides", + "type": "string" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "PromptArgument": { + "description": "Describes an argument that a prompt can accept.", + "properties": { + "description": { + "description": "A human-readable description of the argument.", + "type": "string" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "required": { + "description": "Whether this argument must be provided.", + "type": "boolean" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "PromptListChangedNotification": { + "description": "An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.", + "properties": { + "method": { + "const": "notifications/prompts/list_changed", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "PromptMessage": { + "description": "Describes a message returned as part of a prompt.\n\nThis is similar to `SamplingMessage`, but also supports the embedding of\nresources from the MCP server.", + "properties": { + "content": { + "$ref": "#/definitions/ContentBlock" + }, + "role": { + "$ref": "#/definitions/Role" + } + }, + "required": [ + "content", + "role" + ], + "type": "object" + }, + "PromptReference": { + "description": "Identifies a prompt.", + "properties": { + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + }, + "type": { + "const": "ref/prompt", + "type": "string" + } + }, + "required": [ + "name", + "type" + ], + "type": "object" + }, + "PromptScope": { + "properties": { + "actions": { + "items": { + "enum": [ + "get", + "list" + ], + "type": "string" + }, + "type": "array" + }, + "name": { + "description": "Specific prompt name or pattern.", + "type": "string" + }, + "namePattern": { + "type": "string" + }, + "type": { + "const": "prompt", + "type": "string" + } + }, + "required": [ + "actions", + "type" + ], + "type": "object" + }, + "ReadResourceRequest": { + "description": "Sent from the client to the server, to read a specific resource URI.", + "properties": { + "method": { + "const": "resources/read", + "type": "string" + }, + "params": { + "properties": { + "uri": { + "description": "The URI of the resource to read. The URI can use any protocol; it is up to the server how to interpret it.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "ReadResourceResult": { + "description": "The server's response to a resources/read request from the client.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + }, + "contents": { + "items": { + "anyOf": [ + { + "$ref": "#/definitions/TextResourceContents" + }, + { + "$ref": "#/definitions/BlobResourceContents" + } + ] + }, + "type": "array" + } + }, + "required": [ + "contents" + ], + "type": "object" + }, + "Request": { + "properties": { + "method": { + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "progressToken": { + "$ref": "#/definitions/ProgressToken", + "description": "If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications." + }, + "security": { + "$ref": "#/definitions/SecurityMeta", + "description": "Security envelope for this request. When present, receivers SHOULD validate according to their\nsecurity policy before processing the request." + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "RequestId": { + "description": "A uniquely identifying ID for a request in JSON-RPC.", + "type": [ + "string", + "integer" + ] + }, + "Resource": { + "description": "A known resource that the server is capable of reading.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "description": { + "description": "A description of what this resource represents.\n\nThis can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "size": { + "description": "The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.\n\nThis can be used by Hosts to display file sizes and estimate context window usage.", + "type": "integer" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "name", + "uri" + ], + "type": "object" + }, + "ResourceContents": { + "description": "The contents of a specific resource or sub-resource.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + }, + "ResourceLink": { + "description": "A resource that the server is capable of reading, included in a prompt or tool call result.\n\nNote: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "description": { + "description": "A description of what this resource represents.\n\nThis can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.", + "type": "string" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "size": { + "description": "The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.\n\nThis can be used by Hosts to display file sizes and estimate context window usage.", + "type": "integer" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + }, + "type": { + "const": "resource_link", + "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "name", + "type", + "uri" + ], + "type": "object" + }, + "ResourceListChangedNotification": { + "description": "An optional notification from the server to the client, informing it that the list of resources it can read from has changed. This may be issued by servers without any previous subscription from the client.", + "properties": { + "method": { + "const": "notifications/resources/list_changed", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ResourceScope": { + "properties": { + "actions": { + "items": { + "enum": [ + "list", + "read", + "subscribe", + "templates_list", + "unsubscribe" + ], + "type": "string" + }, + "type": "array" + }, + "type": { + "const": "resource", + "type": "string" + }, + "uri": { + "description": "Exact URI or template this scope applies to.", + "type": "string" + }, + "uriTemplate": { + "description": "RFC 6570 URI template or glob-like pattern.", + "type": "string" + } + }, + "required": [ + "actions", + "type" + ], + "type": "object" + }, + "ResourceTemplate": { + "description": "A template description for resources available on the server.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "description": { + "description": "A description of what this template is for.\n\nThis can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a \"hint\" to the model.", + "type": "string" + }, + "mimeType": { + "description": "The MIME type for all resources that match this template. This should only be included if all resources matching this template have the same type.", + "type": "string" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + }, + "uriTemplate": { + "description": "A URI template (according to RFC 6570) that can be used to construct resource URIs.", + "format": "uri-template", + "type": "string" + } + }, + "required": [ + "name", + "uriTemplate" + ], + "type": "object" + }, + "ResourceTemplateReference": { + "description": "A reference to a resource or resource template definition.", + "properties": { + "type": { + "const": "ref/resource", + "type": "string" + }, + "uri": { + "description": "The URI or URI template of the resource.", + "format": "uri-template", + "type": "string" + } + }, + "required": [ + "type", + "uri" + ], + "type": "object" + }, + "ResourceUpdatedNotification": { + "description": "A notification from the server to the client, informing it that a resource has changed and may need to be read again. This should only be sent if the client previously sent a resources/subscribe request.", + "properties": { + "method": { + "const": "notifications/resources/updated", + "type": "string" + }, + "params": { + "properties": { + "uri": { + "description": "The URI of the resource that has been updated. This might be a sub-resource of the one that the client actually subscribed to.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "Result": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "Role": { + "description": "The sender or recipient of messages and data in a conversation.", + "enum": [ + "assistant", + "user" + ], + "type": "string" + }, + "Root": { + "description": "Represents a root directory or file that the server can operate on.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "name": { + "description": "An optional name for the root. This can be used to provide a human-readable\nidentifier for the root, which may be useful for display purposes or for\nreferencing the root in other parts of the application.", + "type": "string" + }, + "uri": { + "description": "The URI identifying the root. This *must* start with file:// for now.\nThis restriction may be relaxed in future versions of the protocol to allow\nother URI schemes.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + }, + "RootsListChangedNotification": { + "description": "A notification from the client to the server, informing it that the list of roots has changed.", + "properties": { + "method": { + "const": "notifications/roots/list_changed", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "SamplingMessage": { + "description": "Describes a message issued to or received from an LLM API.", + "properties": { + "content": { + "anyOf": [ + { + "$ref": "#/definitions/TextContent" + }, + { + "$ref": "#/definitions/ImageContent" + }, + { + "$ref": "#/definitions/AudioContent" + } + ] + }, + "role": { + "$ref": "#/definitions/Role" + } + }, + "required": [ + "content", + "role" + ], + "type": "object" + }, + "SecurityCapabilities": { + "description": "Supported security features and expectations for the connection.", + "properties": { + "acceptCapabilityFormats": { + "description": "Accepted capability token encodings.", + "items": { + "enum": [ + "cwt", + "jwt", + "object", + "paseto" + ], + "type": "string" + }, + "type": "array" + }, + "maxReplayWindowSeconds": { + "description": "Maximum allowable replay window in seconds.", + "type": "integer" + }, + "requireCapabilities": { + "description": "If true, the endpoint requires capability tokens for privileged operations.", + "type": "boolean" + }, + "requireSignedRequests": { + "description": "If true, the endpoint requires signed requests.", + "type": "boolean" + }, + "requireSignedResponses": { + "description": "If true, the endpoint requires signed responses.", + "type": "boolean" + }, + "supportedEncryptionAlgs": { + "description": "Supported encryption algorithms for payload-level encryption (JOSE/JWE name).", + "items": { + "type": "string" + }, + "type": "array" + }, + "supportedSignatureAlgs": { + "description": "Supported signature algorithms (JOSE name, e.g., \"EdDSA\", \"ES256\").", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "type": "object" + }, + "SecurityMeta": { + "description": "A structured security envelope attached to messages via `_meta.security`.", + "properties": { + "audit": { + "description": "Optional audit/tracing context propagated end-to-end.", + "properties": { + "requestId": { + "type": "string" + }, + "traceId": { + "type": "string" + } + }, + "type": "object" + }, + "capabilities": { + "description": "Capability tokens authorizing this specific request. Each entry may be an opaque string (e.g., JWT)\nor a structured object for constrained environments.", + "items": { + "anyOf": [ + { + "$ref": "#/definitions/CapabilityToken" + }, + { + "type": "string" + } + ] + }, + "type": "array" + }, + "encryption": { + "$ref": "#/definitions/EncryptedPayload", + "description": "Optional message-level encryption container. When present, `params` MAY be omitted\nand the receiver is expected to decrypt to recover the plaintext parameters." + }, + "identity": { + "$ref": "#/definitions/IdentityProof", + "description": "Proof of the sender's identity (e.g., JWS over a canonical request representation)." + }, + "integrity": { + "description": "Integrity information for the payload (e.g., payload hash over `params` after canonicalization, or over the decrypted plaintext when encrypted).", + "properties": { + "alg": { + "description": "Hash algorithm identifier (e.g., \"SHA-256\").", + "type": "string" + }, + "canonicalization": { + "description": "Optional canonicalization method identifier.", + "type": "string" + }, + "hash": { + "description": "Base64-encoded hash of the canonical payload.", + "type": "string" + } + }, + "required": [ + "alg", + "hash" + ], + "type": "object" + }, + "replay": { + "description": "Replay protection parameters.", + "properties": { + "nonce": { + "description": "Unique nonce for this message.", + "type": "string" + }, + "timestamp": { + "description": "Creation time in ISO 8601, used for replay windows.", + "type": "string" + } + }, + "required": [ + "nonce", + "timestamp" + ], + "type": "object" + } + }, + "type": "object" + }, + "ServerCapabilities": { + "description": "Capabilities that a server may support. Known capabilities are defined here, in this schema, but this is not a closed set: any server can define its own, additional capabilities.", + "properties": { + "completions": { + "additionalProperties": true, + "description": "Present if the server supports argument autocompletion suggestions.", + "properties": {}, + "type": "object" + }, + "experimental": { + "additionalProperties": { + "additionalProperties": true, + "properties": {}, + "type": "object" + }, + "description": "Experimental, non-standard capabilities that the server supports.", + "type": "object" + }, + "logging": { + "additionalProperties": true, + "description": "Present if the server supports sending log messages to the client.", + "properties": {}, + "type": "object" + }, + "prompts": { + "description": "Present if the server offers any prompt templates.", + "properties": { + "listChanged": { + "description": "Whether this server supports notifications for changes to the prompt list.", + "type": "boolean" + } + }, + "type": "object" + }, + "resources": { + "description": "Present if the server offers any resources to read.", + "properties": { + "listChanged": { + "description": "Whether this server supports notifications for changes to the resource list.", + "type": "boolean" + }, + "subscribe": { + "description": "Whether this server supports subscribing to resource updates.", + "type": "boolean" + } + }, + "type": "object" + }, + "security": { + "$ref": "#/definitions/SecurityCapabilities", + "description": "Security capabilities." + }, + "tools": { + "description": "Present if the server offers any tools to call.", + "properties": { + "listChanged": { + "description": "Whether this server supports notifications for changes to the tool list.", + "type": "boolean" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "ServerNotification": { + "anyOf": [ + { + "$ref": "#/definitions/CancelledNotification" + }, + { + "$ref": "#/definitions/ProgressNotification" + }, + { + "$ref": "#/definitions/ResourceListChangedNotification" + }, + { + "$ref": "#/definitions/ResourceUpdatedNotification" + }, + { + "$ref": "#/definitions/PromptListChangedNotification" + }, + { + "$ref": "#/definitions/ToolListChangedNotification" + }, + { + "$ref": "#/definitions/LoggingMessageNotification" + }, + { + "$ref": "#/definitions/RootsListChangedNotification" + } + ] + }, + "ServerRequest": { + "anyOf": [ + { + "$ref": "#/definitions/PingRequest" + }, + { + "$ref": "#/definitions/CreateMessageRequest" + }, + { + "$ref": "#/definitions/ListRootsRequest" + }, + { + "$ref": "#/definitions/ElicitRequest" + } + ] + }, + "ServerResult": { + "anyOf": [ + { + "$ref": "#/definitions/Result" + }, + { + "$ref": "#/definitions/InitializeResult" + }, + { + "$ref": "#/definitions/ListResourcesResult" + }, + { + "$ref": "#/definitions/ListResourceTemplatesResult" + }, + { + "$ref": "#/definitions/ReadResourceResult" + }, + { + "$ref": "#/definitions/ListPromptsResult" + }, + { + "$ref": "#/definitions/GetPromptResult" + }, + { + "$ref": "#/definitions/CallToolResult" + }, + { + "$ref": "#/definitions/CreateMessageResult" + }, + { + "$ref": "#/definitions/CompleteResult" + }, + { + "$ref": "#/definitions/ElicitResult" + }, + { + "$ref": "#/definitions/IssueCapabilitiesResult" + } + ] + }, + "SetLevelRequest": { + "description": "A request from the client to the server, to enable or adjust logging.", + "properties": { + "method": { + "const": "logging/setLevel", + "type": "string" + }, + "params": { + "properties": { + "level": { + "$ref": "#/definitions/LoggingLevel", + "description": "The level of logging that the client wants to receive from the server. The server should send all logs at this level and higher (i.e., more severe) to the client as notifications/message." + } + }, + "required": [ + "level" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "StringSchema": { + "properties": { + "description": { + "type": "string" + }, + "format": { + "enum": [ + "date", + "date-time", + "email", + "uri" + ], + "type": "string" + }, + "maxLength": { + "type": "integer" + }, + "minLength": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "type": { + "const": "string", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "SubscribeRequest": { + "description": "Sent from the client to request resources/updated notifications from the server whenever a particular resource changes.", + "properties": { + "method": { + "const": "resources/subscribe", + "type": "string" + }, + "params": { + "properties": { + "uri": { + "description": "The URI of the resource to subscribe to. The URI can use any protocol; it is up to the server how to interpret it.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + }, + "TextContent": { + "description": "Text provided to or from an LLM.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/Annotations", + "description": "Optional annotations for the client." + }, + "text": { + "description": "The text content of the message.", + "type": "string" + }, + "type": { + "const": "text", + "type": "string" + } + }, + "required": [ + "text", + "type" + ], + "type": "object" + }, + "TextResourceContents": { + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "mimeType": { + "description": "The MIME type of this resource, if known.", + "type": "string" + }, + "text": { + "description": "The text of the item. This must only be set if the item can actually be represented as text (not binary data).", + "type": "string" + }, + "uri": { + "description": "The URI of this resource.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "text", + "uri" + ], + "type": "object" + }, + "Tool": { + "description": "Definition for a tool the client can call.", + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "type": "object" + }, + "annotations": { + "$ref": "#/definitions/ToolAnnotations", + "description": "Optional additional tool information.\n\nDisplay name precedence order is: title, annotations.title, then name." + }, + "description": { + "description": "A human-readable description of the tool.\n\nThis can be used by clients to improve the LLM's understanding of available tools. It can be thought of like a \"hint\" to the model.", + "type": "string" + }, + "inputSchema": { + "description": "A JSON Schema object defining the expected parameters for the tool.", + "properties": { + "properties": { + "additionalProperties": { + "additionalProperties": true, + "properties": {}, + "type": "object" + }, + "type": "object" + }, + "required": { + "items": { + "type": "string" + }, + "type": "array" + }, + "type": { + "const": "object", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "name": { + "description": "Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present).", + "type": "string" + }, + "outputSchema": { + "description": "An optional JSON Schema object defining the structure of the tool's output returned in\nthe structuredContent field of a CallToolResult.", + "properties": { + "properties": { + "additionalProperties": { + "additionalProperties": true, + "properties": {}, + "type": "object" + }, + "type": "object" + }, + "required": { + "items": { + "type": "string" + }, + "type": "array" + }, + "type": { + "const": "object", + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "title": { + "description": "Intended for UI and end-user contexts — optimized to be human-readable and easily understood,\neven by those unfamiliar with domain-specific terminology.\n\nIf not provided, the name should be used for display (except for Tool,\nwhere `annotations.title` should be given precedence over using `name`,\nif present).", + "type": "string" + } + }, + "required": [ + "inputSchema", + "name" + ], + "type": "object" + }, + "ToolAnnotations": { + "description": "Additional properties describing a Tool to clients.\n\nNOTE: all properties in ToolAnnotations are hints.\nClients should never make tool use decisions based on ToolAnnotations\nreceived from untrusted servers.", + "properties": { + "destructiveHint": { + "description": "If true, the tool may perform destructive updates to its environment.\nIf false, the tool performs only additive updates.\n\n(This property is meaningful only when `readOnlyHint == false`)\n\nDefault: true", + "type": "boolean" + }, + "idempotentHint": { + "description": "If true, calling the tool repeatedly with the same arguments\nwill have no additional effect on the its environment.\n\n(This property is meaningful only when `readOnlyHint == false`)\n\nDefault: false", + "type": "boolean" + }, + "openWorldHint": { + "description": "If true, this tool may interact with an \"open world\" of external\nentities. If false, the tool's domain of interaction is closed.\n\nDefault: true", + "type": "boolean" + }, + "readOnlyHint": { + "description": "If true, the tool does not modify its environment.\n\nDefault: false", + "type": "boolean" + }, + "title": { + "description": "A human-readable title for the tool.", + "type": "string" + } + }, + "type": "object" + }, + "ToolListChangedNotification": { + "description": "An optional notification from the server to the client, informing it that the list of tools it offers has changed. This may be issued by servers without any previous subscription from the client.", + "properties": { + "method": { + "const": "notifications/tools/list_changed", + "type": "string" + }, + "params": { + "additionalProperties": {}, + "properties": { + "_meta": { + "additionalProperties": {}, + "description": "See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage.", + "properties": { + "security": { + "$ref": "#/definitions/SecurityMeta" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "required": [ + "method" + ], + "type": "object" + }, + "ToolScope": { + "properties": { + "actions": { + "items": { + "enum": [ + "call", + "list" + ], + "type": "string" + }, + "type": "array" + }, + "name": { + "description": "Specific tool name or pattern.", + "type": "string" + }, + "namePattern": { + "type": "string" + }, + "type": { + "const": "tool", + "type": "string" + } + }, + "required": [ + "actions", + "type" + ], + "type": "object" + }, + "UnsubscribeRequest": { + "description": "Sent from the client to request cancellation of resources/updated notifications from the server. This should follow a previous resources/subscribe request.", + "properties": { + "method": { + "const": "resources/unsubscribe", + "type": "string" + }, + "params": { + "properties": { + "uri": { + "description": "The URI of the resource to unsubscribe from.", + "format": "uri", + "type": "string" + } + }, + "required": [ + "uri" + ], + "type": "object" + } + }, + "required": [ + "method", + "params" + ], + "type": "object" + } + } +} + diff --git a/schema/2025-08-09/schema.ts b/schema/2025-08-09/schema.ts new file mode 100644 index 000000000..5b08fdae3 --- /dev/null +++ b/schema/2025-08-09/schema.ts @@ -0,0 +1,1768 @@ +/* JSON-RPC types (Security-focused MCP schema) */ + +/** + * Refers to any valid JSON-RPC object that can be decoded off the wire, or encoded to be sent. + * + * @internal + */ +export type JSONRPCMessage = + | JSONRPCRequest + | JSONRPCNotification + | JSONRPCResponse + | JSONRPCError; + +/** @internal */ +export const LATEST_PROTOCOL_VERSION = "2025-08-09"; +/** @internal */ +export const JSONRPC_VERSION = "2.0"; + +/** + * A progress token, used to associate progress notifications with the original request. + */ +export type ProgressToken = string | number; + +/** + * An opaque token used to represent a cursor for pagination. + */ +export type Cursor = string; + +/** @internal */ +export interface Request { + method: string; + params?: { + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { + /** + * If specified, the caller is requesting out-of-band progress notifications for this request (as represented by notifications/progress). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications. + */ + progressToken?: ProgressToken; + + /** + * Security envelope for this request. When present, receivers SHOULD validate according to their + * security policy before processing the request. + */ + security?: SecurityMeta; + + [key: string]: unknown; + }; + [key: string]: unknown; + }; +} + +/** @internal */ +export interface Notification { + method: string; + params?: { + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { security?: SecurityMeta; [key: string]: unknown }; + [key: string]: unknown; + }; +} + +export interface Result { + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { security?: SecurityMeta; [key: string]: unknown }; + [key: string]: unknown; +} + +/** + * A uniquely identifying ID for a request in JSON-RPC. + */ +export type RequestId = string | number; + +/** + * A request that expects a response. + */ +export interface JSONRPCRequest extends Request { + jsonrpc: typeof JSONRPC_VERSION; + id: RequestId; +} + +/** + * A notification which does not expect a response. + */ +export interface JSONRPCNotification extends Notification { + jsonrpc: typeof JSONRPC_VERSION; +} + +/** + * A successful (non-error) response to a request. + */ +export interface JSONRPCResponse { + jsonrpc: typeof JSONRPC_VERSION; + id: RequestId; + result: Result; +} + +// Standard JSON-RPC error codes +/** @internal */ +export const PARSE_ERROR = -32700; +/** @internal */ +export const INVALID_REQUEST = -32600; +/** @internal */ +export const METHOD_NOT_FOUND = -32601; +/** @internal */ +export const INVALID_PARAMS = -32602; +/** @internal */ +export const INTERNAL_ERROR = -32603; + +/** + * A response to a request that indicates an error occurred. + */ +export interface JSONRPCError { + jsonrpc: typeof JSONRPC_VERSION; + id: RequestId; + error: { + /** + * The error type that occurred. + */ + code: number; + /** + * A short description of the error. The message SHOULD be limited to a concise single sentence. + */ + message: string; + /** + * Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.). + */ + data?: unknown; + }; +} + +// MCP security-related error codes (non-standard JSON-RPC codes) +/** Unauthorized: missing or invalid identity/capabilities */ +export const UNAUTHORIZED = 4900; +/** Forbidden: capability present but does not allow this action */ +export const FORBIDDEN = 4901; +/** Replay detected based on nonce/timestamp */ +export const REPLAY_DETECTED = 4902; +/** Invalid signature or integrity hash */ +export const INVALID_SIGNATURE = 4903; +/** Capability token malformed */ +export const INVALID_CAPABILITY = 4904; +/** Capability token expired or not yet valid */ +export const EXPIRED_CAPABILITY = 4905; +/** Encryption required but not provided */ +export const ENCRYPTION_REQUIRED = 4906; +/** Decryption failed (e.g., wrong key) */ +export const DECRYPTION_FAILED = 4907; + +/* Empty result */ +/** + * A response that indicates success but carries no data. + */ +export type EmptyResult = Result; + +/* Cancellation */ +/** + * This notification can be sent by either side to indicate that it is cancelling a previously-issued request. + * + * The request SHOULD still be in-flight, but due to communication latency, it is always possible that this notification MAY arrive after the request has already finished. + * + * This notification indicates that the result will be unused, so any associated processing SHOULD cease. + * + * A client MUST NOT attempt to cancel its `initialize` request. + * + * @category notifications/cancelled + */ +export interface CancelledNotification extends Notification { + method: "notifications/cancelled"; + params: { + /** + * The ID of the request to cancel. + * + * This MUST correspond to the ID of a request previously issued in the same direction. + */ + requestId: RequestId; + + /** + * An optional string describing the reason for the cancellation. This MAY be logged or presented to the user. + */ + reason?: string; + }; +} + +/* Initialization */ +/** + * This request is sent from the client to the server when it first connects, asking it to begin initialization. + * + * @category initialize + */ +export interface InitializeRequest extends Request { + method: "initialize"; + params: { + /** + * The latest version of the Model Context Protocol that the client supports. The client MAY decide to support older versions as well. + */ + protocolVersion: string; + capabilities: ClientCapabilities; + clientInfo: Implementation; + }; +} + +/** + * After receiving an initialize request from the client, the server sends this response. + * + * @category initialize + */ +export interface InitializeResult extends Result { + /** + * The version of the Model Context Protocol that the server wants to use. This may not match the version that the client requested. If the client cannot support this version, it MUST disconnect. + */ + protocolVersion: string; + capabilities: ServerCapabilities; + serverInfo: Implementation; + + /** + * Instructions describing how to use the server and its features. + * + * This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt. + */ + instructions?: string; +} + +/** + * This notification is sent from the client to the server after initialization has finished. + * + * @category notifications/initialized + */ +export interface InitializedNotification extends Notification { + method: "notifications/initialized"; +} + +/** + * Capabilities a client may support. Known capabilities are defined here, in this schema, but this is not a closed set: any client can define its own, additional capabilities. + */ +export interface ClientCapabilities { + /** + * Experimental, non-standard capabilities that the client supports. + */ + experimental?: { [key: string]: object }; + /** + * Present if the client supports listing roots. + */ + roots?: { + /** + * Whether the client supports notifications for changes to the roots list. + */ + listChanged?: boolean; + }; + /** + * Present if the client supports sampling from an LLM. + */ + sampling?: object; + /** + * Present if the client supports elicitation from the server. + */ + elicitation?: object; + /** + * Security capabilities. + */ + security?: SecurityCapabilities; +} + +/** + * Capabilities that a server may support. Known capabilities are defined here, in this schema, but this is not a closed set: any server can define its own, additional capabilities. + */ +export interface ServerCapabilities { + /** + * Experimental, non-standard capabilities that the server supports. + */ + experimental?: { [key: string]: object }; + /** + * Present if the server supports sending log messages to the client. + */ + logging?: object; + /** + * Present if the server supports argument autocompletion suggestions. + */ + completions?: object; + /** + * Present if the server offers any prompt templates. + */ + prompts?: { + /** + * Whether this server supports notifications for changes to the prompt list. + */ + listChanged?: boolean; + }; + /** + * Present if the server offers any resources to read. + */ + resources?: { + /** + * Whether this server supports subscribing to resource updates. + */ + subscribe?: boolean; + /** + * Whether this server supports notifications for changes to the resource list. + */ + listChanged?: boolean; + }; + /** + * Present if the server offers any tools to call. + */ + tools?: { + /** + * Whether this server supports notifications for changes to the tool list. + */ + listChanged?: boolean; + }; + /** + * Security capabilities. + */ + security?: SecurityCapabilities; +} + +/** + * Base interface for metadata with name (identifier) and title (display name) properties. + * + * @internal + */ +export interface BaseMetadata { + /** + * Intended for programmatic or logical use, but used as a display name in past specs or fallback (if title isn't present). + */ + name: string; + + /** + * Intended for UI and end-user contexts — optimized to be human-readable and easily understood, + * even by those unfamiliar with domain-specific terminology. + * + * If not provided, the name should be used for display (except for Tool, + * where `annotations.title` should be given precedence over using `name`, + * if present). + */ + title?: string; +} + +/** + * Describes the name and version of an MCP implementation, with an optional title for UI representation. + */ +export interface Implementation extends BaseMetadata { + version: string; +} + +/* Ping */ +/** + * A ping, issued by either the server or the client, to check that the other party is still alive. The receiver must promptly respond, or else may be disconnected. + * + * @category ping + */ +export interface PingRequest extends Request { + method: "ping"; +} + +/* Progress notifications */ +/** + * An out-of-band notification used to inform the receiver of a progress update for a long-running request. + * + * @category notifications/progress + */ +export interface ProgressNotification extends Notification { + method: "notifications/progress"; + params: { + /** + * The progress token which was given in the initial request, used to associate this notification with the request that is proceeding. + */ + progressToken: ProgressToken; + /** + * The progress thus far. This should increase every time progress is made, even if the total is unknown. + * + * @TJS-type number + */ + progress: number; + /** + * Total number of items to process (or total progress required), if known. + * + * @TJS-type number + */ + total?: number; + /** + * An optional message describing the current progress. + */ + message?: string; + }; +} + +/* Pagination */ +/** @internal */ +export interface PaginatedRequest extends Request { + params?: { + /** + * An opaque token representing the current pagination position. + * If provided, the server should return results starting after this cursor. + */ + cursor?: Cursor; + }; +} + +/** @internal */ +export interface PaginatedResult extends Result { + /** + * An opaque token representing the pagination position after the last returned result. + * If present, there may be more results available. + */ + nextCursor?: Cursor; +} + +/* Resources */ +/** + * Sent from the client to request a list of resources the server has. + * + * @category resources/list + */ +export interface ListResourcesRequest extends PaginatedRequest { + method: "resources/list"; +} + +/** + * The server's response to a resources/list request from the client. + * + * @category resources/list + */ +export interface ListResourcesResult extends PaginatedResult { + resources: Resource[]; +} + +/** + * Sent from the client to request a list of resource templates the server has. + * + * @category resources/templates/list + */ +export interface ListResourceTemplatesRequest extends PaginatedRequest { + method: "resources/templates/list"; +} + +/** + * The server's response to a resources/templates/list request from the client. + * + * @category resources/templates/list + */ +export interface ListResourceTemplatesResult extends PaginatedResult { + resourceTemplates: ResourceTemplate[]; +} + +/** + * Sent from the client to the server, to read a specific resource URI. + * + * @category resources/read + */ +export interface ReadResourceRequest extends Request { + method: "resources/read"; + params: { + /** + * The URI of the resource to read. The URI can use any protocol; it is up to the server how to interpret it. + * + * @format uri + */ + uri: string; + }; +} + +/** + * The server's response to a resources/read request from the client. + * + * @category resources/read + */ +export interface ReadResourceResult extends Result { + contents: (TextResourceContents | BlobResourceContents)[]; +} + +/** + * An optional notification from the server to the client, informing it that the list of resources it can read from has changed. This may be issued by servers without any previous subscription from the client. + * + * @category notifications/resources/list_changed + */ +export interface ResourceListChangedNotification extends Notification { + method: "notifications/resources/list_changed"; +} + +/** + * Sent from the client to request resources/updated notifications from the server whenever a particular resource changes. + * + * @category resources/subscribe + */ +export interface SubscribeRequest extends Request { + method: "resources/subscribe"; + params: { + /** + * The URI of the resource to subscribe to. The URI can use any protocol; it is up to the server how to interpret it. + * + * @format uri + */ + uri: string; + }; +} + +/** + * Sent from the client to request cancellation of resources/updated notifications from the server. This should follow a previous resources/subscribe request. + * + * @category resources/unsubscribe + */ +export interface UnsubscribeRequest extends Request { + method: "resources/unsubscribe"; + params: { + /** + * The URI of the resource to unsubscribe from. + * + * @format uri + */ + uri: string; + }; +} + +/** + * A notification from the server to the client, informing it that a resource has changed and may need to be read again. This should only be sent if the client previously sent a resources/subscribe request. + * + * @category notifications/resources/updated + */ +export interface ResourceUpdatedNotification extends Notification { + method: "notifications/resources/updated"; + params: { + /** + * The URI of the resource that has been updated. This might be a sub-resource of the one that the client actually subscribed to. + * + * @format uri + */ + uri: string; + }; +} + +/** + * A known resource that the server is capable of reading. + */ +export interface Resource extends BaseMetadata { + /** + * The URI of this resource. + * + * @format uri + */ + uri: string; + + /** + * A description of what this resource represents. + * + * This can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a "hint" to the model. + */ + description?: string; + + /** + * The MIME type of this resource, if known. + */ + mimeType?: string; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known. + * + * This can be used by Hosts to display file sizes and estimate context window usage. + */ + size?: number; + + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * A template description for resources available on the server. + */ +export interface ResourceTemplate extends BaseMetadata { + /** + * A URI template (according to RFC 6570) that can be used to construct resource URIs. + * + * @format uri-template + */ + uriTemplate: string; + + /** + * A description of what this template is for. + * + * This can be used by clients to improve the LLM's understanding of available resources. It can be thought of like a "hint" to the model. + */ + description?: string; + + /** + * The MIME type for all resources that match this template. This should only be included if all resources matching this template have the same type. + */ + mimeType?: string; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * The contents of a specific resource or sub-resource. + */ +export interface ResourceContents { + /** + * The URI of this resource. + * + * @format uri + */ + uri: string; + /** + * The MIME type of this resource, if known. + */ + mimeType?: string; + + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +export interface TextResourceContents extends ResourceContents { + /** + * The text of the item. This must only be set if the item can actually be represented as text (not binary data). + */ + text: string; +} + +export interface BlobResourceContents extends ResourceContents { + /** + * A base64-encoded string representing the binary data of the item. + * + * @format byte + */ + blob: string; +} + +/* Prompts */ +/** + * Sent from the client to request a list of prompts and prompt templates the server has. + * + * @category prompts/list + */ +export interface ListPromptsRequest extends PaginatedRequest { + method: "prompts/list"; +} + +/** + * The server's response to a prompts/list request from the client. + * + * @category prompts/list + */ +export interface ListPromptsResult extends PaginatedResult { + prompts: Prompt[]; +} + +/** + * Used by the client to get a prompt provided by the server. + * + * @category prompts/get + */ +export interface GetPromptRequest extends Request { + method: "prompts/get"; + params: { + /** + * The name of the prompt or prompt template. + */ + name: string; + /** + * Arguments to use for templating the prompt. + */ + arguments?: { [key: string]: string }; + }; +} + +/** + * The server's response to a prompts/get request from the client. + * + * @category prompts/get + */ +export interface GetPromptResult extends Result { + /** + * An optional description for the prompt. + */ + description?: string; + messages: PromptMessage[]; +} + +/** + * A prompt or prompt template that the server offers. + */ +export interface Prompt extends BaseMetadata { + /** + * An optional description of what this prompt provides + */ + description?: string; + /** + * A list of arguments to use for templating the prompt. + */ + arguments?: PromptArgument[]; + + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * Describes an argument that a prompt can accept. + */ +export interface PromptArgument extends BaseMetadata { + /** + * A human-readable description of the argument. + */ + description?: string; + /** + * Whether this argument must be provided. + */ + required?: boolean; +} + +/** + * The sender or recipient of messages and data in a conversation. + */ +export type Role = "user" | "assistant"; + +/** + * Describes a message returned as part of a prompt. + * + * This is similar to `SamplingMessage`, but also supports the embedding of + * resources from the MCP server. + */ +export interface PromptMessage { + role: Role; + content: ContentBlock; +} + +/** + * A resource that the server is capable of reading, included in a prompt or tool call result. + * + * Note: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests. + */ +export interface ResourceLink extends Resource { + type: "resource_link"; +} + +/** + * The contents of a resource, embedded into a prompt or tool call result. + * + * It is up to the client how best to render embedded resources for the benefit + * of the LLM and/or the user. + */ +export interface EmbeddedResource { + type: "resource"; + resource: TextResourceContents | BlobResourceContents; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} +/** + * An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client. + * + * @category notifications/prompts/list_changed + */ +export interface PromptListChangedNotification extends Notification { + method: "notifications/prompts/list_changed"; +} + +/* Tools */ +/** + * Sent from the client to request a list of tools the server has. + * + * @category tools/list + */ +export interface ListToolsRequest extends PaginatedRequest { + method: "tools/list"; +} + +/** + * The server's response to a tools/list request from the client. + * + * @category tools/list + */ +export interface ListToolsResult extends PaginatedResult { + tools: Tool[]; +} + +/** + * The server's response to a tool call. + * + * @category tools/call + */ +export interface CallToolResult extends Result { + /** + * A list of content objects that represent the unstructured result of the tool call. + */ + content: ContentBlock[]; + + /** + * An optional JSON object that represents the structured result of the tool call. + */ + structuredContent?: { [key: string]: unknown }; + + /** + * Whether the tool call ended in an error. + * + * If not set, this is assumed to be false (the call was successful). + * + * Any errors that originate from the tool SHOULD be reported inside the result + * object, with `isError` set to true, _not_ as an MCP protocol-level error + * response. Otherwise, the LLM would not be able to see that an error occurred + * and self-correct. + * + * However, any errors in _finding_ the tool, an error indicating that the + * server does not support tool calls, or any other exceptional conditions, + * should be reported as an MCP error response. + */ + isError?: boolean; +} + +/** + * Used by the client to invoke a tool provided by the server. + * + * @category tools/call + */ +export interface CallToolRequest extends Request { + method: "tools/call"; + params: { + name: string; + arguments?: { [key: string]: unknown }; + }; +} + +/** + * An optional notification from the server to the client, informing it that the list of tools it offers has changed. This may be issued by servers without any previous subscription from the client. + * + * @category notifications/tools/list_changed + */ +export interface ToolListChangedNotification extends Notification { + method: "notifications/tools/list_changed"; +} + +/** + * Additional properties describing a Tool to clients. + * + * NOTE: all properties in ToolAnnotations are hints. + * Clients should never make tool use decisions based on ToolAnnotations + * received from untrusted servers. + */ +export interface ToolAnnotations { + /** + * A human-readable title for the tool. + */ + title?: string; + + /** + * If true, the tool does not modify its environment. + * + * Default: false + */ + readOnlyHint?: boolean; + + /** + * If true, the tool may perform destructive updates to its environment. + * If false, the tool performs only additive updates. + * + * (This property is meaningful only when `readOnlyHint == false`) + * + * Default: true + */ + destructiveHint?: boolean; + + /** + * If true, calling the tool repeatedly with the same arguments + * will have no additional effect on the its environment. + * + * (This property is meaningful only when `readOnlyHint == false`) + * + * Default: false + */ + idempotentHint?: boolean; + + /** + * If true, this tool may interact with an "open world" of external + * entities. If false, the tool's domain of interaction is closed. + * + * Default: true + */ + openWorldHint?: boolean; +} + +/** + * Definition for a tool the client can call. + */ +export interface Tool extends BaseMetadata { + /** + * A human-readable description of the tool. + * + * This can be used by clients to improve the LLM's understanding of available tools. It can be thought of like a "hint" to the model. + */ + description?: string; + + /** + * A JSON Schema object defining the expected parameters for the tool. + */ + inputSchema: { + type: "object"; + properties?: { [key: string]: object }; + required?: string[]; + }; + + /** + * An optional JSON Schema object defining the structure of the tool's output returned in + * the structuredContent field of a CallToolResult. + */ + outputSchema?: { + type: "object"; + properties?: { [key: string]: object }; + required?: string[]; + }; + + /** + * Optional additional tool information. + * + * Display name precedence order is: title, annotations.title, then name. + */ + annotations?: ToolAnnotations; + + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/* Logging */ +/** + * A request from the client to the server, to enable or adjust logging. + * + * @category logging/setLevel + */ +export interface SetLevelRequest extends Request { + method: "logging/setLevel"; + params: { + /** + * The level of logging that the client wants to receive from the server. The server should send all logs at this level and higher (i.e., more severe) to the client as notifications/message. + */ + level: LoggingLevel; + }; +} + +/** + * Notification of a log message passed from server to client. If no logging/setLevel request has been sent from the client, the server MAY decide which messages to send automatically. + * + * @category notifications/message + */ +export interface LoggingMessageNotification extends Notification { + method: "notifications/message"; + params: { + /** + * The severity of this log message. + */ + level: LoggingLevel; + /** + * An optional name of the logger issuing this message. + */ + logger?: string; + /** + * The data to be logged, such as a string message or an object. Any JSON serializable type is allowed here. + */ + data: unknown; + }; +} + +/** + * The severity of a log message. + * + * These map to syslog message severities, as specified in RFC-5424: + * https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1 + */ +export type LoggingLevel = + | "debug" + | "info" + | "notice" + | "warning" + | "error" + | "critical" + | "alert" + | "emergency"; + +/* Sampling */ +/** + * A request from the server to sample an LLM via the client. The client has full discretion over which model to select. The client should also inform the user before beginning sampling, to allow them to inspect the request (human in the loop) and decide whether to approve it. + * + * @category sampling/createMessage + */ +export interface CreateMessageRequest extends Request { + method: "sampling/createMessage"; + params: { + messages: SamplingMessage[]; + /** + * The server's preferences for which model to select. The client MAY ignore these preferences. + */ + modelPreferences?: ModelPreferences; + /** + * An optional system prompt the server wants to use for sampling. The client MAY modify or omit this prompt. + */ + systemPrompt?: string; + /** + * A request to include context from one or more MCP servers (including the caller), to be attached to the prompt. The client MAY ignore this request. + */ + includeContext?: "none" | "thisServer" | "allServers"; + /** + * @TJS-type number + */ + temperature?: number; + /** + * The maximum number of tokens to sample, as requested by the server. The client MAY choose to sample fewer tokens than requested. + */ + maxTokens: number; + stopSequences?: string[]; + /** + * Optional metadata to pass through to the LLM provider. The format of this metadata is provider-specific. + */ + metadata?: object; + }; +} + +/** + * The client's response to a sampling/create_message request from the server. The client should inform the user before returning the sampled message, to allow them to inspect the response (human in the loop) and decide whether to allow the server to see it. + * + * @category sampling/createMessage + */ +export interface CreateMessageResult extends Result, SamplingMessage { + /** + * The name of the model that generated the message. + */ + model: string; + /** + * The reason why sampling stopped, if known. + */ + stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string; +} + +/** + * Describes a message issued to or received from an LLM API. + */ +export interface SamplingMessage { + role: Role; + content: TextContent | ImageContent | AudioContent; +} + +/** + * Optional annotations for the client. The client can use annotations to inform how objects are used or displayed + */ +export interface Annotations { + /** + * Describes who the intended customer of this object or data is. + * + * It can include multiple entries to indicate content useful for multiple audiences (e.g., `["user", "assistant"]`). + */ + audience?: Role[]; + + /** + * Describes how important this data is for operating the server. + * + * A value of 1 means "most important," and indicates that the data is + * effectively required, while 0 means "least important," and indicates that + * the data is entirely optional. + * + * @TJS-type number + * @minimum 0 + * @maximum 1 + */ + priority?: number; + + /** + * The moment the resource was last modified, as an ISO 8601 formatted string. + * + * Should be an ISO 8601 formatted string (e.g., "2025-01-12T15:00:58Z"). + * + * Examples: last activity timestamp in an open file, timestamp when the resource + * was attached, etc. + */ + lastModified?: string; +} + +export type ContentBlock = + | TextContent + | ImageContent + | AudioContent + | ResourceLink + | EmbeddedResource; + +/** + * Text provided to or from an LLM. + */ +export interface TextContent { + type: "text"; + + /** + * The text content of the message. + */ + text: string; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * An image provided to or from an LLM. + */ +export interface ImageContent { + type: "image"; + + /** + * The base64-encoded image data. + * + * @format byte + */ + data: string; + + /** + * The MIME type of the image. Different providers may support different image types. + */ + mimeType: string; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * Audio provided to or from an LLM. + */ +export interface AudioContent { + type: "audio"; + + /** + * The base64-encoded audio data. + * + * @format byte + */ + data: string; + + /** + * The MIME type of the audio. Different providers may support different audio types. + */ + mimeType: string; + + /** + * Optional annotations for the client. + */ + annotations?: Annotations; + + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * The server's preferences for model selection, requested of the client during sampling. + */ +export interface ModelPreferences { + /** + * Optional hints to use for model selection. + * + * If multiple hints are specified, the client MUST evaluate them in order + * (such that the first match is taken). + * + * The client SHOULD prioritize these hints over the numeric priorities, but + * MAY still use the priorities to select from ambiguous matches. + */ + hints?: ModelHint[]; + + /** + * How much to prioritize cost when selecting a model. A value of 0 means cost + * is not important, while a value of 1 means cost is the most important + * factor. + * + * @TJS-type number + * @minimum 0 + * @maximum 1 + */ + costPriority?: number; + + /** + * How much to prioritize sampling speed (latency) when selecting a model. A + * value of 0 means speed is not important, while a value of 1 means speed is + * the most important factor. + * + * @TJS-type number + * @minimum 0 + * @maximum 1 + */ + speedPriority?: number; + + /** + * How much to prioritize intelligence and capabilities when selecting a + * model. A value of 0 means intelligence is not important, while a value of 1 + * means intelligence is the most important factor. + * + * @TJS-type number + * @minimum 0 + * @maximum 1 + */ + intelligencePriority?: number; +} + +/** + * Hints to use for model selection. + */ +export interface ModelHint { + /** + * A hint for a model name. + */ + name?: string; +} + +/* Autocomplete */ +/** + * A request from the client to the server, to ask for completion options. + * + * @category completion/complete + */ +export interface CompleteRequest extends Request { + method: "completion/complete"; + params: { + ref: PromptReference | ResourceTemplateReference; + /** + * The argument's information + */ + argument: { + /** + * The name of the argument + */ + name: string; + /** + * The value of the argument to use for completion matching. + */ + value: string; + }; + + /** + * Additional, optional context for completions + */ + context?: { + /** + * Previously-resolved variables in a URI template or prompt. + */ + arguments?: { [key: string]: string }; + }; + }; +} + +/** + * The server's response to a completion/complete request + * + * @category completion/complete + */ +export interface CompleteResult extends Result { + completion: { + /** + * An array of completion values. Must not exceed 100 items. + */ + values: string[]; + /** + * The total number of completion options available. This can exceed the number of values actually sent in the response. + */ + total?: number; + /** + * Indicates whether there are additional completion options beyond those provided in the current response, even if the exact total is unknown. + */ + hasMore?: boolean; + }; +} + +/** + * A reference to a resource or resource template definition. + */ +export interface ResourceTemplateReference { + type: "ref/resource"; + /** + * The URI or URI template of the resource. + * + * @format uri-template + */ + uri: string; +} + +/** + * Identifies a prompt. + */ +export interface PromptReference extends BaseMetadata { + type: "ref/prompt"; +} + +/* Roots */ +/** + * Sent from the server to request a list of root URIs from the client. + * + * @category roots/list + */ +export interface ListRootsRequest extends Request { + method: "roots/list"; +} + +/** + * The client's response to a roots/list request from the server. + * + * @category roots/list + */ +export interface ListRootsResult extends Result { + roots: Root[]; +} + +/** + * Represents a root directory or file that the server can operate on. + */ +export interface Root { + /** + * The URI identifying the root. This *must* start with file:// for now. + * This restriction may be relaxed in future versions of the protocol to allow + * other URI schemes. + * + * @format uri + */ + uri: string; + /** + * An optional name for the root. This can be used to provide a human-readable + * identifier for the root, which may be useful for display purposes or for + * referencing the root in other parts of the application. + */ + name?: string; + + /** + * See [specification/2025-08-09/basic/index#general-fields] for notes on _meta usage. + */ + _meta?: { [key: string]: unknown }; +} + +/** + * A notification from the client to the server, informing it that the list of roots has changed. + * + * @category notifications/roots/list_changed + */ +export interface RootsListChangedNotification extends Notification { + method: "notifications/roots/list_changed"; +} + +/* Elicitation */ +/** + * A request from the server to elicit additional information from the user via the client. + * + * @category elicitation/create + */ +export interface ElicitRequest extends Request { + method: "elicitation/create"; + params: { + /** + * The message to present to the user. + */ + message: string; + /** + * A restricted subset of JSON Schema. + * Only top-level properties are allowed, without nesting. + */ + requestedSchema: { + type: "object"; + properties: { + [key: string]: PrimitiveSchemaDefinition; + }; + required?: string[]; + }; + }; +} + +/** + * Restricted schema definitions that only allow primitive types + * without nested objects or arrays. + */ +export type PrimitiveSchemaDefinition = + | StringSchema + | NumberSchema + | BooleanSchema + | EnumSchema; + +export interface StringSchema { + type: "string"; + title?: string; + description?: string; + minLength?: number; + maxLength?: number; + format?: "email" | "uri" | "date" | "date-time"; +} + +export interface NumberSchema { + type: "number" | "integer"; + title?: string; + description?: string; + minimum?: number; + maximum?: number; +} + +export interface BooleanSchema { + type: "boolean"; + title?: string; + description?: string; + default?: boolean; +} + +export interface EnumSchema { + type: "string"; + title?: string; + description?: string; + enum: string[]; + /** Display names for enum values */ + enumNames?: string[]; +} + +/** + * The client's response to an elicitation request. + * + * @category elicitation/create + */ +export interface ElicitResult extends Result { + /** + * The user action in response to the elicitation. + * - "accept": User submitted the form/confirmed the action + * - "decline": User explicitly declined the action + * - "cancel": User dismissed without making an explicit choice + */ + action: "accept" | "decline" | "cancel"; + + /** + * The submitted form data, only present when action is "accept". + * Contains values matching the requested schema. + */ + content?: { [key: string]: string | number | boolean }; +} + +/* Security primitives */ + +/** + * Supported security features and expectations for the connection. + */ +export interface SecurityCapabilities { + /** + * If true, the endpoint requires signed requests. + */ + requireSignedRequests?: boolean; + /** + * If true, the endpoint requires signed responses. + */ + requireSignedResponses?: boolean; + /** + * If true, the endpoint requires capability tokens for privileged operations. + */ + requireCapabilities?: boolean; + /** + * Supported signature algorithms (JOSE name, e.g., "EdDSA", "ES256"). + */ + supportedSignatureAlgs?: string[]; + /** + * Supported encryption algorithms for payload-level encryption (JOSE/JWE name). + */ + supportedEncryptionAlgs?: string[]; + /** + * Accepted capability token encodings. + */ + acceptCapabilityFormats?: ("jwt" | "cwt" | "paseto" | "object")[]; + /** + * Maximum allowable replay window in seconds. + */ + maxReplayWindowSeconds?: number; +} + +/** + * A structured security envelope attached to messages via `_meta.security`. + */ +export interface SecurityMeta { + /** + * Proof of the sender's identity (e.g., JWS over a canonical request representation). + */ + identity?: IdentityProof; + + /** + * Capability tokens authorizing this specific request. Each entry may be an opaque string (e.g., JWT) + * or a structured object for constrained environments. + */ + capabilities?: (string | CapabilityToken)[]; + + /** + * Replay protection parameters. + */ + replay?: { + /** Unique nonce for this message. */ + nonce: string; + /** Creation time in ISO 8601, used for replay windows. */ + timestamp: string; + }; + + /** + * Integrity information for the payload (e.g., payload hash over `params` after canonicalization, or over the decrypted plaintext when encrypted). + */ + integrity?: { + /** Hash algorithm identifier (e.g., "SHA-256"). */ + alg: string; + /** Base64-encoded hash of the canonical payload. */ + hash: string; + /** Optional canonicalization method identifier. */ + canonicalization?: string; + }; + + /** + * Optional message-level encryption container. When present, `params` MAY be omitted + * and the receiver is expected to decrypt to recover the plaintext parameters. + */ + encryption?: EncryptedPayload; + + /** + * Optional audit/tracing context propagated end-to-end. + */ + audit?: { + traceId?: string; + requestId?: string; + }; +} + +/** Identity proof carried alongside a message. */ +export interface IdentityProof { + /** Key identifier understood by the receiver. */ + keyId?: string; + /** JOSE compact JWS with a detached payload over the canonical request envelope. */ + jws?: string; + /** Public key material (PEM or JWK) if out-of-band distribution is not available. */ + publicKey?: string; + /** Signature algorithm (e.g., EdDSA, ES256). */ + alg?: string; + /** Optional X.509 certificate chain (PEM) when using PKI. */ + certificateChain?: string[]; +} + +/** A structured capability token. */ +export interface CapabilityToken { + /** Token identifier for audit/revocation. */ + id?: string; + /** Encoding format when represented as a string. */ + format?: "jwt" | "cwt" | "paseto" | "object"; + /** Opaque representation for compact encodings; preferred when present. */ + token?: string; + /** Structured claims for object-encoded capabilities. */ + claims?: CapabilityClaims; +} + +/** Capability claims represent fine-grained authorization with constraints. */ +export interface CapabilityClaims { + /** Actions and targets this token authorizes. */ + scope: CapabilityScope[]; + /** Temporal and contextual constraints. */ + constraints?: CapabilityConstraints; + /** Indicates token is bound to the presenter and is non-transferable. */ + nonTransferable?: boolean; +} + +/** Constraints limiting when/where a capability is valid. */ +export interface CapabilityConstraints { + /** Not valid before (ISO 8601). */ + notBefore?: string; + /** Expiration time (ISO 8601). */ + expiresAt?: string; + /** Intended audience identifier. */ + audience?: string; + /** Issuer identifier. */ + issuer?: string; + /** Subject identifier (e.g., client id). */ + subject?: string; + /** Optional additional constraint context. */ + context?: { [key: string]: unknown }; +} + +/** Capability scopes for resources, tools, or prompts. */ +export type CapabilityScope = + | ResourceScope + | ToolScope + | PromptScope; + +export interface ResourceScope { + type: "resource"; + actions: ("read" | "subscribe" | "unsubscribe" | "list" | "templates_list")[]; + /** Exact URI or template this scope applies to. */ + uri?: string; + /** RFC 6570 URI template or glob-like pattern. */ + uriTemplate?: string; +} + +export interface ToolScope { + type: "tool"; + actions: ("call" | "list")[]; + /** Specific tool name or pattern. */ + name?: string; + namePattern?: string; +} + +export interface PromptScope { + type: "prompt"; + actions: ("get" | "list")[]; + /** Specific prompt name or pattern. */ + name?: string; + namePattern?: string; +} + +/** JWE-like encrypted payload container for message-level encryption. */ +export interface EncryptedPayload { + /** Encryption algorithm (e.g., A256GCM, XC20P). */ + alg: string; + /** Key identifier for decryption. */ + keyId?: string; + /** Base64-encoded initialization vector/nonce. */ + iv?: string; + /** Base64-encoded additional authenticated data (AAD) if used. */ + aad?: string; + /** Base64-encoded ciphertext of the original JSON params. */ + ciphertext: string; + /** Base64-encoded authentication tag (if not implicit in ciphertext). */ + tag?: string; +} + +/* Security service methods */ + +/** + * Request capabilities from the server. Servers SHOULD validate the caller's identity proof and policy + * before issuing any capabilities. Returned tokens are typically short-lived and fine-grained. + * + * @category security/issue + */ +export interface IssueCapabilitiesRequest extends Request { + method: "security/issue"; + params: { + /** A list of requested capabilities. Servers MAY downscope or deny. */ + requested: CapabilityClaims[]; + /** Identity proof binding this request to the caller. */ + proof: IdentityProof; + /** Optional intended audience for the issued capabilities. */ + audience?: string; + }; +} + +/** Result of a capability issuance request. */ +export interface IssueCapabilitiesResult extends Result { + /** Issued capability tokens. */ + capabilities: (string | CapabilityToken)[]; + /** Optional common expiration for all returned tokens. */ + expiresAt?: string; +} + +/* Client messages */ +/** @internal */ +export type ClientRequest = + | PingRequest + | InitializeRequest + | CompleteRequest + | SetLevelRequest + | GetPromptRequest + | ListPromptsRequest + | ListResourcesRequest + | ListResourceTemplatesRequest + | ReadResourceRequest + | SubscribeRequest + | UnsubscribeRequest + | CallToolRequest + | ListToolsRequest + | IssueCapabilitiesRequest; + +/** @internal */ +export type ClientNotification = + | CancelledNotification + | ProgressNotification + | InitializedNotification + | RootsListChangedNotification + | PromptListChangedNotification + | ResourceListChangedNotification + | ToolListChangedNotification + | ResourceUpdatedNotification + | LoggingMessageNotification; + +/** @internal */ +export type ClientResult = + | EmptyResult + | CreateMessageResult + | ListRootsResult + | ElicitResult + | IssueCapabilitiesResult + | ListResourcesResult + | ListResourceTemplatesResult + | ReadResourceResult + | ListToolsResult + | GetPromptResult + | ListPromptsResult + | CompleteResult + | CallToolResult; + +/* Server messages */ +/** @internal */ +export type ServerRequest = + | PingRequest + | CreateMessageRequest + | ListRootsRequest + | ElicitRequest; + +/** @internal */ +export type ServerNotification = + | CancelledNotification + | ProgressNotification + | LoggingMessageNotification + | ResourceUpdatedNotification + | ResourceListChangedNotification + | ToolListChangedNotification + | PromptListChangedNotification + | RootsListChangedNotification; + +/** @internal */ +export type ServerResult = + | EmptyResult + | InitializeResult + | CompleteResult + | GetPromptResult + | ListPromptsResult + | ListResourceTemplatesResult + | ListResourcesResult + | ReadResourceResult + | CallToolResult + | CreateMessageResult + | ElicitResult + | IssueCapabilitiesResult; + + diff --git a/tsconfig.json b/tsconfig.json index 1e339e42e..22412fb58 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -6,5 +6,7 @@ "forceConsistentCasingInFileNames": true, "strict": true, "skipLibCheck": true - } + }, + "include": ["schema/**/*.ts"], + "exclude": ["**/node_modules/**", "**/dist/**", "docs/**", "blog/**"] } From 01955fc198153c39da5711fd36486cbd6707b288 Mon Sep 17 00:00:00 2001 From: Em H Date: Sat, 9 Aug 2025 13:33:52 -0400 Subject: [PATCH 2/2] docs: Document security model --- docs/docs.json | 11 +++++++ docs/docs/security/capabilities.mdx | 47 +++++++++++++++++++++++++++++ docs/docs/security/crypto.mdx | 43 ++++++++++++++++++++++++++ docs/docs/security/envelope.mdx | 45 +++++++++++++++++++++++++++ docs/docs/security/errors.mdx | 16 ++++++++++ docs/docs/security/index.mdx | 29 ++++++++++++++++++ docs/docs/security/rollout.mdx | 22 ++++++++++++++ 7 files changed, 213 insertions(+) create mode 100644 docs/docs/security/capabilities.mdx create mode 100644 docs/docs/security/crypto.mdx create mode 100644 docs/docs/security/envelope.mdx create mode 100644 docs/docs/security/errors.mdx create mode 100644 docs/docs/security/index.mdx create mode 100644 docs/docs/security/rollout.mdx diff --git a/docs/docs.json b/docs/docs.json index 74c7c142f..fdfe5534b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -27,6 +27,17 @@ "pages": [ "docs/getting-started/intro", "docs/sdk", + { + "group": "Security", + "pages": [ + "docs/security/index", + "docs/security/envelope", + "docs/security/capabilities", + "docs/security/crypto", + "docs/security/errors", + "docs/security/rollout" + ] + }, { "group": "Concepts", "pages": [ diff --git a/docs/docs/security/capabilities.mdx b/docs/docs/security/capabilities.mdx new file mode 100644 index 000000000..46ce96cae --- /dev/null +++ b/docs/docs/security/capabilities.mdx @@ -0,0 +1,47 @@ +--- +title: Capability-Based Authorization +--- + +Capabilities provide fine-grained, time-bounded authorization per request. + +### Model + +- `CapabilityToken`: either a compact `token` (JWT, PASETO, CWT) or a structured `claims` object +- `CapabilityClaims`: + - `scope`: array of entries for resources, tools, and prompts + - `resource`: `{ type: "resource", actions: ["read"|"subscribe"|"unsubscribe"|"list"|"templates_list"], uri?, uriTemplate? }` + - `tool`: `{ type: "tool", actions: ["call"|"list"], name?, namePattern? }` + - `prompt`: `{ type: "prompt", actions: ["get"|"list"], name?, namePattern? }` + - `constraints`: `{ notBefore?, expiresAt?, audience?, issuer?, subject?, context? }` + - `nonTransferable`: boolean + +### Issuance RPC: `security/issue` + +Servers validate identity proof and policy, then issue scoped, short-lived capabilities. + +Request: + +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "security/issue", + "params": { + "requested": [ + { + "scope": [ + { + "type": "resource", + "actions": ["read"], + "uriTemplate": "file://*/README.md" + } + ], + "constraints": { "expiresAt": "2025-08-09T12:05:00Z" }, + "nonTransferable": true + } + ], + "proof": { "keyId": "kid:client", "alg": "EdDSA", "jws": "" }, + "audience": "urn:mcp:server" + } +} +``` diff --git a/docs/docs/security/crypto.mdx b/docs/docs/security/crypto.mdx new file mode 100644 index 000000000..bcf71b377 --- /dev/null +++ b/docs/docs/security/crypto.mdx @@ -0,0 +1,43 @@ +--- +title: Message-Level Cryptography +--- + +### Identity (signatures) + +- Carried in `_meta.security.identity`: `{ keyId, alg, jws, publicKey?, certificateChain? }` +- Use detached JWS over a canonical envelope; advertise algorithms in `supportedSignatureAlgs`. + +### Integrity (hashing) + +- `_meta.security.integrity`: `{ alg, hash, canonicalization? }` +- Hash the canonical payload (or plaintext when using encryption) and verify on receipt. + +### Encryption (JWE-like) + +- `_meta.security.encryption`: `{ alg, keyId?, iv?, aad?, ciphertext, tag? }` +- When present, `params` MAY omit plaintext fields; receiver decrypts to recover them. + +#### Example + +```json +{ + "jsonrpc": "2.0", + "id": 12, + "method": "resources/read", + "params": { + "_meta": { + "security": { + "replay": { "nonce": "v2t4...", "timestamp": "2025-08-09T12:02:00Z" }, + "encryption": { + "alg": "A256GCM", + "keyId": "kid:server", + "iv": "Q2hhbmdlbWU=", + "aad": "eyJqd3QiOnRydWV9", + "ciphertext": "X1c+...", + "tag": "bG9naW4=" + } + } + } + } +} +``` diff --git a/docs/docs/security/envelope.mdx b/docs/docs/security/envelope.mdx new file mode 100644 index 000000000..91e6a45bf --- /dev/null +++ b/docs/docs/security/envelope.mdx @@ -0,0 +1,45 @@ +--- +title: Security Envelope (`_meta.security`) +--- + +The security envelope attaches to requests, notifications, and results under `_meta.security`. + +### Fields + +- `identity`: `{ keyId, alg, jws, publicKey?, certificateChain? }` + - Cryptographic sender authentication per-message (JWS over a canonical payload) +- `capabilities`: `(string | CapabilityToken)[]` + - Fine-grained, short-lived, non-transferable authorization tokens +- `replay`: `{ nonce, timestamp }` + - Prevents replay attacks within a configured window +- `integrity`: `{ alg, hash, canonicalization? }` + - Tamper detection for the payload +- `encryption`: `{ alg, keyId?, iv?, aad?, ciphertext, tag? }` + - Optional message-level encryption (JWE-like container) +- `audit`: `{ traceId?, requestId? }` + - End-to-end tracing and incident response + +### Example + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "resources/read", + "params": { + "_meta": { + "security": { + "replay": { "nonce": "3XbV...", "timestamp": "2025-08-09T12:00:00Z" }, + "integrity": { "alg": "SHA-256", "hash": "base64-hash" }, + "capabilities": ["eyJhbGciOiJFZERTQSIs..."], + "identity": { + "keyId": "kid:client", + "alg": "EdDSA", + "jws": "" + } + } + }, + "uri": "file:///project/README.md" + } +} +``` diff --git a/docs/docs/security/errors.mdx b/docs/docs/security/errors.mdx new file mode 100644 index 000000000..200855454 --- /dev/null +++ b/docs/docs/security/errors.mdx @@ -0,0 +1,16 @@ +--- +title: Security Error Codes +--- + +The enhanced schema introduces clear, operational security errors (non-JSON-RPC standard codes): + +- 4900 UNAUTHORIZED — missing or invalid identity/capabilities +- 4901 FORBIDDEN — capability present but does not allow this action +- 4902 REPLAY_DETECTED — nonce/timestamp outside window or reused +- 4903 INVALID_SIGNATURE — signature or integrity failure +- 4904 INVALID_CAPABILITY — malformed token/claims +- 4905 EXPIRED_CAPABILITY — token expired or not yet valid +- 4906 ENCRYPTION_REQUIRED — policy requires encryption but absent +- 4907 DECRYPTION_FAILED — could not decrypt (e.g., wrong key) + +Use these for policy enforcement, telemetry, and alerting. diff --git a/docs/docs/security/index.mdx b/docs/docs/security/index.mdx new file mode 100644 index 000000000..d1d56bc77 --- /dev/null +++ b/docs/docs/security/index.mdx @@ -0,0 +1,29 @@ +--- +title: MCP Enhanced Security Overview +--- + +This section documents the enhanced, security-focused MCP schema introduced in `schema/2025-08-09/schema.ts`. + +### What’s new + +- Message-scoped security envelope via `_meta.security` +- Capability-based authorization with fine-grained scopes +- Message-level cryptography (identity signatures, integrity hashes, optional encryption) +- Security feature negotiation during `initialize` +- Dedicated security error codes (4900–4907) +- Capability issuance RPC: `security/issue` + +### Start here + +- Read the high-level summary: `ENHANCED_SCHEMA.md` +- Deep dives: + - `Security Envelope` (how to attach identity, capabilities, replay, integrity, encryption) + - `Capabilities` (scope/constraints and the `security/issue` RPC) + - `Cryptography` (signatures, hashing, encryption container) + - `Errors` (security-aware error codes) + - `Rollout` (progressive hardening strategy) + +### Spec cross-references + +- TypeScript: `schema/2025-08-09/schema.ts` +- Docs pages: `specification/2025-08-09/*` diff --git a/docs/docs/security/rollout.mdx b/docs/docs/security/rollout.mdx new file mode 100644 index 000000000..d4d947005 --- /dev/null +++ b/docs/docs/security/rollout.mdx @@ -0,0 +1,22 @@ +--- +title: Progressive Security Rollout +--- + +A staged adoption strategy minimizes disruption while improving security. + +### Phases + +1. Negotiate: advertise `security` capabilities during `initialize`. +2. Verify: enforce `replay` and `integrity` (log failures), continue to allow requests. +3. Capabilities: require tokens for privileged methods; soft-fail on missing signatures. +4. Signatures: require identity on all requests/responses. +5. Encryption: require message-level encryption for sensitive methods/parameters. + +### Validation checklist + +- Replay: `timestamp` within `maxReplayWindowSeconds`, `nonce` unique per `keyId`. +- Integrity: recompute canonical payload hash; return 4903 on mismatch. +- Identity: verify `identity.jws` and `keyId`/PKI; apply revocation/rotation. +- Capabilities: validate scope/constraints; return 4901/4905/4904 as appropriate. +- Encryption: if required, enforce presence and decrypt; return 4906/4907 on violations. +- Audit: propagate and log `traceId`/`requestId`.