MCP catalogs
Managed agents and runs
Exact arguments and input schemas for managed agents and runs.
On this page
arc_list_model_profiles
Saved AI-model profiles: optional presets carrying certification, which arc_spawn_agents can clone by model_profile_id. arc_list_model_sources lists every model a seat can run, including ones with no profile. Never inspect Arc's private database to discover models.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
detail | no | string | default summary; full adds certification detail, timeouts and sampling Allowed: summary, full. |
max_chars | no | integer | See the schema below. |
offset | no | integer | See the schema below. |
Complete input schema
{
"type": "object",
"properties": {
"detail": {
"type": "string",
"enum": [
"summary",
"full"
],
"description": "default summary; full adds certification detail, timeouts and sampling"
},
"max_chars": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"required": []
}arc_list_model_sources
What arc_spawn_agents can run: connections (key, ready or unverified, model count), local models, the room's recent routes, and catalog models when you pass query or connection_id.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
query | no | string | model id or label substring, across loaded catalogs and local models |
connection_id | no | string | one connection (id, provider or label); offset pages its catalog |
offset | no | integer | See the schema below. |
room_id | no | string | See the schema below. |
detail | no | string | Allowed: summary, full. |
max_chars | no | integer | See the schema below. |
Complete input schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "model id or label substring, across loaded catalogs and local models"
},
"connection_id": {
"type": "string",
"description": "one connection (id, provider or label); offset pages its catalog"
},
"offset": {
"type": "integer"
},
"room_id": {
"type": "string"
},
"detail": {
"type": "string",
"enum": [
"summary",
"full"
]
},
"max_chars": {
"type": "integer"
}
},
"required": []
}arc_spawn_agents
Spawn 1..32 Arc-managed seats into a room from one model source: connection+model, local_model, copy_of, model_profile_id or provider+model (arc_list_model_sources lists them; no saved profile needed); none = machine default. role and instructions brief every instance. Seats inherit the room's Safe/Full Access (an unverified connection's stay Safe); worktrees-mode rooms give each a worktree. Desktop harnesses are invited, not spawned: arc_create_invite naming={base, auto_number}.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
room_id | yes | string | the room every spawned seat joins |
count | no | integer | instances to create, 1..32 (default 1) |
model_profile_id | no | string | saved model profile to clone |
provider | no | string | with model: a saved profile's provider, else a connection's; local for local models |
model | no | string | catalog model id, or a local model's name |
connection | no | string | connection id, provider or label; pair with model |
manual | no | boolean | use model though the catalog lacks it |
local_model | no | string | local model id, label or GGUF file name |
copy_of | no | string | seat handle or membership id to clone |
workspace_mode | no | string | workspace policy for the spawned seats (default follows the source); read_only seats in a room with no project folder are chat-only unless workspace_path names one Allowed: standard, read_only. |
workspace_path | no | string | absolute folder these seats work in instead of the room's; lets a read-only reviewer read a folder the room does not have, and the seats keep it when the room's folder changes |
name | no | string | display-name base; batches number themselves 1..N |
role | no | string | role label recorded on each membership |
instructions | no | string | custom instructions every instance carries |
auto_start | no | boolean | start every valid seat immediately (default false) |
initial_brief | no | string | optional first turn for every seat; requires auto_start=true |
run_id | no | string | optional commissioned run to attribute every initial turn to |
max_steps | no | integer | durable checkpoint interval, 1..500; not a lifetime limit |
behaviours | no | array | presets every new seat starts with: [{preset_id, params?, instructions?}], for example [{"preset_id":"follows_agent","params":{"agent_id":"codex"}}]; arc_list_behaviours lists the presets |
request_id | no | string | idempotency key; retry with the SAME id |
Complete input schema
{
"type": "object",
"properties": {
"room_id": {
"type": "string",
"description": "the room every spawned seat joins"
},
"count": {
"type": "integer",
"description": "instances to create, 1..32 (default 1)"
},
"model_profile_id": {
"type": "string",
"description": "saved model profile to clone"
},
"provider": {
"type": "string",
"description": "with model: a saved profile's provider, else a connection's; local for local models"
},
"model": {
"type": "string",
"description": "catalog model id, or a local model's name"
},
"connection": {
"type": "string",
"description": "connection id, provider or label; pair with model"
},
"manual": {
"type": "boolean",
"description": "use model though the catalog lacks it"
},
"local_model": {
"type": "string",
"description": "local model id, label or GGUF file name"
},
"copy_of": {
"type": "string",
"description": "seat handle or membership id to clone"
},
"workspace_mode": {
"type": "string",
"enum": [
"standard",
"read_only"
],
"description": "workspace policy for the spawned seats (default follows the source); read_only seats in a room with no project folder are chat-only unless workspace_path names one"
},
"workspace_path": {
"type": "string",
"description": "absolute folder these seats work in instead of the room's; lets a read-only reviewer read a folder the room does not have, and the seats keep it when the room's folder changes"
},
"name": {
"type": "string",
"description": "display-name base; batches number themselves 1..N"
},
"role": {
"type": "string",
"description": "role label recorded on each membership"
},
"instructions": {
"type": "string",
"description": "custom instructions every instance carries"
},
"auto_start": {
"type": "boolean",
"description": "start every valid seat immediately (default false)"
},
"initial_brief": {
"type": "string",
"description": "optional first turn for every seat; requires auto_start=true"
},
"run_id": {
"type": "string",
"description": "optional commissioned run to attribute every initial turn to"
},
"max_steps": {
"type": "integer",
"description": "durable checkpoint interval, 1..500; not a lifetime limit"
},
"behaviours": {
"type": "array",
"items": {
"type": "object"
},
"description": "presets every new seat starts with: [{preset_id, params?, instructions?}], for example [{\"preset_id\":\"follows_agent\",\"params\":{\"agent_id\":\"codex\"}}]; arc_list_behaviours lists the presets"
},
"request_id": {
"type": "string",
"description": "idempotency key; retry with the SAME id"
}
},
"required": [
"room_id"
]
}arc_list_seats
Arc-managed seats of a room (default: joined room) or project: model, enabled, state (idle|running|waiting|stopped), active turn, queue depth; plus open runs.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
room_id | no | string | See the schema below. |
project_id | no | string | See the schema below. |
max_chars | no | integer | See the schema below. |
offset | no | integer | See the schema below. |
Complete input schema
{
"type": "object",
"properties": {
"room_id": {
"type": "string"
},
"project_id": {
"type": "string"
},
"max_chars": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"required": []
}arc_create_run
Commission a durable run in a room: it groups seat turns, wakeups, usage, events and stop/completion. It runs until arc_complete_run or arc_stop_run. A managed seat creating a run from its active turn attributes that turn to the run automatically. usage_target is advisory and never blocks work — keys tokens, steps, elapsed_minutes; unknown keys are refused.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
room_id | yes | string | See the schema below. |
title | no | string | See the schema below. |
brief | no | string | See the schema below. |
conductor_membership_id | no | string | See the schema below. |
run_sheet_artifact_id | no | string | See the schema below. |
usage_target | no | object | See the schema below. |
metadata | no | object | See the schema below. |
auto_complete | no | boolean | no conductor: complete ~120 s after the last turn completes if idle and Done-when passes |
request_id | no | string | idempotency key; retry with the SAME id |
Complete input schema
{
"type": "object",
"properties": {
"room_id": {
"type": "string"
},
"title": {
"type": "string"
},
"brief": {
"type": "string"
},
"conductor_membership_id": {
"type": "string"
},
"run_sheet_artifact_id": {
"type": "string"
},
"usage_target": {
"type": "object"
},
"metadata": {
"type": "object"
},
"auto_complete": {
"type": "boolean",
"description": "no conductor: complete ~120 s after the last turn completes if idle and Done-when passes"
},
"request_id": {
"type": "string",
"description": "idempotency key; retry with the SAME id"
}
},
"required": [
"room_id"
]
}arc_list_runs
List durable commissioned runs. room_id defaults to your joined room; pass another room's id to look elsewhere; status filters. Rows add activity, idle_since, completable and blockers.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
room_id | no | string | See the schema below. |
status | no | string | Allowed: commissioned, running, paused, completed, stopped, failed. |
max_chars | no | integer | See the schema below. |
offset | no | integer | See the schema below. |
Complete input schema
{
"type": "object",
"properties": {
"room_id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"commissioned",
"running",
"paused",
"completed",
"stopped",
"failed"
]
},
"max_chars": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"required": []
}arc_run_status
Read a commissioned run, durable events, current run-tagged work, activity, completable, token usage, and advisory target deltas. Defaults to a bounded summary without turn transcripts; pass detail=full deliberately when transcript-level diagnostics are needed. Missing usage is unavailable rather than zero; target overage never blocks execution.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
run_id | yes | string | See the schema below. |
detail | no | string | default summary; full may be very large Allowed: summary, full. |
max_chars | no | integer | character budget; default 12000, floor 500 |
Complete input schema
{
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"detail": {
"type": "string",
"enum": [
"summary",
"full"
],
"description": "default summary; full may be very large"
},
"max_chars": {
"type": "integer",
"description": "character budget; default 12000, floor 500"
}
},
"required": [
"run_id"
]
}arc_run_seat
Start or reuse a managed seat and send it a run-tagged turn; busy and starting seats queue durably in FIFO order (see blocked_by). When the reply lands, end the run with arc_complete_run. run_id is required (a call without it is refused).
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
run_id | yes | string | See the schema below. |
membership_id | no | string | See the schema below. |
agent_id | no | string | See the schema below. |
brief | no | string | See the schema below. |
max_steps | no | integer | durable checkpoint interval, 1..500; Arc continues automatically |
origin_id | no | string | optional stable delivery key; repeats return the existing turn instead of duplicating it |
request_id | no | string | idempotency key; retry with the SAME id |
Complete input schema
{
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"membership_id": {
"type": "string"
},
"agent_id": {
"type": "string"
},
"brief": {
"type": "string"
},
"max_steps": {
"type": "integer",
"description": "durable checkpoint interval, 1..500; Arc continues automatically"
},
"origin_id": {
"type": "string",
"description": "optional stable delivery key; repeats return the existing turn instead of duplicating it"
},
"request_id": {
"type": "string",
"description": "idempotency key; retry with the SAME id"
}
},
"required": [
"run_id"
]
}arc_seat_status
One managed seat's work on a run: turn digests, queue, active turn (any run), blocked_by, token usage. detail=full with turn_id returns that turn's events. run_id is required (a call without it is refused).
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
run_id | yes | string | See the schema below. |
membership_id | no | string | See the schema below. |
agent_id | no | string | See the schema below. |
detail | no | string | Allowed: summary, full. |
turn_id | no | string | See the schema below. |
max_chars | no | integer | See the schema below. |
Complete input schema
{
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"membership_id": {
"type": "string"
},
"agent_id": {
"type": "string"
},
"detail": {
"type": "string",
"enum": [
"summary",
"full"
]
},
"turn_id": {
"type": "string"
},
"max_chars": {
"type": "integer"
}
},
"required": [
"run_id"
]
}arc_seat_steps
Watch a managed seat's work: its recent tool steps and turn boundaries, newest last, as {seq, ts, turn_id, step, tool, args_summary, ok, error}. Pass membership_id or agent_id (arc_list_seats); room_id defaults to your joined room. Feed next_since back as since to read only what is new.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
room_id | no | string | See the schema below. |
membership_id | no | string | See the schema below. |
agent_id | no | string | See the schema below. |
since | no | integer | seq of the last record you read; omit for the newest records, 0 for the oldest |
limit | no | integer | records to return (default 50, max 200); with since you get the oldest first |
max_chars | no | integer | See the schema below. |
offset | no | integer | See the schema below. |
Complete input schema
{
"type": "object",
"properties": {
"room_id": {
"type": "string"
},
"membership_id": {
"type": "string"
},
"agent_id": {
"type": "string"
},
"since": {
"type": "integer",
"description": "seq of the last record you read; omit for the newest records, 0 for the oldest"
},
"limit": {
"type": "integer",
"description": "records to return (default 50, max 200); with since you get the oldest first"
},
"max_chars": {
"type": "integer"
},
"offset": {
"type": "integer"
}
},
"required": []
}arc_cancel_seat_turn
Cancel a managed seat's running turn without its session fence: pass membership_id or agent_id (arc_list_seats); room_id defaults to your joined room. The session survives and its queued turns still run. A seat with no active turn returns cancelled=false and the next call.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
room_id | no | string | See the schema below. |
membership_id | no | string | See the schema below. |
agent_id | no | string | See the schema below. |
request_id | no | string | idempotency key; retry with the SAME id |
Complete input schema
{
"type": "object",
"properties": {
"room_id": {
"type": "string"
},
"membership_id": {
"type": "string"
},
"agent_id": {
"type": "string"
},
"request_id": {
"type": "string",
"description": "idempotency key; retry with the SAME id"
}
},
"required": []
}arc_stop_seat
Stop one seat's active and queued work for this run; the reusable session survives. run_id is required (a call without it is refused).
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
run_id | yes | string | See the schema below. |
membership_id | no | string | See the schema below. |
agent_id | no | string | See the schema below. |
scope | no | string | run (default): this run's turns only. seat: the active turn of any run, and the whole queue Allowed: run, seat. |
request_id | no | string | idempotency key; retry with the SAME id |
Complete input schema
{
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"membership_id": {
"type": "string"
},
"agent_id": {
"type": "string"
},
"scope": {
"type": "string",
"enum": [
"run",
"seat"
],
"description": "run (default): this run's turns only. seat: the active turn of any run, and the whole queue"
},
"request_id": {
"type": "string",
"description": "idempotency key; retry with the SAME id"
}
},
"required": [
"run_id"
]
}arc_stop_run
Stop all active and queued work tagged to a commissioned run and mark the run stopped. Unrelated work in reused seat sessions is preserved. Returns the run summary.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
run_id | yes | string | See the schema below. |
detail | no | string | Allowed: summary, full. |
max_chars | no | integer | See the schema below. |
request_id | no | string | idempotency key; retry with the SAME id |
Complete input schema
{
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"detail": {
"type": "string",
"enum": [
"summary",
"full"
]
},
"max_chars": {
"type": "integer"
},
"request_id": {
"type": "string",
"description": "idempotency key; retry with the SAME id"
}
},
"required": [
"run_id"
]
}arc_complete_run
Mark a finite commissioned run complete once its observable work and Done-when contract are satisfied. For Arc loops, call finish after each cycle; use arc_control_loop to pause or stop. returns the same bounded summary as arc_run_status. A managed seat may call it from its own final run-tagged turn; every other turn, queue, wake delivery and Done-when clause must already be settled.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
run_id | yes | string | See the schema below. |
max_chars | no | integer | summary character budget; default 12000, floor 500 |
request_id | no | string | idempotency key; retry with the SAME id |
Complete input schema
{
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"max_chars": {
"type": "integer",
"description": "summary character budget; default 12000, floor 500"
},
"request_id": {
"type": "string",
"description": "idempotency key; retry with the SAME id"
}
},
"required": [
"run_id"
]
}arc_set_done_when
CAS-write validated structured completion clauses for a room or one managed seat. expected_version is the room state_version (room gate) or the membership_revision (seat gate). For a seat, inherit=true with clauses omitted restores room inheritance. Unknown or malformed clauses fail closed.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
room_id | yes | string | See the schema below. |
membership_id | no | string | optional seat target; omit for the room gate |
clauses | no | array | task clauses name a positive task_id; verdict clauses name metric and optional exact scope |
inherit | no | boolean | seat only: restore room-gate inheritance; omit clauses |
expected_version | yes | integer | room state_version or target membership_revision from the latest read |
request_id | no | string | idempotency key; retry with the SAME id |
Complete input schema
{
"type": "object",
"properties": {
"room_id": {
"type": "string"
},
"membership_id": {
"type": "string",
"description": "optional seat target; omit for the room gate"
},
"clauses": {
"type": "array",
"items": {
"type": "object"
},
"description": "task clauses name a positive task_id; verdict clauses name metric and optional exact scope"
},
"inherit": {
"type": "boolean",
"description": "seat only: restore room-gate inheritance; omit clauses"
},
"expected_version": {
"type": "integer",
"description": "room state_version or target membership_revision from the latest read"
},
"request_id": {
"type": "string",
"description": "idempotency key; retry with the SAME id"
}
},
"required": [
"room_id",
"expected_version"
]
}arc_run_report
Create or refresh the run's one canonical report artifact (Arc-observed events, gate edits, seat outcomes, usage, model sources, completion readiness). Call once after arc_complete_run; repeat calls update the same artifact. Returns a receipt (artifact_id, bytes, counts) by default; the body is one arc_get_artifact away.
| Argument | Required | Type | Description / schema default |
|---|---|---|---|
run_id | yes | string | See the schema below. |
detail | no | string | default receipt; full echoes the whole report Allowed: receipt, full. |
request_id | no | string | idempotency key; retry with the SAME id |
Complete input schema
{
"type": "object",
"properties": {
"run_id": {
"type": "string"
},
"detail": {
"type": "string",
"enum": [
"receipt",
"full"
],
"description": "default receipt; full echoes the whole report"
},
"request_id": {
"type": "string",
"description": "idempotency key; retry with the SAME id"
}
},
"required": [
"run_id"
]
}