Skip to Content
How-to guidesConnect an AI agent (MCP)

Connect an AI agent over MCP

Run Marshal from the AI client you already use, such as Claude Code or Codex. Ask it to start a run, check on it, and answer what is waiting on you, without leaving your editor or chat. The client acts as you, with only the permissions you approve.

Before you start

  • Role: any member.
  • An admin or owner turns MCP on: organization menu, Organization settings, General, card MCP access, switch Allow MCP access.
  • Your Marshal address, the one you open in the browser.

Steps

  1. Add Marshal to your client as an MCP server. For Claude Code, run this once:

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

    For Codex, run codex mcp add marshal --url https://<your-marshal-host>/mcp and then codex mcp login marshal. Marshal shows both commands, filled in for your install, under Personal settings, Connected apps, and on Home until you connect an app. For headless agents and the full tool list, see Connecting an AI agent (MCP).

  2. Use any Marshal tool from the client. Your browser opens and you sign in to Marshal as usual. In Claude Code, /mcp starts the same sign-in.

  3. The consent page says the client “wants to use Marshal as you”. Check the Organization and the Permissions, then click Approve. Read, Launch and stop runs and Answer your inbox start ticked for a verified client. Manage your work and Org admin (owners and admins only) are never ticked for you; tick them to let the agent change your spaces, deputies and manifests, or run the org. Click Deny if you did not start the connection.

  4. Try it. Ask your client things like:

    • “List my Marshal manifests and start a run on backend that fixes the failing lint check.”
    • “What is waiting on me in Marshal?” and then “Answer the first question: use the staging database.”
    • “Show me the logs of my last run and tell me why it failed.”

To see or end a connection later, open the account menu, Personal settings, Connected apps, and click Revoke on the app.

What you should see

  • The app listed under Connected apps with its permissions, the connect date, and when it was last used.
  • Runs the client starts appear in Runs, started by you.
  • After Revoke, the app’s access ends on its next call. It can ask for access again at any time.

Next

Start a run in the web and follow it: open a run your client started and watch it on its run page.

Set up OAuth on a custom MCP serverOverview