Delegate from your AI client
You are deep in a task in Claude Code, and a second job comes up: fix the flaky checkout test in acme/web. You do not want to switch tools or give up your editor. Ask your assistant to hand it to Marshal. A run does the work in its own space, and your assistant follows it, brings you its questions and reads you the result.
The result
- You start, follow and stop runs from the chat you already work in.
- The heavy work runs in Marshal, on your team’s manifest and credentials, not on your laptop.
- Questions from your runs come to you in the same chat, and your answer goes straight back.
- Your client acts as you, with only the permissions you approve, and every launch, stop and answer is in the audit log.
How it works
You ask Claude Code to start a run on the web-app manifest. It calls runs_launch, and Claude Code asks you to confirm before the run starts. The run works in its own fresh space. Your client calls runs_wait to follow it, and each call returns as soon as the run produces events, asks a question or ends. When the agent asks “Can I skip the payment provider stub?”, your client shows it to you from inbox_list. You answer in the chat, and inbox_answer sends it in your name. When the run ends, runs_logs gives your client the transcript, wrapped as untrusted content so your client treats it as data.
What you use
| Piece | Its role here |
|---|---|
| Connect an AI agent (MCP) | The endpoint at https://<your-marshal-host>/mcp and every tool it offers. |
| Runs | The work itself, each in its own space, with a full record. |
| Deputies | Saved missions your client can launch by name. |
| Manifests and stacks | The environment and credentials each run gets. |
| Home and notifications | The same questions, also on Home and in Slack. |
| Audit log | Every MCP launch, stop, answer and sign-in, under channel mcp. |
Every tool needs one of five permissions, and this use case needs three. Launch covers runs_launch and runs_stop. Answer covers inbox_answer. Read covers runs_wait, runs_get, runs_list, runs_logs, inbox_list, deputies_list, manifests_list, spaces_get and audit_search. Manage and Admin add the tools that change your spaces, deputies and manifests, and run the org. See The five permissions.
Build it
-
An owner or admin turns on Allow MCP access under Organization settings > General, card MCP access. See Step 1: an admin turns MCP on.
-
Add Marshal to Claude Code once:
claude mcp add --transport http marshal https://<your-marshal-host>/mcp -
Call any Marshal tool, or run
/mcpin Claude Code. Sign in to Marshal in the browser that opens. -
On the consent page, check the Organization and the permissions, then select Approve. See Connect an AI agent over MCP.
-
Ask: “List my Marshal manifests and start a run on
web-appthat fixes the flaky checkout test.” -
Ask: “What is waiting on me in Marshal?” and answer from the chat. See Answer a question from a run.
-
See or end the connection any time under Personal settings > Connected apps, with Revoke.
Make it yours
- Launch a saved mission. “Start the release-notes mission on our docs deputy.” Your client finds it with
deputies_listand launches it with its inputs. See Create a deputy and a mission. - Ask why a run failed. Your client reads the run with
runs_get, its output withruns_logs, and its space withspaces_getfor restarts and out-of-memory stops. - Read-only for a cautious start. Approve only Read on the consent page. Your client can follow and explain runs, and cannot start or stop anything.
- Run it from CI. An owner or admin creates an org API key with
marshal api-key create ci-agent --role member, and the CI job sends it as a bearer token to/mcp. See Create an API key for CI.
Each person can have 5 runs started through MCP active at once in an org. Approval and takeover asks wait for a person in the web app or Slack unless an admin turns on Agents may answer approval gates.