Guide · Updated 2026-10-23

Machine Mode and MCP

MCP makes a tool reachable. Machine Mode makes it operable.

MCP, the Model Context Protocol, is how an AI agent discovers and calls tools that a server exposes. Machine Mode defines what a command‑line tool returns once it's called. They sit at different layers, so a tool can have both: a Machine Mode interface on the command line and an MCP server in front of it for hosts that don't run a shell.

The Machine Mode contract stays the same whoever calls the tool: an MCP server, a code‑mode script, a shell pipeline or a queue worker.

Two layers, one call

What each one is responsible for.

MCP covers reaching a tool: listing what a server offers (tools/list), describing each tool's input with a JSON Schema, invoking it (tools/call) and carrying the result back. Since the 2025‑06‑18 revision a tool may also declare an outputSchema and return structuredContent that conforms to it.

Machine Mode covers what happens inside the call when the tool is a CLI: typed JSONL events on stdout, a schema the tool describes offline, errors from a closed list with an authoritative retryable flag, bounded reads with cursors, and a terminal aoi:summary that states whether the run worked. An MCP adapter can pass all of that through without inventing anything.

Putting a Machine Mode CLI behind MCP

A thin adapter: spawn the command, collect the stream, translate the result.

Machine Mode to MCP field mapping
Machine Mode	MCP	Notes
`capabilities` commands	`tools/list` entries	One MCP tool per command, named after it.
Input schema from schema	`inputSchema`	Flags and operands become JSON Schema properties.
Event schemas from schema	`outputSchema`	Describe the collected result: an `events` array and the `summary`.
Domain events and aoi:summary	`structuredContent`	Also put the serialized JSON in a text block, which the MCP spec recommends for clients that ignore structured content.
`aoi:error` (process scope) or `ok:false`	`isError: true`	Keep the full error event, including `category` and `retryable`, in the structured result.
`aoi:progress`	`notifications/progress`	Only when the client sent a progress token.
`truncated` and `next_cursor`	A cursor argument on the tool	The agent calls again with the cursor to fetch the next page.
`read_only`, `destructive`, `supports_idempotency_key`	`readOnlyHint`, `destructiveHint`, `idempotentHint`	MCP treats annotations as hints, and clients should not trust them from untrusted servers.

A search call through such an adapter returns something like this:

tools/call resultjson

{
  "content": [{ "type": "text", "text": "{\"events\":[…],\"summary\":{…}}" }],
  "structuredContent": {
    "events": [
      { "type": "hit", "rank": 1, "id": "doc_123", "title": "Agent-Operable Tools" }
    ],
    "summary": { "ok": true, "event_count": 3, "truncated": false }
  },
  "isError": false
}

Credentials

Machine mode never prompts.

A Machine Mode tool inherits credentials from its environment: a keychain, a config file, environment variables. If a call would need an interactive login, it emits an aoi:error with category authn and code INTERACTIVE_REQUIRED, plus a hint naming the human‑mode command to run. An MCP adapter should surface that error to the user rather than retry it, and any authorization the MCP server adds sits on top of the tool's own.

Which way should an agent call the tool?

Whichever the host supports.

The agent has a shell or a code‑mode runtime: call the CLI directly and read its JSONL. That skips the adapter and keeps the full stream, including progress and per‑item errors. See Machine Mode and code mode.
The host only speaks MCP: put the adapter in front. The agent gets the same result, collected into one response.
Both: ship both. The adapter is a few dozen lines, and the CLI stays the single source of behavior.

Sources

Model Context Protocol specification, revision 2025‑06‑18, “Tools” (modelcontextprotocol.io).
AOI‑CLI v1.0‑alpha, §1.3 Interactive flows, §9 Error taxonomy, §15 Bounds, §17 Capability manifest.