Connect an AI agent (MCP)

Drive Marshal from the AI agent you already use. Connect Claude Code or Codex on your laptop, or a headless agent in CI, and it can do what you do in the web app: start runs, follow them, steer them, answer the questions they ask, manage your spaces, deputies, manifests and connections, and for admins, run the org. It acts as the person who signed in, with that person’s permissions.

The endpoint is on the same host as the web app:

https://<your-marshal-host>/mcp

Each install has its own endpoint. Give your people this address.

What you can do with it

• Hand off a task and keep coding. In Claude Code: “Start the release-notes mission on our docs deputy, and tell me when it asks something.” The agent starts the run (runs_launch), follows it (runs_wait), and shows you the question when the run asks one. You answer in the same chat, and the agent passes your answer on (inbox_answer). The run continues.
• Find out why a run failed. “Why did my last run fail?” The agent lists your runs (runs_list), reads the failed one (runs_get) and its output (runs_logs), and checks the space it ran in for restarts or out-of-memory stops (spaces_get). You get the cause, not a page of logs.
• Clear your inbox from one place. “What is waiting for me?” The agent lists the open asks from your runs (inbox_list), and answers the ones you decide on (inbox_answer).
• Get answers from the docs. “What does Marshal recommend for space compute sizes?” The agent searches the official docs (docs_search), reads the page (docs_read), and answers with the link.

See it end to end: Delegate from your AI client.

Step 1: an admin turns MCP on

MCP access is off in every org until an owner or admin turns it on, in Organization settings > General, card MCP access. Until then, an agent that tries to connect is told to ask an org admin.

The approval switches are separate on purpose. An agent reads text that runs produce, so text inside a run can try to steer it. Keep approval gates and policy approvals for people unless you decide otherwise.

Every run and space uses compute and AI tokens, so a person approves each launch by default. Turn Require approval for every launch off when you want unattended launches, such as an API key in CI. Marshal asks you to confirm the change first. With approval off, an agent can start several runs in a row on its own. Runs it starts still count toward the run cap, and every launch is in the audit log.

The switches are stored as mcp.access_enabled, mcp.answer_approval_gates, mcp.policy_approvals and mcp.launch_without_approval (the inverse of Require approval for every launch) in the org’s settings.

Step 2: connect your agent

Marshal shows the exact commands for your install, with your address filled in:

• Connect agent, in the top bar on every page. It opens the same commands, with a tab for Claude Code and a tab for Codex, and a link to your connected apps. Once you have connected an agent, it shrinks to an icon.
• Personal settings > Connected apps, card Connect an agent, with a tab for Claude Code and a tab for Codex. Select the copy button next to a command.
• Home, when you have no connected app yet. The card there shows the Claude Code command and links to the full card.

claude mcp add --transport http marshal https://<your-marshal-host>/mcp

codex mcp add marshal --url https://<your-marshal-host>/mcp
codex mcp login marshal

marshal api-key create ci-agent --role=member

claude mcp add --transport http marshal https://<your-marshal-host>/mcp \
  --header "Authorization: Bearer marshal_..."

marshal api-key create agent --role=admin --mcp-scopes read,launch,answer,manage

What you approve

After you sign in, a consent page asks:

• which org this connection is for. One org per connection.
• which permissions to grant. See the five permissions.

The page names the client and the host its identity comes from. A client whose host is not on the install’s verified list is marked Unverified, and only Read starts ticked. Tick the others yourself if you want them.

Manage your work and Org admin are never ticked for you, for any client. You opt in on purpose, because they change things. Org admin is shown only to owners and admins.

Select Approve, and the client is connected. Nothing has to be registered in Marshal first.

What the agent can do

Every tool needs exactly one of five permissions, so a Read-only connection cannot start, stop, change or delete anything.

The five permissions

Manage and Admin are never pre-ticked on the consent page, and Admin is offered only to owners and admins. Your role still decides each call: an agent never does more than the person it acts for.

Every tool

The Lowest role column is the lowest org role the tool is listed for. Member means any member. Admin means owners and admins. A tool that asks you to confirm shows you what will happen first, and declining changes nothing. Deputy tools appear when deputies are enabled for your org.

Runs

Start, follow, steer and continue runs.

Name every run you start. A title such as Fix flaky checkout test shows in the runs list, in the web app and in marshal runs list, so runs from the same mission are easy to tell apart. A launch that waits in a mission’s queue shows its title there too, and the run keeps it when it starts. A title can be up to 120 characters. A launch without a title still starts, and the answer asks you to name the next one.

Inbox and agent requests

Answer what runs and agents are waiting on you for.

Spaces

Create, resize and manage your spaces.

Space policy approvals

Allow a blocked domain or tool for a space. These need the Agents may approve blocked domains and tools switch.

Deputies, missions, schedules and triggers

