Skip to main content
The Agent Client Protocol provides built-in extension mechanisms that allow implementations to add custom functionality while maintaining compatibility with the core protocol. These mechanisms ensure that Agents and Clients can innovate without breaking interoperability.

​
The _meta Field

All types in the protocol include a _meta field with type { [key: string]: unknown } that implementations can use to attach custom information. This includes requests, responses, notifications, and even nested types like content blocks, tool calls, plan entries, and capability objects. 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": {
    "sessionId": "sess_abc123def456",
    "prompt": [
      {
        "type": "text",
        "text": "Hello, world!"
      }
    ],
    "_meta": {
      "traceparent": "00-80e1afed08e019fc1110464cfa66635c-7a085853722dc6d2-01",
      "zed.dev/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. This allows implementations to add new functionality without the risk of conflicting with future protocol versions. Extension methods follow standard JSON-RPC 2.0 semantics:

​
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": "_zed.dev/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": "_zed.dev/file_opened",
  "params": {
    "path": "/home/user/project/src/editor.rs"
  }
}
Unlike with custom requests, implementations SHOULD ignore unrecognized notifications.

​
Enum and Tagged-Union Variants

ACP v2 also reserves _-prefixed values for implementation-specific extensions in enum-like fields and tagged unions that define a custom or future fallback.
  • Values beginning with _ are reserved for implementation-specific extensions.
  • Unknown values that do not begin with _ are reserved for future ACP variants.
  • Extensions MUST NOT define custom non-underscore values.
  • Implementations MUST NOT treat unknown non-underscore values as custom extensions.
This rule applies only where the v2 schema defines a fallback path. Closed discriminators can still reject unknown values when the receiver cannot safely continue without understanding the variant. When storing, replaying, proxying, or forwarding data, implementations SHOULD preserve unknown values and any raw tagged-union payloads. When displaying an unknown value, implementations SHOULD fall back to generic UI behavior that matches the field’s purpose.

​
Advertising Custom Capabilities

Implementations SHOULD use the _meta field in capability objects to advertise support for extensions and their methods: 
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 2,
    "capabilities": {
      "session": {
        "load": {}
      },
      "_meta": {
        "zed.dev": {
          "workspace": true,
          "fileNotifications": true
        }
      }
    }
  }
}
This allows implementations to negotiate custom features during initialization without breaking compatibility with standard Clients and Agents.