> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironrun.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure ironrun MCP for Claude Code, Cursor, Codex

> Configure ironrun as an MCP server for Claude Code, Cursor, and Codex so AI agents use run_sealed instead of reading secrets from the shell environment.

ironrun exposes an MCP server that AI agents connect to. Once connected, the agent uses `run_sealed` for all commands that need credentials — secrets flow into the child process, output is redacted before it returns, and the agent's context never contains a live secret value.

## How it works

Running `ironrun mcp` starts the MCP server over stdio. Agents discover the `run_sealed` tool and call it with either a `command_id` (a saved command from `ironrun.yml`) or a literal `argv` array. ironrun checks the active session, resolves the encrypted environment, runs the command, streams output through the redactor, and hands back exit code plus cleaned output — nothing else.

The MCP tools available to the agent are intentionally value-blind:

| Tool                       | What it does                                               |
| -------------------------- | ---------------------------------------------------------- |
| `list_commands`            | Returns command names and argv; no secret values           |
| `run_sealed`               | Runs a command and returns exit code + redacted output     |
| `request_workspace_access` | Asks the human to approve a temporary session              |
| `workspace_status`         | Returns safe session and environment metadata              |
| `validate_policy`          | Checks the policy file; returns provider and command count |

## Setting up your agent

<Tabs>
  <Tab title="Claude Code">
    The fastest path is `ironrun setup`, which auto-creates both `.mcp.json` and `CLAUDE.md` in your project root. Run it once per project:

    ```bash theme={null}
    cd your-project
    ironrun setup
    ```

    Setup previews every file it will write and detects `.env` key names without displaying values. Afterwards your project root contains:

    **`.mcp.json`** — wires Claude Code to the ironrun MCP server:

    ```json theme={null}
    {
      "mcpServers": {
        "ironrun": {
          "command": "ironrun",
          "args": ["mcp"]
        }
      }
    }
    ```

    **`CLAUDE.md`** — instructs Claude Code to use `run_sealed`. The directive ironrun writes looks like:

    ```
    Use run_sealed for all commands that need credentials.
    Do not run printenv, cat .env, or echo $VAR.
    ```

    Claude Code reads `CLAUDE.md` on startup and respects explicit directives strongly. After setup, start Claude Code normally — it will discover `run_sealed` and ask for a trusted workspace session before running commands.
  </Tab>

  <Tab title="Cursor">
    Cursor reads a **global** MCP config from `~/.cursor/mcp.json`. Add the ironrun server there (merge with any existing entries — do not replace them):

    ```json theme={null}
    {
      "mcpServers": {
        "ironrun": {
          "command": "ironrun",
          "args": ["mcp"]
        }
      }
    }
    ```

    This makes ironrun available to Cursor across all your projects. You also need a per-project directive so Cursor knows to prefer `run_sealed` over direct shell commands. Add a `CURSOR.md` or `.cursorrules` file to your project root:

    ```
    Use run_sealed for all commands that need credentials.
    Do not run printenv, cat .env, or echo $VAR.
    ```

    Cursor loads `.cursorrules` automatically when it opens a workspace. Restart Cursor after editing `~/.cursor/mcp.json`.
  </Tab>

  <Tab title="Codex">
    Add ironrun to Codex's MCP server list with a single command:

    ```bash theme={null}
    codex mcp add ironrun -- ironrun mcp
    ```

    Or add it manually to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.ironrun]
    enabled = true
    command = "ironrun"
    args = ["mcp"]
    ```

    Then add a `CODEX.md` file in your project root to direct the agent:

    ```
    Use run_sealed for all commands that need credentials.
    Do not run printenv, cat .env, or echo $VAR.
    ```

    Codex treats `CODEX.md` the same way Claude Code treats `CLAUDE.md` — it reads it on startup and follows explicit directives.
  </Tab>
</Tabs>

## Trusted workspace session flow

For normal local development, ironrun uses **trusted workspace sessions** — a lightweight approval flow that lets you authorize an agent once and have it work freely for two hours.

<Steps>
  <Step title="Agent requests access">
    When the agent first calls `run_sealed` with an `argv` array (or explicitly calls `request_workspace_access`), ironrun blocks the command and posts a request to the global Inbox.
  </Step>

  <Step title="You review and approve">
    Open the ironrun TUI (`ironrun` or `ironrun tui`) and navigate to the Inbox tab. You'll see the agent's request — the project, environment, and reason. Press Enter to approve.
  </Step>

  <Step title="Agent works normally">
    The same MCP session can now run commands for the selected project and environment for **two hours** without further prompts.
  </Step>

  <Step title="Session expires or you revoke it">
    After two hours the session expires automatically. You can also revoke it immediately:

    ```bash theme={null}
    ironrun trust list
    ironrun trust revoke trust_abc123
    ```
  </Step>
</Steps>

Trusted sessions are pinned to the MCP session, project, and environment. A server restart creates a new session — an old grant does not carry over. `staging` and `prod` environments require a separate explicit grant from `dev`.

You can also pause, extend, or inspect sessions:

```bash theme={null}
ironrun trust list
ironrun trust grant req_abc123
ironrun trust pause trust_abc123
ironrun trust extend trust_abc123 --ttl 2h
ironrun trust revoke trust_abc123
```

## What if the agent ignores run\_sealed?

If the agent keeps running shell commands directly instead of using `run_sealed`, check the following:

* **`CLAUDE.md` / `CODEX.md` / `.cursorrules` exists** in the project root and contains a clear directive to use `run_sealed`.
* **The MCP server is connected** — confirm it in the agent's settings or run `ironrun mcp` manually to verify it starts without errors.
* **The directive is explicit** — vague instructions like "prefer ironrun" are less reliable than "Use run\_sealed for all commands that need credentials. Do not run printenv, cat .env, or echo \$VAR."

Running `ironrun setup` regenerates all three files if they are missing or incomplete.

<Warning>
  ironrun protects agent context, conversation logs, and routine command output — it prevents secrets from leaking into the agent's transcript and Claude Code's JSONL session files. However, a trusted agent session grants the agent the ability to run commands with network access. A trusted agent could still deliberately exfiltrate a secret through network or file actions if you allow it. ironrun is not an OS sandbox for a process you choose to trust.
</Warning>