---
title: "MCP reference"
description: "The MCP tools Auto Runtime serves to agents for playbooks, functions, workflows and runs, how each maps to the HTTP API, and how an MCP client signs in."
url: "https://on.auto/docs/reference/mcp"
last_updated: "2026-11-18T11:05:13+00:00"
---

# MCP reference

Auto Runtime serves its playbook, function and workflow operations to agents over the Model Context Protocol (MCP). Each MCP tool runs one operation of the [HTTP API](https://on.auto/docs/reference/http), with the same fields, limits and refusals. This page maps each tool to its HTTP section, which is the home of those rules. It also covers what only MCP has: the endpoints, authentication from an MCP client, annotations, guides and prompts, model information, and the shape of results and errors.

To connect Claude Code, Claude Desktop or Codex, follow the [quick start](https://on.auto/docs/get-started/cloud#connect-your-agent). For a worked example, follow [Build your first playbook](https://on.auto/docs/tutorials/first-playbook).

## An inbound interface

MCP here is an inbound interface: an external agent connects to Auto Runtime and calls its operations. It does not configure tools inside a reasoning function.

A reasoning function can call tools itself, through tool servers the runtime's operator configures or through [connections](https://on.auto/docs/reference/mcp#connections) people add to their organization. That outbound connection is set up in Auto, never by adding an endpoint to an external agent. The operator lists each server and the tools it allows in [`tool_servers`](https://on.auto/docs/self-host/configuration#tool-servers), and a function names those tools in its [`tools`](https://on.auto/docs/reference/reasoning-format#tools). [Tool access inside a reasoning function](https://on.auto/docs/concepts/functions#tool-access-inside-a-reasoning-function) explains the difference.

## Endpoints

For hosted Auto, use `https://mcp.on.auto`. It serves the caller's organization and its playbooks, and handles sign-in through MCP authentication. The paths below describe a [self-hosted runtime](https://on.auto/docs/self-host). The tools a deployment exposes depend on its capabilities and your permissions.

| Path | Acts on | Tools |
| --- | --- | --- |
| `/mcp` | The caller's own org and, through a `playbook` argument, its playbooks | Every tool. A tool that works inside a playbook takes a required `playbook` argument; `search`, `list_comments` and `resolve_comment` take it as an optional one |
| `/orgs/{org}/mcp` | One org's playbooks | Playbook management, `list_models`, `list_generation_models`, `search`, `list_comments` and `resolve_comment` with `playbook` optional, the connection tools, `activate_license` and `get_guide` |
| `/orgs/{org}/playbooks/{playbook}/mcp` | One playbook | The tools that work inside a playbook, with no `playbook` argument, and `search`, `list_generation_models` and `get_guide` |
| `/directory` | The caller's own org, as `/mcp` does | The tools of `/mcp`, less what the directory listing leaves out, listed below |

*   Every endpoint uses streamable HTTP without sessions and accepts `POST`.
*   `/directory` is the directory listing. It leaves out two things.
    *   No generation function: the definition tools take no `generation` type, `get_guide` holds no generation guide, `list_playbook_events` names none of its events, and neither `get_asset`, which reads what one made, nor `list_generation_models`, which lists the models one may name, is listed. A call that names a generation function is refused as `not_found`.
    *   No tool server whose tools pay, refund, transfer or pay out money, which its provider's entry or its configuration marks `handles_money: true`, such as Stripe. `search` lists neither the server nor its provider, and `add_connection`, `list_connection_tools`, `query_connection` and `execute_connection` refuse it as `unavailable`, saying the directory listing does not offer it. Through `/mcp` the same calls work.
*   The answer to a request the runtime handles comes as an event stream that carries a heartbeat, an SSE comment, every 5 seconds while the request runs, so an MCP client can tell a call that is still running from a server that has stopped. A request refused before it is handled keeps its JSON answer and its status, and a notification is answered `202 Accepted`. A stream that breaks is not resumed: closing it cancels the request.
*   When the runtime stops while it handles a request, it answers the request with the JSON-RPC error `Auto Runtime stopped while it handled this request, so it may or may not have taken effect` before the stream ends, and a request that comes while it stops gets a `503`.
*   The runtime supports protocol revision `2026-07-28` and the compatible revisions `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05` and `2024-10-07`. An MCP client handles the negotiation.
*   On `/mcp`, the org is the caller's own: an API key's org, or the org a signed-in person's token names. In local mode it is the org `local`. No tool takes an org argument.
*   A connection lists only the tools its key or token may call. A read-only key sees the tools that read, and none that creates or runs a function. A key that may only read inside some playbooks is offered `list_playbooks`, which lists those playbooks.
*   Which tools a connection lists depends on both the endpoint and the caller's permissions. A missing `create_definition` can mean either. The connection may be to the org endpoint, or its key or token may lack `playbook:write`.
*   The org and playbook a scoped endpoint names stay subject to the caller's access. Choosing a more specific endpoint grants no extra permission.
*   Some operations are served only over [HTTP](https://on.auto/docs/reference/http), and no endpoint offers them as a tool:
    *   The six routes of Studio's page that connects a [connection](https://on.auto/docs/reference/mcp#connections), `read_link`, `approve`, `give_credential`, `give_client`, `start` and `finish`; `list_providers`, which a page reads to show what a person may connect; `set_connection_playbooks`, which sets which playbooks may use a connection; and `set_connection_signing_secret` and `remove_connection_signing_secret`, which a person uses in Studio to give a connection's service the secret it signs what it sends with, which no agent holds.
    *   Six reads an agent does with another tool or leaves to Studio: `get_connection`, since each connection `list_connections` returns holds the same fields, its `status` among them; `get_run_history`, since `list_playbook_events` with a `run_id` returns the run's events and those of every run it started; `get_playbook_analytics` and `render_playbook_page`, which Studio presents; `render_page`, since `get_definition` with `render` previews the same page, and given a run's `run_id` it renders that run's page as it stood when the run ended, which Studio's Ledger shows for the chosen run; and `validate`, since `dry_run` reports the same check of the arguments in its `arguments` field.
    *   Comments and voice: `make_comment`, a playbook's and the organization's, since an agent does not comment on its own work; `reopen_comment`, since a person reopens a comment; and `transcribe` and `get_voice`, by which Studio writes out what a person says into a comment.
    *   Licensing, changes and activity: `get_license`, which Studio presents; `list_org_changes` and `list_playbook_changes`, by which a client such as Studio learns what changed in the org or a playbook; `activate_allocation` and `report_allocation`, which serve a runtime on [offline credits](https://on.auto/docs/self-host/licensing#offline-credits); and `list_activity` and `mark_activity_seen`, which read [the organization's activity](https://on.auto/docs/reference/http#the-organization-s-activity) and mark it seen.
    *   Roles: `list_role_assignments`, `assign_role` and `unassign_role`, by which a person signed in to Studio sees and changes who holds which [role](https://on.auto/docs/reference/http#roles), and `get_caller`, by which Studio learns which permissions the person signed in may use; nothing an agent is told gives anyone a role.

### What a connecting agent is told

An agent that connects receives short instructions written for its caller and the tools its key or token may call. They say:

*   first, before building or changing anything, to read the guide `start` with `get_guide`, which says which function type each part of a job takes, and that a playbook is built from the job: each part is a function of the type its work needs, and a workflow runs the parts in order. Both sentences end within the first 512 characters, whatever the caller is called;
*   then, that a playbook holds work that keeps running after a conversation, in any line of business, that Auto Runtime makes and runs playbooks, Studio manages them and the agent is a separate client, and that a playbook contains one brain, its reusable functions, and workflows, with its runs;
*   what the connection acts on: the caller's own org on `/mcp`, with `list_playbooks` and `create_playbook` where the caller may call them; one org's playbooks on `/orgs/{org}/mcp`, whose definitions are made on each playbook's own endpoint; or one playbook on `/orgs/{org}/playbooks/{playbook}/mcp`;
*   whom the connection acts as, by name and id, and in which org: `This connection acts as Ada Lovelace (person:user_2ada) in the org acme.` for a signed-in person, the local developer by the name of the account the server runs as and the id `local`, and `This connection acts as the key build-bot in the org acme.` for a key. So an agent that reads who created, added, connected, started or answered something tells the person it acts for from the others;
*   that a tool that cannot do what was asked says why and what to change.

The guide `start`, which every endpoint serves, holds what the instructions leave out. It names only the types, the recipes and the pages the runtime serves, and says:

*   first, that a playbook is built from what the person wants it to achieve: once they agree on it, the agent designs with them the workflow that achieves it, before any function, and names in the design the function type of each step that does work, with a line for each function type the runtime runs by what a step does; that a step that reads or searches a service is a lookup function, whether the run's input or an earlier step says what to read, run once for each item in a `for`, and that a reasoning function judges or writes from what was read and names tools only where what it looks for next depends on what it just read, a step with no tools choosing what to look for, what to open or which hits to read and lookups reading those; that the order, the branches, the waits and what happens when a step fails are the workflow's; where the runtime runs no workflow, that a playbook is built from the job, a function for each part; and that where a reasoning function has come to hold a read, a calculation, a question or an act, that part takes a function of its own type;
*   that a workflow owns one job the business does again and again, with a result the person recognizes as done, so a function to test, a question to a person or a check of a service is not one;
*   that testing, setting a service up and checking it are the agent's own work, done with `query_connection`, `execute_connection`, `dry_run` and `run_definition` and never saved as a workflow, and that the agent connects what that work takes;
*   which connection lists which of those tools;
*   how a service is connected with `search` and `add_connection`;
*   how a person is asked, through an interaction function, and answered with `answer_interaction`;
*   that every workflow and function takes a page, where the runtime keeps pages;
*   which guide or recipe each task needs.

The instructions stay short so that a client that shows little of a server's instructions shows them whole; no bound is enforced on them.

What the instructions and the guide leave out, the tools' descriptions say. The description of `get_guide` names the recipes the connection's tools can follow. That of `create_definition` says that a workflow, designed before its functions, owns one job the business does again and again, that a check, a test or a setup is not one, and that each step that does work calls a function of the type that work needs, and its `type` says that the workflow is the job and, by the job of a step that does work, which function type takes it, for each type the runtime serves; that of `create_playbook` that each job a playbook does again and again is a workflow, and each part of a job a function of the type that part needs. That of `run_definition` says that a workflow does a job the person wants done again while a function runs alone to be tested, and that a run that finishes later returns `started` and `get_run` shows how it ended. Those of `list_models` and `search` say how a reasoning function names its model and its tools, as the reasoning function's guide does. Those of `query_connection`, `execute_connection` and `dry_run` say what each does. Those of `list_runs`, `list_playbook_events` and `list_interactions` say that their pages come one at a time, each read on from the `next_cursor` of the page before. Those of `list_comments` and `resolve_comment` say what each does with what people said in Studio, as [Comments](https://on.auto/docs/reference/mcp#comments) sets out.

### Everything an agent receives, on one page

`GET /debug` answers a page a person reads in a browser, with everything this server gives an agent over MCP, for a caller with every permission. A switch picks the connection: `/mcp`, `/orgs/{org}/mcp`, `/orgs/{org}/playbooks/{playbook}/mcp` or `/directory`. For each it shows the instructions, verbatim but for the sentence that names the caller, which the page cannot know; every tool the connection lists, with its title, its description, its hints and its arguments; every guide `get_guide` reads, rendered, with its raw Markdown beside it; and the prompts, with what a client receives when one is picked. A search, opened with `⌘K`, `Ctrl+K` or `/`, finds a tool, a guide or a prompt by its name or by any words it holds. The page needs no key and loads nothing from any server. It is built when the server starts, from the code the endpoints serve, so it changes only with a restart.

## Authentication

Hosted Auto signs you in when your agent connects; account creation is part of the same flow.

An MCP client sends the same credentials as any HTTP caller, and has the same permissions; see [Requests and access](https://on.auto/docs/reference/http#requests-and-access). A client connects in one of three ways:

*   Signed in. Hosted Auto uses this flow by default. For a self-hosted runtime, the operator enables sign-in with `PUBLIC_URL`. Your agent discovers the identity service and opens the browser for you to sign in.
*   With no credential, when a self-hosted server runs in [local mode](https://on.auto/docs/self-host/security#local-mode). It listens only on a loopback address and trusts requests from that computer. Never expose local mode through a tunnel or public proxy.
*   With an [API key](https://on.auto/docs/self-host/security#api-keys), sent as `Authorization: Bearer <key>`. Keep it in the connection configuration, outside prompts and function documents.

[Authentication and security](https://on.auto/docs/self-host/security) says how an operator sets each of these up. The [Sign-in and token reference](https://on.auto/docs/reference/authentication) gives the rules the server applies.

### Signing in from an MCP client

With sign-in on, each endpoint is an OAuth 2.1 protected resource, as the MCP authorization specification describes. A client that supports that flow signs the person in by itself. So does an agent gateway that obtains tokens on the person's behalf:

1.  It connects without a token and gets `401`, with a challenge that points to the endpoint's protected resource metadata.
2.  It signs the person in at the identity service the metadata names, and asks for a token for that endpoint.
3.  It connects again with `Authorization: Bearer <token>`.

The connection then acts as the person in the org their token names, which is also the org `/mcp` acts in. It lists only the tools the token's granted scopes allow. [Discovery and challenges](https://on.auto/docs/reference/authentication#discovery-and-challenges) gives the metadata and every challenge. [How scopes grant permissions](https://on.auto/docs/reference/authentication#how-scopes-grant-permissions) says what each scope allows.

## Tools

Each tool runs one HTTP operation, and its section in the [HTTP reference](https://on.auto/docs/reference/http) gives its fields, limits and refusals.

*   A tool takes as arguments what its route takes in the path, the query string or the body, by the same names. Examples are a definition's `type` and `name`, a `run_id`, an `event_id`, or a `server` and a `tool`.
*   On `/mcp`, a tool that works inside a playbook also takes the playbook's id as `playbook`.
*   A definition's `type` is `reasoning`, `lookup`, `interaction`, `prediction`, `computation`, `generation` or `workflow`. [Availability](https://on.auto/docs/concepts/functions#availability) says which of them a runtime runs. On `/directory`, the definition tools take no `generation`, as [Endpoints](https://on.auto/docs/reference/mcp#endpoint-scope) sets out.

### How a tool describes itself

Every tool supplies a description and the JSON Schema of its input. No tool has an output schema. [Successful results](https://on.auto/docs/reference/mcp#successful-results) says what a result contains, and the [OpenAPI document](https://on.auto/docs/reference/http#the-openapi-document-the-guides-and-the-api-catalog) gives each operation's output schema.

*   A description says what the tool does and when to use it.
*   The rules of each argument are in the input schema.
*   The format of a definition is in its guide, which `get_guide` returns.

Each tool's annotations tell a client how careful to be:

| Annotation | Means | `true` for |
| --- | --- | --- |
| `readOnlyHint` | The tool only reads | Every tool that reads, including `dry_run`, although its HTTP route uses `POST`, and `query_connection`, which calls only a tool marked `reads` |
| `destructiveHint` | It may change or delete data | Every tool that does not only read, `execute_connection` among them |
| `idempotentHint` | Calling it again with the same input changes nothing | Every tool that reads except `query_connection`, and `update_playbook`, `retire_playbook`, `remove_connection`, `activate_license`, `update_definition`, `pause_definition`, `resume_definition`, `retire_definition`, `cancel_run`, `answer_interaction` and `resolve_comment` |
| `openWorldHint` | It reaches outside the runtime | `list_models`, `run_definition`, `create_definition` and `update_definition`, which reach model providers or ask the tool servers what they offer; `search`, `introspect`, `dry_run`, `list_connection_tools`, `query_connection` and `execute_connection`, which reach tool servers; `activate_license`, which reaches Auto's account service |

A client that honours the hints asks the person before it calls a tool marked destructive.

### Playbooks and models

These tools are listed on `/mcp` and the org endpoint, and `list_generation_models` on a playbook endpoint too. Their routes are relative to `/v1/orgs/{org}`.

| Tool | HTTP operation | What it is for |
| --- | --- | --- |
| `create_playbook` | `POST /playbooks` | Create a playbook, active and empty |
| `list_playbooks` | `GET /playbooks` | List the playbooks the caller may access |
| `get_playbook` | `GET /playbooks/{playbook}` | Read a playbook, with the source of its page |
| `update_playbook` | `PUT /playbooks/{playbook}` | Change a playbook's name, description or page |
| `retire_playbook` | `POST /playbooks/{playbook}/retire` | Retire a playbook, which keeps its id and stays readable |
| `restore_playbook` | `POST /playbooks/{playbook}/restore` | Bring a retired playbook back, active again |
| `list_models` | `GET /models` | List the models a reasoning function may name; see [Model information](https://on.auto/docs/reference/mcp#model-information) |
| `list_generation_models` | `GET /generation-models` | List the models a generation function may name; see [Generation models](https://on.auto/docs/reference/mcp#generation-models) |

Each playbook `list_playbooks` returns holds every field of the playbook but its page, a retired one among them with `include_retired`; `get_playbook` adds the page's `source`, as `update_playbook` answers it. [Playbooks](https://on.auto/docs/reference/http#playbooks) and [Models](https://on.auto/docs/reference/http#models) give the fields, limits and refusals.

### The welcome of a new organization

`list_playbooks` of an organization with no playbook yet, active or retired, answers a caller who may make its first playbook, one who may act on every playbook of the org and holds `org:write`, a `welcome` beside the empty `playbooks`, which the agent relays to the person; over MCP the result's text is that welcome, whole, in place of the summary. It reads:

> This organization has no playbooks yet. A playbook keeps work your team can use again. Its workflows coordinate functions that reason, look up, interact, predict, compute and generate. Unless the person has already said what they want, ask what they want done, and offer three starts: set up a first playbook, connect a service they use, or hear what Auto can do for their team. Before you build, read the guide start with get\_guide: it says which function type each part of a job takes. In Studio, your team can review playbooks and run results. You can also manage workflows, connections, members and billing there.

It ends with the link to Studio's home, as [Links to Studio](https://on.auto/docs/reference/http#links-to-studio) sets out. A caller who may only read, or who acts on some playbooks alone, is answered the empty list and no `welcome`, so it learns nothing more of the organization; and an organization that has a playbook answers no `welcome` to anyone.

### Definitions

These tools are listed on `/mcp` and a playbook endpoint. Their routes are relative to `/v1/orgs/{org}/playbooks/{playbook}`, where `{type}` is the tool's `type` argument.

| Tool | HTTP operation | What it is for |
| --- | --- | --- |
| `create_definition` | `POST /definitions/{type}` | Save a new function or workflow from its document, given as `source`, its `overview` and a function's `diagram` |
| `list_definitions` | `GET /definitions/{type}` | List the definitions of one type, without their `overview`, `diagram` and `used_by` |
| `get_definition` | `GET /definitions/{type}/{name}` | Read a definition, with its document, its `overview`, its `diagram`, `used_by`, and its page's `runs` and `standing`, or preview its page with `render` |
| `update_definition` | `PUT /definitions/{type}/{name}` | Save a new version from a changed document, overview or diagram |
| `pause_definition` | `POST /definitions/{type}/{name}/pause` | Pause a definition, so that nothing starts a run of it until it is resumed, with an optional `reason` |
| `resume_definition` | `POST /definitions/{type}/{name}/resume` | Resume a paused definition, whose triggers start runs again from the first time or event after it |
| `retire_definition` | `POST /definitions/{type}/{name}/retire` | Retire a definition, keeping its name and history |
| `restore_definition` | `POST /definitions/{type}/{name}/restore` | Restore a retired definition, paused until it is resumed |

`create_definition` and `update_definition` take an `overview` beside `source`, and a function's saves take a `diagram` every time: a save without one is refused, and so is a workflow's with one, since Auto Studio draws a workflow from its steps. `get_definition`, `create_definition`, `update_definition`, `pause_definition`, `resume_definition`, `retire_definition` and `restore_definition` return both as written, with `used_by`, the definitions of the playbook, active or paused, that use this one. [Reasoning functions](https://on.auto/docs/reference/http#reasoning-functions) gives the rules of the overview, the diagram and each relation of `used_by`, and the section of each type adds its own. A definition's [page](https://on.auto/docs/reference/page-format), which presents its results, is the `page` key of its document, written with the document and saved with it. Give every workflow and function one: a save without it is accepted, and its summary ends with `It has no page yet; the page guide says how to give it one.` where the summary has room for it, since a summary stops at 400 characters. `get_definition` with `render: true` renders it now, over an optional `sample_output`, as [The preview](https://on.auto/docs/reference/page-format#the-preview) sets out.

#### Renaming a definition

A definition's name is its id. To rename one, create it with `create_definition` under the new name and with the same document, and point every call and filter that names the old name at the new. Retire the old one at once with `retire_definition`, since until then a trigger the two share starts both. A renamed definition's runs so far stay under its old name.

### Runs

These tools are listed on `/mcp` and a playbook endpoint. Their routes are relative to `/v1/orgs/{org}/playbooks/{playbook}`.

| Tool | HTTP operation | What it is for |
| --- | --- | --- |
| `run_definition` | `POST /definitions/{type}/{name}/run` | Run a function or workflow once, with its `input` and an optional `run_id` |
| `get_run` | `GET /runs/{run_id}` | Read a run, with its detailed `record`, its page's `result` and, for a run a step started, `within` |
| `list_runs` | `GET /runs` | List the playbook's runs, newest first; `steps: false` leaves out those a step started |
| `cancel_run` | `POST /runs/{run_id}/cancel` | Cancel a run that is still going |
| `send_run_event` | `POST /runs/{run_id}/events` | Deliver an event to a workflow run that is still `started` |
| `get_asset` | `GET /assets/{id}` | Read an asset of a generation function or a tool's image, with an address to its bytes |

`create_playbook` answers the playbook's page in Studio as `studio`, `create_definition` and `update_definition` the definition's, and `run_definition` its playbook's Ledger with the run chosen, so the agent gives the person the link without being asked; [Links to Studio](https://on.auto/docs/reference/http#links-to-studio) says what each link opens.

[Runs and results](https://on.auto/docs/reference/http#runs-and-results) covers input limits and which runs finish later, and [Retrying under a run id](https://on.auto/docs/reference/http#retrying-under-a-run-id) what a request under an earlier run's id returns. [Cancelling a run](https://on.auto/docs/reference/http#cancelling-a-run), [Sending an event to a run](https://on.auto/docs/reference/http#sending-an-event-to-a-run) and [Run history and playbook events](https://on.auto/docs/reference/http#run-history-and-playbook-events) give the rest.

### Requests

These tools are listed on `/mcp` and a playbook endpoint. Their routes are relative to `/v1/orgs/{org}/playbooks/{playbook}`.

| Tool | HTTP operation | What it is for |
| --- | --- | --- |
| `list_interactions` | `GET /interactions` | List the open requests of interaction functions, newest first |
| `answer_interaction` | `POST /runs/{run_id}/answer` | Answer a request in the shape its `answer_schema` gives; the run that asked takes it within about a second |

[Interaction functions](https://on.auto/docs/reference/http#interaction-functions) lists every field of a request and of an answer, and each refusal. [Answering a request](https://on.auto/docs/reference/interaction-format#answering-a-request) explains how a run takes its answer.

`create_definition` and `update_definition` refuse an interaction function in two cases:

*   a request that names no `deliver`, in words that name each connection or tool server of the playbook whose tools can send a request and read its replies, with those two tools, and `deliver: agent`;
*   a notification that names no tool, or that names `agent`, in words that name each connection or tool server whose tools can send it.

A client of the `2026-07-28` revision may declare in its request that it answers forms, the `form` mode of elicitation, or declare `elicitation: {}` with no mode, which the SDK reads as forms. To such a client, the server first asks the person one question, such as `Where should the owner be asked?`, with a titled choice for each such connection or tool server, by its name, and, for a request, one for the agent way. The client retries the call with the answer:

*   Once the person chose, the call is refused in words that name the chosen server's sending tool and, for a request, its tool that reads the replies, or that say to write `deliver: agent`. From them the agent learns what each tool takes with `introspect`, calls the sending tool with `execute_connection` once the person agrees, and writes the document.
*   Where the person declined or cancelled, the call is refused with every choice.

A client that declares links alone or no elicitation, or speaks an earlier revision, is not asked, and the agent asks the person in words, from the refusal's list.

### Events and history

These tools are listed on `/mcp` and a playbook endpoint. Their routes are relative to `/v1/orgs/{org}/playbooks/{playbook}`.

| Tool | HTTP operation | What it is for |
| --- | --- | --- |
| `publish_event` | `POST /events` | Record an event in the playbook, such as a month closed in a ledger |
| `list_playbook_events` | `GET /events` | Read everything that happened in the playbook, newest first, or with `run_id` one run's whole tree |
| `get_event` | `GET /events/{event_id}` | Read one event with every field in full, such as a tool's whole result |

Over MCP, a result carries its output twice, as JSON text and as structured content. So `get_event` shows a large field in full only up to 64 KiB as JSON, and shows its size beyond that. The large fields are an input, an output, a record, an answer, a call's `arguments` and `result`, and a published event's data. Over HTTP, every field is whole.

`list_playbook_events` with a run's `run_id` returns what the run and every run it started recorded: its steps, its tool calls and how it ended. [Publishing events](https://on.auto/docs/reference/http#publishing-events) and [Run history and playbook events](https://on.auto/docs/reference/http#run-history-and-playbook-events) give the fields, filters, paging and limits. The playbook's [analytics](https://on.auto/docs/reference/http#analytics) are Studio's to present, over HTTP alone.

### Comments

People comment on anything Studio shows, where they see it: a step's prompt, a run's result, a run that never ended, a figure on a page, the Ledger, a connection that stopped working, a member, a page of Settings. Each comment carries the [address](https://on.auto/docs/reference/addresses) of what it is about, and stays open until it is resolved, and a person can reopen a resolved one. A comment on a thing of a playbook is the playbook's, and one on a thing of the organization is the organization's own. These tools let an agent read what people said and close what it acted on. They are listed on every endpoint, to every caller who may read the playbook.

*   On `/mcp` and the org endpoint, both keep their names and take `playbook` as an optional argument. With it, they act on that playbook's comments, routes relative to `/v1/orgs/{org}/playbooks/{playbook}`. Without it, they act on the organization's own comments, routes relative to `/v1/orgs/{org}` ([The organization's comments](https://on.auto/docs/reference/http#the-organization-s-comments)).
*   On a playbook endpoint, they act on the playbook's comments and take no `playbook`.

| Tool | HTTP operation | What it is for |
| --- | --- | --- |
| `list_comments` | `GET /comments` | Read the open comments of a playbook or of the organization, newest first, or those on one address or under it |
| `resolve_comment` | `POST /comments/{id}/resolve` | Close a comment, `acted` once what it asked is done or `dismissed` when the person says to drop it |

The descriptions of the two tools carry part of what an agent does with them: when to call `list_comments`, that a comment's `address` says which tool reads and changes the thing, and when to resolve a comment as `acted` or `dismissed`, with the `playbook` it was read with. On a playbook endpoint, the description of `list_comments` also says what its open comments are and that a comment on an earlier version is read against the current document. The rest of this list is not in them:

*   When the person says they left comments in Studio, or pastes the line Studio copies, call `list_comments`. For one playbook, read its comments. Told to act on the open comments in Auto, read the organization's own, with no `playbook`, and each playbook's, with each `playbook` that `list_playbooks` lists. Their open comments are what people said and nobody has acted on yet.
*   Act on each comment where its address says: read the thing with the tool [From an address to a call](https://on.auto/docs/reference/addresses#from-an-address-to-a-call) names, such as `get_definition` for a step, `get_run` for a run or `list_connections` for a connection, and change it as the comment asks, such as with `update_definition` or `reconnect_connection`. A comment on a part of a thing is about that piece of the thing. A comment on an earlier version is read against the current document. What no tool changes, such as a member's role or the organization's billing, report to the person.
*   Once a comment is acted on, resolve it with `resolve_comment`, `how` `acted`, with the `playbook` it was read with, or none for the organization's own. Dismiss one only when the person says to. Tell the person what was changed for each comment, and which were left open and why.
*   A retired playbook's comments can be read but not resolved, and nothing in it can be changed: report them to the person instead.
*   Never comment yourself. `make_comment` is not a tool: a comment is what a person says, and an agent reports its work to the person instead.

`list_comments` takes `address`, `under`, `open`, `limit` and `cursor`, and `resolve_comment` takes `id` and `how`, each with the rules [Comments](https://on.auto/docs/reference/http#comments) gives, with the fields of a comment, its `anchor` among them: where Studio draws the comment's pin, which the address already places for an agent. Each comment carries `studio`, its place in Studio, which the agent gives the person when it says what it did.

A person reopens a resolved comment in Studio, with `reopen_comment`, which is served over HTTP alone, so no tool reopens a comment ([Reopening a comment](https://on.auto/docs/reference/http#reopening-a-comment)). An agent sees a reopened comment open again in `list_comments`, with `reopened_at` and `reopened_by` saying when and by whom, and acts on it and resolves it as any open comment.

### Tool servers

Five tools work with the tool servers of the playbook, those set up in the configuration and the [connections](https://on.auto/docs/reference/mcp#connections) of its org, whether MCP servers or HTTP APIs, under the names an agent gateway gives the same tools over the systems behind it, so an agent uses one vocabulary with either. A sixth operation, `validate`, is served over [HTTP](https://on.auto/docs/reference/http#tool-servers) alone: `dry_run` reports the same check of the arguments. The routes are relative to `/v1/orgs/{org}`.

| Tool | HTTP operation | What it is for |
| --- | --- | --- |
| `search` | `GET /tool-servers/search`, or on a playbook endpoint `GET /playbooks/{playbook}/tool-servers/search` | Find the servers and the tools a reasoning function may name in `tools` |
| `introspect` | `GET /playbooks/{playbook}/tool-servers/{server}/tools/{tool}` | Read one tool in full: its description, its arguments' schema, its hints and its mark |
| `dry_run` | `POST /playbooks/{playbook}/tool-servers/{server}/tools/{tool}/dry-run` | See what `execute_connection` would check, without calling the tool |
| `query_connection` | `POST /playbooks/{playbook}/tool-servers/{server}/tools/{tool}/query` | Call one tool marked `reads` by hand, live, as the playbook, to see what it returns |
| `execute_connection` | `POST /playbooks/{playbook}/tool-servers/{server}/tools/{tool}/execute` | Call one tool by hand, live, as the playbook, whatever its mark, to see what it returns or to act |

*   `search` is listed on every endpoint, and the other four on `/mcp` and a playbook endpoint.
*   On `/mcp` and the org endpoint, `search` takes an optional `playbook`. Without it, `search` covers the whole org, so an agent can see what is set up before a playbook exists. On a playbook endpoint, `search` takes no `playbook`.
*   `introspect` and `dry_run` change nothing and call no tool, but they ask the servers for their tool lists. So their hints say read-only and open-world, and a key that may read the playbook is offered them.
*   Each tool carries its mark: `reads` when it only reads, `acts` when it may change something, and `unmarked` when nothing marks it, which counts as `acts`. `search` and `dry_run` answer it as `mark`, and `introspect` beside the hints its server gives, `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint` as it gives them, with `marked_by`: `server` for the hints its server lists it with, or the lack of them, `method` for the HTTP method of an operation of an HTTP API, `catalogue` for the entry of its provider, and `settings` for its entry in the [configuration](https://on.auto/docs/self-host/configuration#the-mark-of-a-tool). `search` with `only: read` keeps the tools marked `reads`, and with `only: write` the others.
*   `query_connection` and `execute_connection` need `playbook:write` whatever the tool does, so a key that may only read is offered neither. Each call is recorded in the playbook's history.
*   `query_connection` calls only a tool marked `reads`, and refuses any other as `unavailable` of the kind `tool_not_read_only`, so it is marked read-only. `execute_connection` calls a tool whatever its mark, so it is marked destructive. Many of the tools they call belong to third parties: a connection's MCP server, a provider's API, or an HTTP API an operator set up. The runtime cannot always tell whether such a tool only reads or changes something. `search` with `only: read`, `introspect` and `dry_run` show a tool's mark without calling it.
*   A call that names a server or a tool the playbook may not use is refused, and the refusal's words say what `search` shows.
*   A connection is listed with `connection`, its id, and named by its name. One that is not ready is refused, and listed unavailable, with `because` `connection_pending` while nobody has approved it, `connection_broken` once its server answered `401`, or a code its provider's `failure_codes` names for a refused credential, its credential is gone from the secret store or is not the tokens of a consent, its consent was revoked or has ended, its client is no longer registered, or the provider it was made from is replaced here, in words that say what mends it, most often `reconnect_connection`, `connection_not_allowed` when a rule of the operator no longer takes it, or `connection_unavailable` while its credential cannot be read just now, which a later call may find put right.
*   Each server carries `provider`: the name of the provider a connection was added from or an entry of the configuration names, or `null` for a server given by hand.
*   On `/mcp` and the org endpoint, to a caller who may add a connection, `search` also lists in `providers` the [providers](https://on.auto/docs/reference/http#providers) a person may connect that no server serves yet, found by `terms` as tools are, each with its `name`, `title` and `description` and, where its way offers groups of scopes beyond its first consent, `more`, each group by the name `add_connection` takes as `more` and what it is for. A provider none of whose ways is offered, as while a value whoever runs Auto sets for it is not set, is left out. An agent asked to connect a service, or for one no server serves, finds its provider there by the service's words and connects it with `add_connection`. A key, a caller who may only read and a runtime where nobody may add get no `providers`, and neither does `search` with `server`.
*   When no server serves the playbook, the words of `search` say that whoever runs the server sets one up. Where people may add connections, they also say that a person adds one, or, where `search` lists a provider, that a person connects a provider it lists.

[Tool servers](https://on.auto/docs/reference/http#tool-servers) gives the fields, limits and refusals of all six.

### Connections

A connection is a tool server that a person adds to the org through their agent, a provider by its name or a server given by hand, which every playbook of the org may use, or the playbooks its entry names. These tools are listed on `/mcp` and the org endpoint. Their routes are relative to `/v1/orgs/{org}`.

| Tool | HTTP operation | What it is for |
| --- | --- | --- |
| `add_connection` | `POST /connections` | Add a provider or a tool server to the org, pending, and answer the link that approves it |
| `list_connections` | `GET /connections` | List the org's connections, newest first, whether each is pending or connected, and what each may still be granted |
| `list_connection_tools` | `GET /connections/{id}/tools` | List the tools one connection's server offers now, by name, each with its title, its whole description, its hints and its mark |
| `reconnect_connection` | `POST /connections/{id}/link` | Give a connection that is broken, or whose link ran out, a new link on which the person gives its credential or signs in again, or a link that asks more |
| `remove_connection` | `DELETE /connections/{id}` | Remove a connection for good, which forgets its credential |

*   A connection is added by a person: where the runtime signs people in, `add_connection` refuses a key, and a runtime of API keys alone, which signs nobody in, refuses every connection, since no person could approve it.
*   The agent adds a connection without its credential: an entry that holds a value that looks like a credential, or a reference to an environment variable, written `${NAME}`, is refused. The person approves the connection, and gives its credential where it takes one, on Studio's page, which `connect.url` of the answer opens within 24 hours.
*   `add_connection` puts the link in its answer to the call that adds the connection. To a client of the `2026-07-28` revision that declares in its request that it opens links, the `url` form of elicitation, it also asks for the link to be opened, with a message that says what to do. The client opens the page or declines, and retries the call. The retry never adds a second connection, and answers the connection as it stands then:
    *   once the person approved it, `connected`, with no `connect`, in words that say nothing is left to open;
    *   while the link lasts, as when the person continued without approving it, `pending` with its link, in words that also say the person declined to open the page where the client declined or cancelled;
    *   once the link has expired, `pending` with no `connect`, in words that say to reconnect it for a new link;
    *   where a newer link that is still open replaced the one offered, the connection with `link_replaced`, and no `connect`, in words that say the person opens the newest and that reconnecting it would replace that one too;
    *   where the person cancelled on the page, `removed`, in words that say nothing is connected.
*   A retry of `add_connection` by another caller, or in another org, is refused, and the connection stays added. A client of an earlier revision, whose requests carry no capabilities on this stateless server, is not asked; it shows the person the link from the answer, whose words say to show it as a link named `Approve the <title> connection` with its provider's title, or `Approve the connection` for a server given by hand, never as its address.
*   `add_connection` takes one of two inputs. For a provider: `provider`, its name; `placeholders`, the value of each placeholder it takes; and, where they are wanted, `name`, the provider's when left out, `credential` with its `kind` alone, since a provider offers one way of each kind, and when it is left out the first way `list_providers` marks offered, or the provider's first where it offers none, and `entry` with `playbooks`, `allowed` and `record_content` alone; and `more`, the name of a group of scopes the provider's way offers beyond its first consent, as `search` lists it under the provider, whose scopes the first consent asks too. The provider gives the rest, and `type`, the server in `entry` and the other fields of `credential` are refused. For a server given by hand: `name`, the name a function gives the server; `type`, `mcp` for a remote MCP server or `openapi` for an HTTP API; `entry`, the server without its credential; and `credential`, which the agent leaves out for an MCP server, since the server says how it authenticates, and gives for an HTTP API, or for an MCP server whose answer says it names no way of its own; with no `placeholders`. An HTTP API's `entry` names its OpenAPI document by its address, `document`, where the service's own documentation states one, or holds the document itself, `document_text`, which the agent writes from that documentation for the calls the job needs, of at most 16,384 bytes, with `base_url`, the one address its calls go to. The runtime reads the document as the connection is added and refuses, before the person is asked for anything, one it cannot read or that offers no tool, at its place in the document; a connection given its document whole answers `document`, its SHA-256, its size and the number of tools it offers, never its text.
*   With `provider`, `credential` may also be `{ kind: authorization, oauth_client: own }`, where the person connects under the organization's own OAuth client, a client the organization registers with the provider, which bills and limits it, rather than the client Auto or whoever runs it has there: the person gives its client ID and client secret on the page before signing in, and the runtime keeps the secret sealed and starts the consent with that client. A way whose `oauth_client` is `required` in `list_providers`, as the way says or since no client here covers it, takes the organization's own OAuth client with `oauth_client` left out. `oauth_client` beside another kind, or without `provider`, is refused at `/credential/oauth_client`. [A connection under the organization's own OAuth client](https://on.auto/docs/self-host/connections#a-connection-under-the-organization-s-own-oauth-client) sets it out.
*   A provider the runtime does not have is refused at `/provider`, in words that say `search` lists the providers a person may connect, a placeholder or a value refused at `/placeholders/<name>`, and what the checks of an entry find in what the provider resolved at `/provider`.
*   The credential is one object: its `kind` and the fields that kind takes. A field its kind lacks or does not take is refused as `invalid_input` at that field.
    *   `reference` takes `variable`, `name` and `in`, and `secret` takes `name` and `in`. Where `in` is `header`, each also takes an optional `scheme`, such as `Bearer`, which the runtime writes before the value.
    *   A `secret` given by hand also takes `instructions` and `key_page`, both required, for Studio's page to show the person beside the field of the key. `instructions` is Markdown without HTML, at most 1,000 characters, that says where the key is made, with a link to that page, the plan or role it needs, the permissions it needs and its format, such as `Make a key under [Settings, API keys](https://app.example/keys) as an Admin, with read access. It is 40 characters.`; `key_page` is the `https` address of that page. It may also take `example`, what a key looks like with `…` in place of its characters, and `pattern`, the regular expression from `^` to `$` a key matches, from the service's documentation, of characters and character classes, each repeated, with no group, alternative, lookaround or back reference. A key the person gives that misses the pattern is kept, and the page is told, since the pattern may be wrong as well as the key. Each is refused at its field where it is missing or not of its shape. With `provider`, the provider's way gives the four, and the agent gives none.
    *   `client_credentials` takes `issuer`, an optional `client_id` and an optional `scope`. A `client_id` left out is given by the person on Studio's page, with the secret or the key.
    *   `authorization` names a way by which the person signs in at an authorization server and allows Auto. It is taken with `provider`, as the kind of its way, and, for an MCP server given by hand, from the server itself. An HTTP API given by hand is refused `authorization`.
*   As an MCP server given by hand is added, and before anything is recorded, the runtime asks it once how it authenticates, with one request that carries no token, and reads the protected resource metadata it names:
    *   Where that metadata names an authorization server the runtime takes, the connection records `authorization` with that server as its issuer, whether the agent left the credential out or gave `authorization` with its `kind` alone. A `none`, `secret` or `reference` is refused at `/credential/kind`, in words that name the authorization server and say to leave the credential out. A `client_credentials` credential stands as given.
    *   Where the server names none, `authorization` is refused at `/credential/kind`, in words that say the server offers no consent, and any other kind the agent gave stands. A credential left out is refused at `/credential`, in words that say the server names no way of its own and ask how its credential is sent.
    *   A server that does not answer, or whose host the operator's rules refuse, is refused whatever the kind.
*   Once connected, a connection is a tool server of the org: a function names it by its name as `name/tool`, `list_connection_tools` lists its tools, and `search`, `introspect`, `dry_run`, `query_connection` and `execute_connection` reach it, as [Tool servers](https://on.auto/docs/reference/mcp#tool-servers) describes.
*   A link is gone after its 24 hours. `reconnect_connection` gives the connection a new one, as it gives one to a connection that is broken or to a connected one whose credential the person replaces, so the person gives its credential or signs in again on Studio's page; nothing else of the connection changes, but where it adds the connection again, as below. The new link replaces the one before, open or not, and the token of the one before is answered in words that say a newer link replaced it. It answers as `add_connection` does, asking a client that opens links to open it, and refuses a removed connection, which is added again instead. A broken connection of a `reference` takes no link: the runtime finds its variable set and connects it again at once, or refuses it while the variable is not set, since it reads its variables when it starts. Where people sign in, the person who added the connection reconnects it. Where the runtime lets a person of the organization reconnect a connection of the provider whoever added it, that person may reconnect it instead, for a connection made from a provider another replaces and for one another person added that is still `pending`: either is removed and added again under its name, for the same playbooks, as theirs to finish, and a caller the runtime starts no connection of the provider for is refused in words that say who can.
*   `list_connections` answers each connection with `more`, the groups of scopes its provider's way names that it does not hold yet and a client set up here can ask, each `{ name, for }`, `for` what the group is for in the person's words, as `Share your files with other people.` for `share` in the example of [A consent that asks more](https://on.auto/docs/self-host/connections#a-consent-that-asks-more). `reconnect_connection` given `more`, a group's name, gives a connection that is pending, connected or broken a link whose consent asks the scopes the connection asked that it was granted with the group's, so the person allows more and keeps what they allowed before; a connected connection stays connected as it is until the person finishes. A group the way does not name is refused as `invalid_input` at `/more`, and one the connection holds already or no client set up here covers as `conflict`. A plain link asks the scopes the credential asks with those the connection asked since and was granted, so a group allowed once is kept.
*   `list_connection_tools` asks the connection's server for its tools when it is called and answers those its entry allows, sorted by name, a page at a time with `limit` and `cursor`: each tool's `name`, its `title` where the server gives one, its `description` whole up to 4 KiB, `hints`, the server's `destructiveHint`, `idempotentHint` and `openWorldHint` as it gives them, left out where it gives none of them, and its `mark` and `marked_by`, as [Tool servers](https://on.auto/docs/reference/mcp#tool-servers) sets out, the mark taking the place of the read-only hint. A connection that is not connected, or whose server cannot be reached, is refused as `unavailable` with the `kind`, the `because` and the words `search` gives it, and an id the org has no connection of, or one removed, as `not_found`.
*   Each connection answers `asked_scopes`, which grow by a group's scopes as a consent that asks more starts, and `granted_scopes`, each scope with `says`, the sentence of its provider's way or of the group that says what the connection can do through it, or `null` where the way says nothing of it, as for a server given by hand, and `broken`, `{ kind, detail, at }` while it is broken: the kind of the break, the runtime's words and when it broke.
*   `add_connection`, `reconnect_connection` and `remove_connection` need `org:write`, and `list_connections` and `list_connection_tools` need `org:read`. `get_connection`, which reads one connection by its id, and `set_connection_playbooks`, which sets which playbooks may use one and needs `org:write`, are served over HTTP alone; `list_connections` shows whether the person approved a connection, in the `status` of each.

[Connections](https://on.auto/docs/reference/http#connections) gives the fields, limits and refusals, and [Let people add connections](https://on.auto/docs/self-host/connections) the flow and the rules the operator sets.

### License

`activate_license` activates the license of the whole runtime with the key Studio gives, `alk.<org>.<runtime id>.<secret>`, the HTTP operation `POST /license`. It is listed on `/mcp` and the org endpoint to a caller who may change the org, and answers where the runtime stands, as `GET /license` does, saying it in words. A key Auto does not know, or one for another runtime, is refused as `license_invalid`. [License](https://on.auto/docs/reference/http#license) gives the rest, and [Activate the key](https://on.auto/docs/self-host/licenses#activate-the-key) the other ways to give a runtime its key.

## Guides and prompts

`get_guide` returns one of the runtime's guides in full, by its name. Every endpoint serves the same guides, except `/directory`: it holds no `generation-function` guide, and its `terminology` guide leaves generation functions out. Each endpoint also lists its guides as Markdown resources, `guide://<name>`, for clients that let a person or a model read them directly. Over HTTP, [`GET /v1/guides/{guide}`](https://on.auto/docs/reference/http#the-openapi-document-the-guides-and-the-api-catalog) serves the same text as `/mcp`.

| Guide | Contains |
| --- | --- |
| `start` | Where an agent begins: what a playbook is made of, what a workflow owns, what the agent does itself, and which guide each task needs |
| `terminology` | What the words of a playbook mean, for the types of function the runtime runs |
| `reasoning-function`, `lookup-function`, `interaction-function`, `prediction-function`, `computation-function`, `generation-function` and `workflow` | The reference page of each format, as the documentation publishes it. `reasoning-function` ends with what this runtime offers |
| `templates` | The filters every template may use, from [Templates](https://on.auto/docs/reference/template) |
| `triggers` | How a workflow starts on its own: the triggers of its schedule, on an event, at set times or every so often, and their limits, from [Triggers](https://on.auto/docs/reference/triggers). A runtime that runs no workflows serves no `triggers` guide |
| `events` | The playbook's events that a workflow's trigger, a page and a prediction function take, and how a filter names them, from [Events](https://on.auto/docs/reference/events). A runtime that runs no workflows or prediction functions and keeps no pages serves no `events` guide |
| `page` | The [page format](https://on.auto/docs/reference/page-format), with what the page of each type shows. A runtime that keeps no pages serves no `page` guide |
| `glance` | What a workflow says about itself in a fixed shape, from the [glance format](https://on.auto/docs/reference/glance-format). A runtime that keeps no pages serves no `glance` guide |
| `first-playbook`, `connect-a-service`, `give-tools`, `schedule` and `keep` | Recipes for common tasks, listed below |

One prompt, listed first, is for a person who does not yet know what to ask: `get-started`, offered only where the connection lists every tool it asks for, `create_playbook`, `create_definition` and `run_definition`, so on `/mcp` and `/directory` alone. A playbook endpoint and the org endpoint do not offer it, and nor does a key that may only read. It answers one message from the person, with nothing embedded:

| Prompt | Title | Arguments | The message |
| --- | --- | --- | --- |
| `get-started` | Get started with Auto | None | Create a playbook in Auto with one function and run it on a made-up example. Ask me what the playbook is for and anything else you need first, then give me a link to the run in Studio. |

The recipes are also prompts, listed after it. A connection offers a recipe's prompt only when it lists every tool the recipe's steps call, and the description of `get_guide` names the same recipes. So a playbook endpoint offers no `first-playbook` and no `connect-a-service`, whose steps add the connection and set the service up by hand, the org endpoint offers none, and a key that may only read gets none.

| Prompt | Title | Arguments | What the recipe does |
| --- | --- | --- | --- |
| `first-playbook` | Create your first playbook | None | Creates a playbook from the job the person wants done again and again: a function of the right type for each part and the workflow that runs them, each with its page, saved and run once the person has agreed. A runtime that runs no function type offers no `first-playbook` |
| `connect-a-service` | Connect a service | `service`, required: the service to connect, such as Slack or Google Drive | Connects a service the team uses, asks for the access the playbook needs to run and to be set up there, in one approval where the provider's first consent or a group of its `more` covers both, sets the service up by hand once the person agrees, and says what it can do |
| `give-tools` | Give the playbook tools | Optional `server`, a tool server | Puts the tools of a connected service to work: a lookup function for a read, an interaction function for an act or a question, and a reasoning function's tools only where its model must explore, by the mark each tool declares. A runtime that runs none of those types offers no `give-tools` |
| `schedule` | Run a workflow on a schedule | The `workflow`, and `when` to run it | Starts a workflow on a schedule or on an event, and reads how its runs went |
| `keep` | Keep something for later | `what` to keep | Keeps what the person wants kept as the output of a run, and reads it back with a lookup of that definition's runs |

A recipe asked without an argument it requires, such as `connect-a-service` without `service`, is the JSON-RPC error `-32602`, which names the argument. A prompt returns the recipe with the person's words filled in, followed by the format guide it names, where it names one: `connect-a-service` writes no definition, and `first-playbook` and `give-tools` write a function of each type the job needs, so none of the three names one.

## Model information

`list_models` lists the model references the server offers, including configured aliases. An agent can then name a model that works instead of guessing. It requires `org:read`, and it only reads. It is served on `/mcp` and the org endpoint, and is not available on a playbook-scoped endpoint. Over HTTP it is [`GET /v1/orgs/{org}/models`](https://on.auto/docs/reference/http#models), which returns the same result.

Its optional `provider` input selects one provider prefix, such as `anthropic`, or a configured gateway name. The server then lists only what that provider serves, and asks no other provider.

The result has the shape of the OpenAI API's list of models, with fields of its own at the top:

```json
{
  "object": "list",
  "data": [
    {
      "id": "anthropic/claude-sonnet-4-5-20250929",
      "object": "model",
      "created": 1759104000,
      "owned_by": "anthropic",
      "name": "Claude Sonnet 4.5",
      "context_window": 200000,
      "max_tokens": 64000
    },
    {
      "id": "gateway/anthropic/claude-haiku-4-5",
      "object": "model",
      "created": 1760486400,
      "owned_by": "gateway",
      "name": "Claude Haiku 4.5",
      "context_window": 200000,
      "max_tokens": 64000
    },
    {
      "id": "house/fast",
      "object": "model",
      "created": 0,
      "owned_by": "gateway",
      "alias": true,
      "resolved_to": "gateway/anthropic/claude-haiku-4-5"
    },
    {
      "id": "openai/*",
      "object": "model",
      "created": 0,
      "owned_by": "gateway",
      "alias": true,
      "resolved_to": "gateway/openai/*",
      "pattern": true
    },
    { "id": "bedrock/*", "object": "model", "created": 0, "owned_by": "bedrock", "pattern": true }
  ],
  "catalog_status": "complete",
  "narrowed": false,
  "listed_at": "2026-10-01T09:30:00.000Z"
}
```

| Field | Meaning |
| --- | --- |
| `object` | `"list"` |
| `data` | The entries, sorted by `id`, each `id` once |
| `catalog_status` | `complete`, or `partial` when a provider could not be asked, so its models are missing or are its last list |
| `narrowed` | `true` when `allowed_models` or `ALLOWED_MODELS` is set, so the list holds only what the operator allows; `false` when nothing narrows it, and a definition may name any model of the configured providers |
| `listed_at` | When the oldest provider list in the result was read; the time of the response when no provider was queried |
| `provider_setup` | Only from a runtime started with npx, when no `provider` is given and it lists no model: how the person adds a model provider |

Each entry contains `id`, `object: "model"`, `created` and `owned_by`. The last six fields in this table appear only where they apply:

| Field | Meaning |
| --- | --- |
| `id` | The model as a definition names it, `<provider>/<model id>`, or an alias as its operator wrote it |
| `created` | When the provider released or added the model, in seconds since 1970, as the provider says; `0` when it does not say |
| `owned_by` | The provider prefix that serves the model; for an alias, the prefix of its target. Never the owner a provider reports |
| `name` | The provider's name for the model, only when the provider reports one |
| `context_window` | The most input tokens, only when the provider reports it |
| `max_tokens` | The most output tokens, only when the provider reports it |
| `alias` | `true` for every alias its operator named, whether or not `resolved_to` shows its target; no other entry has it |
| `resolved_to` | For an alias, the reference it is sent to; left out when that is a Bedrock ARN, which names an account and a region |
| `pattern` | `true` for an id that ends in `*`, which stands for any model id. It is a wildcard alias, or `<provider>/*` for a provider that lists nothing and has no declared models, such as Bedrock, Azure or Vertex |

How to read it:

*   Use a concrete `id` as the reasoning function's `model`.
*   A wildcard describes a supported prefix; it is not a model to run.
*   `catalog_status: "partial"` means a provider's list is missing or stale. It does not mean the server has no models. The caller sees only `partial`; the operator's log says why the list could not be read.
*   Model access rules also apply when a function runs. A model the operator does not allow is refused before the provider is called, as [Responses and errors](https://on.auto/docs/reference/http#responses-and-errors) says.

How long a list is kept:

*   The server reads a provider's list the first time it needs it, and keeps it for five minutes. Calls that arrive while the list is being read wait for that read.
*   When a list cannot be read again, the server returns the last list it read, marked `partial`. It waits a minute before it asks that provider again; the first call after that minute asks again.

What the list leaves out:

*   a model that an alias redirects, since a definition that names it reaches the alias instead. With `anthropic/*` sent to a gateway, the models Anthropic lists are left out, and `anthropic/*` is listed;
*   an alias whose target provider is not configured, since a definition cannot call it;
*   any model the operator's allow list does not allow;
*   an entry whose id is empty, longer than 256 characters, contains a space, a control character or a `*`, or is a Bedrock ARN;
*   a `name` longer than 100 characters or on more than one line, though its entry is kept;
*   every key, token, base URL, header, query parameter, account, project, region and Bedrock ARN, every price, description or other field a provider adds, and the owner a provider reports.

The plain-language summary of the result follows these rules:

*   It names at most 20 models and counts the rest. It names each by the name its provider gives, or else by the last part of its id.
*   A name two providers share gets its provider in brackets. A name one provider repeats is replaced by the last part of the id.
*   It says which providers accept any model id, such as `It can also call any openai model.`
*   When the list is narrowed, it then says `It lists only the models its operator allows.`
*   A `partial` result ends with `The list may be incomplete: a provider could not be asked just now.`

A server with six models, for example, says: `This server can call 6 models through anthropic and gateway: Claude Haiku 4.5 (anthropic), Claude Opus 4.1, Claude Sonnet 4.5, Qwen3-14B, Claude Haiku 4.5 (gateway), and fast.`

[Set up a model provider](https://on.auto/docs/self-host/models) explains how an operator sets up a provider. The [Model settings reference](https://on.auto/docs/reference/model-settings) covers aliases, declared models, the allow list and how each list is built.

This catalog lists language models, not MCP tools. `search` finds the tools of the tool servers a playbook's functions may use. A separately managed tool library is still planned.

## Generation models

`list_generation_models` lists the models a [generation function](https://on.auto/docs/reference/generation-format) may name, from the catalogue the server holds, so an agent or Studio shows the models of the runtime it talks to rather than those of another release. It only reads: it reads the catalogue the server read as it started, and asks no gateway, so it answers the same in every org and playbook of the server. It is served on `/mcp` and the org endpoint, where it requires `org:read`, and on a playbook endpoint, where it requires `playbook:read`, the permission to read that playbook; on none of them does it take a `playbook`. Over HTTP it is [`GET /v1/orgs/{org}/generation-models`](https://on.auto/docs/reference/http#models), or `GET /v1/orgs/{org}/playbooks/{playbook}/generation-models` under `playbook:read`, which return the same result.

Its optional `kind` input, `image`, `audio` or `video`, lists only the models that produce that kind.

```json
{
  "object": "list",
  "as_of": "2026-11-16",
  "gateways": ["gateway"],
  "data": [
    {
      "model": "openai/gpt-image-2",
      "kind": "image",
      "media_types": ["image/png", "image/jpeg", "image/webp"],
      "limits": {
        "sizes": ["auto", "1024x1024", "1536x1024", "1024x1536"],
        "qualities": ["auto", "low", "medium", "high"],
        "prompt_characters": 32000,
        "references": { "most": 16, "bytes": 52428800 }
      }
    }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `as_of` | The day the list was read, as `YYYY-MM-DD`, against which each `retired.on` is read |
| `gateways` | The names of the gateways of `MODEL_GATEWAYS`, one of which a generation function writes before its model, as `gateway/openai/gpt-image-2`. Empty where no gateway is configured, so no generation function can run |
| `data` | The models of the catalogue, sorted by `model`, each as [The models](https://on.auto/docs/reference/generation-format#the-models) gives it |
| `model` | The model as the gateway names it |
| `kind` | What it produces: `image`, `audio` or `video` |
| `media_types` | The media types of the assets it takes as references; empty where it takes none |
| `limits` | The values each [parameter](https://on.auto/docs/reference/generation-format#parameters) may take, the most characters of a prompt, and, where it takes references, how many and how large |
| `retired` | For a model that retires, `on`, the day it retires, as `YYYY-MM-DD`, and `replacement`, the model that replaces it. Until that day a function may name it, and a save that names it carries a notice. From that day a save that names it is refused, and so is every run of a function that still names it; the model stays listed so that refusal can be explained |

The plain-language summary names the models a function can name by what each makes, each by the last part of its id, with its provider where two share it. With the catalogue the runtime ships and one gateway, it names fourteen models until 2027-01-06, six that make an image, five that make audio and three that make a video, and eleven from that day, when the three OpenAI speech models retire. It then names each model that retires with the one that replaces it, as `<model> retires on <day>; name <replacement> before then.` while that day is still to come, and as `<model> was retired on <day>; <replacement> replaces it.` from that day, which it reads against the day it answers, `as_of`. Where no gateway is configured, it says first that no generation function can run until whoever runs the server configures one.

## Successful results

A successful tool result carries a plain-language summary, the operation's output as JSON text and the same output as structured content, led by the summary:

| Field | Contents |
| --- | --- |
| `content[0].text` | A plain-language summary of what was done, or the words the agent relays, whole |
| `content[1].text` | The operation's output as JSON text, for clients that do not read the next one |
| `structuredContent` | The same summary as `content[0].text` under `in_words`, then the output as structured content |

Read `structuredContent`. The first text block is not JSON. Some clients give their model only `structuredContent` on a success, and others give it every text block too, so `in_words` carries the summary to a model either way. When the summary is a field the output already holds, such as `list_playbooks`'s `welcome`, there is no `in_words`. An HTTP API answer has no `in_words`. No tool advertises an output schema, so a client should use `structuredContent` as it comes rather than validate it against a schema.

*   A run's result is the run: its run id, definition version and status, its output when it succeeded, and, for a run a workflow's step started, `within`, which names the workflow run and the step. `get_run` adds the detailed record and, where the run's definition has a page, `page.result`, the run as that page shows it.
*   A run that finishes later, such as a workflow's, is `started` when `run_definition` returns; [Runs and results](https://on.auto/docs/reference/http#runs-and-results) says which runs do and how to read them again.
*   The summary repeats a short result in words, and points to `structuredContent` for a long one. It takes at most 400 characters.
*   An action the runtime accepted may answer `notices`, at most three things to double-check. Each has a `kind`, a `detail` of at most 400 characters that says what was noticed and what to check, a `certainty` and, where it has one, `at`, a JSON pointer to where it is in the document. `certainty` is `exact` when the fact was checked, `likely` when it usually means a mistake, and `reminder` when it could not be checked. The action is done either way.
*   When an answer has `notices`, they come first in its output, followed by `before_going_on`, one sentence that counts them and says what to do: if you are sure of what you did, carry on and tell the person in one sentence why you kept them; if not, fix them now. Over MCP they follow `in_words`. The summary leaves that sentence to `before_going_on`, so a model that reads both reads it once. A save of a reasoning function whose tools are all marked reads answers one when its tool servers list their tools within two seconds, and a run of one that you ask for answers one when it succeeds. On a server that runs workflows, the first function or workflow saved in a playbook answers a `reminder`: that the person should have seen the workflow's steps, each with its function type, and said yes to that design. No later save in that playbook answers it. A read answers no `notices`; `get_run` shows a run's notices only in its `record`.
*   Where the output holds words for the agent to relay, as the [welcome](https://on.auto/docs/reference/mcp#the-welcome-of-a-new-organization) of `list_playbooks` does, the first text block is those words, whole up to 1,000 characters.
*   A review that recommends Revise still belongs to a succeeded run: the operation completed and produced that recommendation.

These summaries were recorded from a two-step review-and-approval workflow on a self-hosted runtime. Its approval step uses the [example interaction function](https://on.auto/docs/reference/interaction-format#a-function-document). Only the review's words come from a scripted model:

```text
create_definition: Created the interaction function “approve-campaign-brief”. What it does: Asks the campaign owner, in the team chat, to approve a reviewed brief. It has been saved but has not been run yet.
create_definition: Created the workflow “review-and-approve”. What it does: Reviews a campaign brief, then asks its owner to approve it. It has been saved but has not been run yet. It has no page yet; the page guide says how to give it one.
run_definition: The workflow “review-and-approve” has started and is still running. It carries on by itself, and how it ends can be looked up later.
get_run: The workflow “review-and-approve” is still running; how it ends can be looked up again later.
list_interactions: Found 1 request waiting on this page.
answer_interaction: The request is answered: the run that asked it takes the answer within the host's sweep, a second by default, and get_run shows how it ended.
get_run: The run of the workflow “review-and-approve” finished. Its result: review: “Revise: the audience lacks a job role.” and approval: (verdict: “approve” and note: “Approved for the autumn launch.”)
list_playbook_events: Found 19 events of the run asked for in this playbook, oldest first, each with its fact and its metadata.
get_run: The run of the interaction function “approve-campaign-brief” finished. Its answer: verdict: “approve” and note: “Approved for the autumn launch.”
list_interactions: No request is waiting.
```

Each event carries a summary too. Given the workflow run's `run_id`, `list_playbook_events` answers its events and those of the two runs it started. The summaries of the workflow run's own nine events read, oldest first:

```text
run_started: A run of the workflow “review-and-approve” started.
workflow_input_applied: The workflow started, and 1 step moved.
step_waiting: The step “review brief” waits for a function it called.
workflow_input_applied: A function the workflow called answered, and 2 steps moved.
step_finished: The step “review brief” finished.
step_waiting: The step “ask for approval” waits for a function it called.
workflow_input_applied: A function the workflow called answered, and 1 step moved; the workflow ended.
step_finished: The step “ask for approval” finished.
run_succeeded: A run finished.
```

## Errors

An operation failure is a tool result with `isError: true` and no `structuredContent`:

*   The first text block explains the failure in words.
*   The second contains the JSON problem document. Its `reason` and `detail` distinguish invalid input, permission failures, conflicts and unavailable dependencies.
*   Invalid arguments are `invalid_input`, with a pointer at each field, so an agent can correct them. An input that the input schema of the function or workflow it runs refused has the kind `input_schema`.
*   A run the runtime's meter refuses, as `license_required`, `license_invalid`, `credits_exhausted` or `account_closed`, has the problem's `resolve_at`, the page where a person resolves it, which the first block points the agent to, and `runtime_id`, the runtime's id, as [The refusals of the meter](https://on.auto/docs/reference/http#the-refusals-of-the-meter) sets out.

Some failures come before a tool runs, outside any tool result:

*   Authentication and origin checks can reject a request with an HTTP problem document.
*   Protocol failures return JSON-RPC errors. A call to a tool the connection does not list returns `-32602`.

[Responses and errors](https://on.auto/docs/reference/http#responses-and-errors) lists the status codes, problem reasons and kinds. [Function availability](https://on.auto/docs/concepts/functions#availability) says which function types the runtime runs.

## Sitemap

See the [full documentation and product sitemap](https://on.auto/sitemap.md) for related pages.
