Extensibility

Implementations can add custom behavior without breaking peers that don’t know about it. They can attach custom data in _meta fields, define custom methods whose names start with _, and advertise custom capabilities during initialization.

The `_meta` field

Object types that define a _meta field can use it to attach custom information with type { [key: string]: unknown }. This includes many requests, responses, notifications, and nested types such as content blocks, tool calls, plan entries, and capability objects. Not every protocol type defines _meta. For example, the Error object does not.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": {
    "sessionId": "sess_abc123def456",
    "prompt": [
      {
        "type": "text",
        "text": "Hello, world!"
      }
    ],
    "_meta": {
      "traceparent": "00-80e1afed08e019fc1110464cfa66635c-7a085853722dc6d2-01",
      "com.example/debugMode": true
    }
  }
}

Clients may propagate fields to the agent for correlation purposes, such as requestId. The following root-level keys in _meta SHOULD be reserved for W3C trace context to guarantee interop with existing MCP implementations and OpenTelemetry tooling:

traceparent
tracestate
baggage

Implementations MUST NOT add any custom fields at the root of a type that’s part of the specification. All possible names are reserved for future protocol versions.

Extension methods

The protocol reserves any method name starting with an underscore (_) for custom extensions, so custom methods can’t conflict with methods added in future protocol versions. Extension methods follow standard JSON-RPC 2.0 semantics:

Requests - Include an id field and expect a response
Notifications - Omit the id field and are one-way

Custom requests

In addition to the requests specified by the protocol, implementations MAY expose and call custom JSON-RPC requests as long as their name starts with an underscore (_).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "_com.example/workspace/buffers",
  "params": {
    "language": "rust"
  }
}

Upon receiving a custom request, implementations MUST respond accordingly with the provided id:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "buffers": [
      { "id": 0, "path": "/home/user/project/src/main.rs" },
      { "id": 1, "path": "/home/user/project/src/editor.rs" }
    ]
  }
}

If the receiving end doesn’t recognize the custom method name, it should respond with the standard “Method not found” error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

To avoid such cases, extensions SHOULD advertise their custom capabilities so that callers can check their availability first and adapt their behavior or interface accordingly.

Custom notifications

Custom notifications are regular JSON-RPC notifications that start with an underscore (_). Like all notifications, they omit the id field:

{
  "jsonrpc": "2.0",
  "method": "_com.example/file_opened",
  "params": {
    "path": "/home/user/project/src/editor.rs"
  }
}

Unlike with custom requests, implementations SHOULD ignore unrecognized notifications.

Advertising custom capabilities

Implementations SHOULD use the _meta field in capability objects to advertise support for extensions and their methods. To avoid collisions with other extensions, follow MCP’s naming convention: prefix extension names with dot-separated labels in reverse-DNS order of a domain you control, followed by /. For example, use com.example/<name> for _meta keys, including capability entries, and _com.example/<name> for custom methods. For example:

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "loadSession": true,
      "_meta": {
        "com.example/workspace": true,
        "com.example/fileNotifications": true
      }
    }
  }
}

Implementations can then negotiate custom features during initialization without breaking standard Clients and Agents.

Get Started

Protocol

Libraries

The `_meta` field

Extension methods

Custom requests

Custom notifications

Advertising custom capabilities

​The _meta field

​Extension methods

​Custom requests

​Custom notifications

​Advertising custom capabilities

The `_meta` field

Extension methods

Custom requests

Custom notifications

Advertising custom capabilities