Build and run deputies.

Memory

Read and write deputy and personal memory documents.

Manifests and stacks

Environments for runs and the curated stacks they build on.

Connections, credentials and secrets

Manage who can reach what. Values are never returned, and adding or replacing a secret value happens in the web app.

Marketplace, network and compute

Org-wide packages, network policies and compute classes.

People

Members, invitations and teams.

Admin dashboards

The admin dashboards, for owners and admins.

Security Center

Block a vulnerable package version, see what it affects, move it out of your stacks and manifests, and restart spaces that run an old setup. These are the same actions as the Security Center in the web app, for owners and admins. Anything that changes something asks you to confirm first, showing facts read from the server.

Audit

Search the audit log.

Credential, secret and vault values are never returned. Adding or replacing a value happens in the web app, and the tool hands you the link.

Docs

Let the agent read the official docs instead of guessing. The pages are the ones on docs.marshal.codes, bundled with your install, so the agent reads the docs as of your install’s API release. It works on installs with no outbound internet, and every member and admin sees the same pages.

Ask for them by name when you want a sourced answer: “Search the Marshal docs for how to add a package to a stack, read the best page, and tell me the steps with the link.”

How the tools behave

• Confirmations come from your client. Claude Code and Codex ask you before the action runs.
• Short ids work. The run and ask tools take the first 8 or more characters of an id, the way the web app and the CLI show it, as long as only one run or ask that you can see starts with them: your own runs (any run in the org for owners and admins) and the asks you may answer. Give the whole id for anything else.
• Messages reach a run that is waiting on an ask. A run waiting on an ask cannot read its queue until the ask is settled, so runs_message attaches your message to the ask instead and returns delivered: true with attached_to_ask. The agent gets the message together with the answer, before it acts. The person answering sees it on the ask card in the web app and in inbox_get. An ask holds up to 5 messages of 2 KB each; when it is full, wait for the ask to be settled and send again. A message is attached only to the agent’s own question, and only when the run can show it. In every other case (a tool-permission prompt, a longer message, a run whose agent cannot show the message, an interrupt) the message is queued as before, and delivered is false while the run waits. If the ask is skipped, a running agent reads the message at the end of its turn; a parked run whose ask is skipped does not resume, and the message ends with it. If the ask times out, the run ends and the message ends with it: continue the run with runs_continue and repeat the instruction.
• runs_continue says what to do instead. When a run kept no conversation to continue from, start a new run with runs_launch and give it what it needs to know in notes.
• Runs started over MCP read as MCP. A run started with runs_launch or deputies_run_adhoc shows MCP as its trigger on the run page and in the Runs list, so you can tell it apart from a run started in the web app, the CLI or the API.
• runs_wait holds at most 30 seconds per call and returns at most 200 events. It returns early when the run ends, asks a question, or produces events. The agent calls it again with the cursor it got back.
• runs_wait keeps each answer small. One call returns about 24,000 characters of events (max_chars, up to 57,344) and the rest on the next call, so nothing is lost. The text of each tool call and tool result is cut to its first 400 characters (text_chars; -1 returns it whole, and runs_logs always does). summary returns no events at all: the run’s state, the agent’s last message, how many tools it called and a count of each kind of event, over everything after the cursor.
• A run that handed off names its successor. When a run ends because a later segment picked it up (stop reason continued, after an answer or a wake), runs_get and runs_wait return that run’s id as continued_by_run_id. Follow that run to see the work finish.
• Watch for changes with changes_since. Call it once with no cursor to get a cursor, then pass the cursor from each answer into the next call. Each call returns only what happened since: runs created, started or ended, and asks raised, answered, expired or canceled, oldest first. Add minutes (up to 1,440) on the first call to start with the last few minutes; it is ignored once you pass a cursor. You see your own runs and the asks put to you; scope=org shows the whole org to owners and admins. An event appears about 5 seconds after it happens, so a change that commits a moment late is still returned, in order, and each event comes back once. A change that takes more than 5 seconds to commit can still be missed. When has_more is true, call again straight away. A cursor older than 24 hours starts again from 24 hours ago and says reset. A run that parks gets an ended event, because its turn is over; the state on an event is the run’s state when you call, so a run that has since been ended shows its final state. What happens to a parked run afterwards, and runs waiting on an ask, show in runs_attention.
• Lists stay short. runs_list shows the first 80 characters of each task, and inbox_list with brief shows one line per ask. Read the whole thing with runs_get or inbox_get.
• runs_logs reads the stored transcript first. If your install keeps no transcripts, it reads the run events that are still kept (about an hour after the run ends). When there is neither, it returns logs_unavailable, never an empty success.
• Deputy cost is one call. admin_cost with view: deputy rolls up what your deputies’ runs cost over a date range (since and until, up to 90 days, the last 7 by default). Set group_by to deputy (run hours, compute, LLM cost, total and tokens per deputy, most tokens first), day (LLM cost and tokens per UTC day) or deputy_day (each deputy with a row for each day it used tokens, up to 31 days). It lists the top 20 deputies (10 for deputy_day) and sums the rest in other, so the total covers every deputy. Only the usage of deputy runs counts, not people’s own spaces. Per-day rows, and the total of the day and deputy_day groupings, carry LLM cost and tokens only. Deputies are ordered by tokens, then known spend (compute plus priced LLM cost), so a large spender on an unpriced model is listed first. Run hours are the part of each run inside the range, and a run that is waiting on a person or parked adds its hours when it completes, so a closed day can grow. A model with no price is flagged unpriced on the row, named once in the total, and its cost is left out, never counted as $0. Owners and admins only; it answers once per 10 seconds.
• Run output is wrapped in an <untrusted-content> block, with known secret shapes redacted, so the agent treats it as data and not as instructions. The note that explains the block comes once per answer, on the first block.

