API reference

Nothing supported: no images, no audio, no embedded context.

No MCP transport supported.

No session method beyond session/new.

No authentication step offered.

An agent that supports only session/new and session/prompt.

No file access granted.

No terminal authentication offered by the client.

No supplementary session features.

No elicitation kind supported.

A client that reads and writes nothing, runs nothing, and answers no ask.

A name and a version, which is all the protocol asks for.

The name the category travels as.

The category with that name; unknown names are kept as they came.

Wires a client to a transport. The caller runs the returned connection, which is what delivers updates and answers the agent's calls.

Takes messages in until the other side goes away. Updates reach the client from here, so it has to run in a task of its own while the other tasks call the agent.

A call the protocol does not name: send it raw and read the answer raw.

A notice the protocol does not name.

Negotiates the version and trades capabilities. Call it once, before anything else.

Runs one of the agent's authentication methods.

Drops whatever authenticate established.

Starts a session and returns what the agent says about it: identifier, modes, options.

Reopens a session; the updates that replay its history arrive on run.

Reattaches to a live session without replaying anything.

The sessions the agent remembers, one page at a time.

Forgets a session.

Ends a running session, as if session/cancel had been sent.

Switches the session's mode.

Sets one configuration option and returns the whole list, as the protocol requires.

Sends one turn and waits for its answer. Updates arrive through the client's update while this waits, because the connection is being run in another task.

Asks the agent to stop the turn running in a session. A notice: nothing comes back, and the turn answers Cancelled on its own.

The client this connection feeds.

The name the role travels as.

The role with that name, or None.

A reference to a terminal, as a tool call embeds it.

The name the format travels as.

The format with that name, or None.

The text is not JSON.

The value is not a valid message.

Nobody handles that method.

The parameters are not what the method takes.

The handler failed for its own reasons.

The caller asked for the work to stop.

The client has to authenticate before this method works.

A path, a session or a resource named in the request does not exist.

An error object with a code of your choosing.

The code this failure travels as.

What the other side reads.

Anything else attached to the failure.

The wire form of a failure.

Turns anything a handler raised into the error object to send: the wire code is kept, and anything that is not a Refused becomes -32603 with no detail, because what a handler trips over is not the caller's to read.

The reverse, for a call that came back with an error object.

The protocol version this library speaks. It only changes when the protocol breaks.

A first answer for an agent that supports nothing beyond session/new: the version, no capabilities, no authentication.

The name the reason travels as.

The reason with that name, or None.

Serves an agent over any transport: the caller runs the returned peer. Messages are answered in the order they arrive, and batches are refused, because the protocol has none.

The session's identifier, the one the client sent with session/new.

Sends one update. Updates are notifications, so they are never answered and never fail the turn by themselves; the connection going away raises Closed.

Asks the user to allow a tool call. The client answers with the option it picked, or Cancelled when the prompt was dismissed; a client that never answers blocks the turn, so keep the ask in the turn's own task.

Reads a text file through the client, sliced from line when one is given.

Writes a text file through the client.

Runs a command in a terminal the client owns. The returned handle reads, waits for, kills and releases it.

Asks the user for a few fields or for a visit to a URL. The ask is scoped to this session, and to the tool call it came from when one is given.

The identifier the client gave this terminal.

Everything the command has printed so far.

Waits for the command to exit and reports how it did.

Stops the command without giving the terminal back.

Gives the terminal back. The client may reuse it for the next command.

The terminal as a tool call refers to it, for ToolCallContent.

The name the priority travels as.

The priority with that name, or None.

The name the status travels as.

The status with that name, or None.

The name the severity travels as.

The severity with that name; unknown names are kept as they came.

The name the state travels as.

The state with that name; unknown names are kept as they came.

The name the kind travels as.

The kind with that name, or None.

The name the status travels as.

The status with that name, or None.

The name the option kind travels as.

The option kind with that name, or None.

What a handler raises, and what the other side's error object becomes when a call fails. A variant's code is the JSON-RPC code it travels as: Refused(code~, ..) carries the wire code itself, Unsupported is -32601, Malformed is -32602.

Content kinds the agent accepts inside a prompt.

MCP transports the agent can connect to.

Session methods beyond session/new. Each flag is a promise to answer that method.

Authentication the agent offers.

Everything the agent says it can do, sent back from initialize.

Files the client lets the agent read and write on its behalf.

Whether the client runs terminal commands for the agent.

The client's support for supplementary session features.

Elicitation kinds the client can show.

Everything the client says it can do, sent with initialize.

A name and version, for the log and the about box.

An authentication method the agent offers, one of two shapes tagged by type on the wire; the agent-driven one carries no tag.

The client runs a command to authenticate.

The agent runs the flow itself once authenticate is called.

A text file to read.

What a read returns.

A text file to write, whole.

A command to run in a new terminal.

The identifier of the terminal the client opened.

Names an existing terminal, for terminal/output, terminal/wait_for_exit, terminal/kill and terminal/release.

How a command ended.

What a terminal has printed so far, and whether it has exited.

One mode the agent can work in.

The modes on offer and the one in force.

What a configuration option is about, so a client can place it. Unknown categories are kept.

