Configure ironrun MCP for Claude Code, Cursor, Codex

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

Claude Code
Cursor
Codex

The fastest path is ironrun setup, which auto-creates both .mcp.json and CLAUDE.md in your project root. Run it once per project:

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:

{
  "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.

Cursor reads a global MCP config from ~/.cursor/mcp.json. Add the ironrun server there (merge with any existing entries — do not replace them):

{
  "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.

Add ironrun to Codex’s MCP server list with a single command:

codex mcp add ironrun -- ironrun mcp

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

[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.

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.

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.

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.

Agent works normally

The same MCP session can now run commands for the selected project and environment for two hours without further prompts.

Session expires or you revoke it

After two hours the session expires automatically. You can also revoke it immediately:

ironrun trust list
ironrun trust revoke trust_abc123

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:

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.

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.

Get Started

Core Concepts

Guides

CLI Reference

MCP Tools

Troubleshooting

Configure ironrun MCP for Claude Code, Cursor, Codex

How it works

Setting up your agent

Trusted workspace session flow

What if the agent ignores run_sealed?

​How it works

​Setting up your agent

​Trusted workspace session flow

​What if the agent ignores run_sealed?

How it works

Setting up your agent

Trusted workspace session flow

What if the agent ignores run_sealed?