The run cap

One person may have 5 runs started through the MCP active at once, per org. The sixth is refused, with the runs that are in the way:

refused: you already have 5 active runs started through the MCP in this org,
and the cap is 5. Active runs: <ids>. Wait for one to end (runs_wait) or stop
one (runs_stop), then launch again.

Runs started in the web app, the CLI or by a schedule do not count. The cap guards clients that cannot ask you to confirm a launch, so think about that before you raise it. To change it for the whole install, set MARSHAL_MCP_RUN_CAP on the API (chart value api.extraEnv).

Auditing and revoking

Every launch, stop and answer, and every sign-in, token and revoke, is written to the audit log with the person, the client, the permissions and the outcome, under channel mcp. Search it on the Audit page, or from an agent with audit_search.

To end a connection:

• A person revokes their own in Personal settings > Connected apps, with Revoke. The client is refused on its next call and must sign in again.
• An owner or admin sees every connection in the org on the same page and can revoke any of them.
• Turning off Allow MCP access ends every connection in the org at once.

Access also ends by itself when the person leaves the org or their role changes, by the same rules that end their web sign-in.

Other MCP clients

Any client that speaks MCP over streamable HTTP and OAuth 2.1 with PKCE can connect. Nothing about the endpoint is Claude-specific. One rule decides whether a client works: its redirect URI must be https://, or http:// on a loopback host (127.0.0.1, [::1] or localhost, on any port, which is what desktop clients use). A client that registers a private-use scheme such as myapp://callback is refused.

Installs with no inbound internet

Most self-hosted installs take no traffic from the internet. MCP works there with two settings. Claude Code, Codex, other clients inside your network, and headless agents with an API key all work.

How a laptop reaches the install

The chart supports two ways:

• A tailnet name. Set tailscaleIngress.enabled=true and tailscaleIngress.hostname, and the install also answers on <hostname>.<your tailnet>.ts.net for anyone on the tailnet. Also set tailscaleIngress.tailnet to your tailnet’s domain. The chart then allows both the short name and the full MagicDNS name on /mcp.
• An internal DNS name. Any name that resolves to the install’s ingress inside your network. List it in ingress.extraHosts so it gets its own routing rule. If the name reaches the API another way, list it in mcp.extraHosts.

A name that is not in one of those lists gets 403 on /mcp, while the rest of the app works on it. This check is deliberate: it stops a name someone else controls from pointing at your install and driving the MCP with a person’s token.

Each name is its own sign-in

A person signs in per name. Connect on marshal.ts.net and you sign in there. The same laptop connecting on marshal.internal signs in again. The address you use decides the whole exchange (the sign-in page, the consent page and the token), so a token from one name is refused on the other, and the client asks you to sign in again.

So pick one name per audience and put it in your install’s instructions.

No outbound internet: turn off client metadata documents

By default, Marshal identifies a client by fetching the https:// URL the client uses as its ID, a Client ID Metadata Document on the public internet. An install with no outbound internet cannot fetch it: the fetch waits for its timeout and fails, and the person sees an error about the client’s host.

On such an install, set mcp.cimdEnabled=false in the chart (MARSHAL_MCP_CIMD_ENABLED=false on the API). Then:

• the authorization server stops advertising those documents, so clients register themselves dynamically instead. Claude Code and other standard clients do this.
• a client that still sends a URL as its ID is refused at once, with a message telling it to register dynamically.
• every client is Unverified on the consent page (only a document can carry a verified host), so only Read starts ticked and the person ticks the ones they want.

Keep it on (the default) if the install can reach the internet outbound, even when nothing can reach it inbound. Fetching those documents is what lets the consent page tell a real client from one that only uses the name.

Related

• Connect an AI agent
• Runs
• Deputies
• Audit log
• Networking and egress