One value of a dropdown.

Choices under a heading.

The choices of a dropdown, flat or grouped. The two are told apart by whether the first entry carries group.

What a configuration option holds: a picked value or a switch.

One entry of the session configuration picker.

What session/new and its siblings answer with.

The whole option list after one of them changed.

A connection to an agent, from the editor's side. run takes messages in; the methods here send them out and wait for their answers.

Who a piece of content is for.

Hints for how a client shows a piece of content.

Text the model reads or writes.

An image, base64 in data.

Audio, base64 in data.

A resource the client can read, named by URI rather than by value.

Resource contents carried as text.

Resource contents carried as base64 in blob.

Either kind of embedded resource contents, told apart by text against blob.

A resource carried by value inside a message.

One displayable piece of a prompt or of a tool's output, tagged by type on the wire.

A standard content block wrapped for a tool call's output.

A file edit, given as the whole file before and after.

A reference to a terminal the client opened, embedded in a tool call.

What a tool call produced, tagged by type on the wire.

A place in the workspace a tool touched.

A string field's format hint.

One titled choice of a string field.

A field the user types into.

A field for a fractional number.

A field for a whole number.

A field for yes or no.

What a multi-select offers: bare values or titled ones.

A field for picking several of a set.

One field of a form, tagged by type on the wire. A kind the protocol does not define yet is kept as it came so a client can still show it.

The form to render.

Which request an elicitation belongs to: a session's turn, or a bare JSON-RPC request.

A form for the user to fill in.

A link the user follows.

An ask, tagged by mode on the wire.

What the user did with the ask. content holds one value per field, of whatever type the field asked for, so it stays raw.

One header sent to an MCP server.

One environment variable for a spawned MCP server.

An MCP server reached over HTTP.

An MCP server reached over the older HTTP plus SSE transport.

An MCP server the client is to launch as a child process.

An MCP server a session may use. The wire tells the two HTTP shapes apart by type; the stdio shape carries no tag at all.

Opens the conversation: versions and capabilities, once per connection.

The answer to initialize.

Names one of the methods from initialize.

Starts a conversation. The working directory is where the agent reads and writes.

Reopens a session and replays its history as updates.

Reattaches to a session without replaying its history.

Asks for the sessions the agent remembers.

One row of session/list.

The page of sessions, and the cursor for the next one.

Removes a session from what session/list returns.

Ends a session that is still running.

Picks a mode.

Sets a configuration option. The wire has two shapes, a value id or a boolean, told apart by type.

Sets one configuration option.

One turn of the conversation.

Why the agent stopped.

The answer to a prompt: why the turn ended.

Stops whatever turn is running in a session. A notification, so it is never answered.

One session, as the agent sees it inside prompt. Everything here is a call to the client: updates, permission, files, terminals, elicitation.

A command running in a terminal the client owns. Holding one is not owning a process: release hands the terminal back, and the exit status is only known after wait.

One streamed item of content.

How urgent a plan entry is.

How far a plan entry got.

One step of the agent's plan.

The whole plan, replacing whatever came before.

The text typed after a command's name, offered to the user as a hint.

A slash command the user may type.

The command list, replacing whatever came before.

The session's mode changed.

The session's metadata changed; only the fields that changed are present.

What the turn cost, in whatever currency the agent bills in.

How much of the context window the conversation fills.

How loud a notice is. Unknown severities are kept as they came.

Something to tell the user that is not part of the conversation.

Where a context compaction got to. Unknown states are kept as they came.

A compaction, created the first time its identifier is seen and updated after that.

One more block of a compaction's retained summary.

Everything the agent may tell the client mid-turn, tagged by sessionUpdate on the wire.

One update as it travels: the session it belongs to and the update itself.

What kind of thing a tool does, for a client that wants to pick an icon.

How far a tool call got.

A tool call the model has asked for.

A later change to a tool call: only what changed is present.

What choosing an option means, so a client can group the buttons.

One button in a permission prompt.

The ask the agent makes: run this tool call, and here is what the user may choose.

What came back: one option chosen, or the ask dismissed.

The agent side. Implement what the agent can do and leave the rest: initialize and new_session and prompt are the three every agent has, the others have defaults that report themselves as unsupported.

The client side. update is the only method the protocol requires; the rest exist so the agent can ask for them, and a client that leaves one out answers -32601 when the agent asks.

Runs an agent on the process's own stdin and stdout until the client closes stdin. This is the transport an editor uses when it launches an agent: one JSON-RPC message per line, nothing else on stdout, diagnostics on stderr.

Starts command with args and connects to it as a client. The command is an absolute path or something the system can find on PATH; the first array element is the program.

The connection to the child, runnable and callable.

Closes the child's input, which is how an agent learns the client is done: it finishes what it is doing and exits. The read side ends with it, so a task blocked on run comes back.

A child process speaking the protocol on its pipes.

Serves an agent over ASGI: one path, four verbs, and a WebSocket upgrade. Nothing is global, so several agents can be mounted side by side.

The defaults: 1 MiB bodies, 256 buffered messages per stream, a keepalive every 15 seconds, and half a minute for initialize.

The transport's bounds.