Read vs write operations
How x-write marks mutating broker endpoints and how connectors gate write access.
Read vs write operations
The broker distinguishes read operations (safe to call freely) from write operations (they
mutate upstream provider state). This mirrors the v1 MCP ?write=true gate and is encoded directly
in the OpenAPI spec.
The x-write extension
| Operation kind | OpenAPI marker | Example |
|---|---|---|
| Read (list, get, search) | omitted | GET /rest/v1/github/repos/{owner}/{repo}/pulls |
| Write (create, update, delete, or generic passthrough) | "x-write": true | POST /rest/v1/linear/graphql |
Write operations carry the vendor extension at the top level of the operation object:
post:
operationId: linear_graphql
x-write: true
summary: Execute a Linear GraphQL query or mutationGenerated connectors (SDK, MCP server, CLI) read this flag to decide whether a caller may invoke the operation without an explicit write opt-in.
Why it matters
- Automation safety: read-only agents and scripts can be restricted to non-mutating endpoints.
- Auditability: the spec is the single source of truth for which routes change external state.
- Docs: API reference pages are generated from the same spec. When
x-writeis present, the operation is a write endpoint regardless of HTTP method.
Connector contract (summary)
The generated SDK, MCP server, and CLI all consume the same operation metadata. Each connector can
use x-write to distinguish mutating operations and enforce the access policy appropriate to that
surface. See each package README for its implemented behavior.
See Connectors for package links.
Adding new routes
When contributing a service, mark every mutating route with 'x-write': true in
createRoute({...}). Reads must omit the field, and each service's OpenAPI document tests should
assert the expected write markers.