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

# ironrun MCP Server: Value-Blind Tools for AI Agents

> ironrun exposes MCP tools so AI agents can run commands and use secrets without receiving raw values. Start the server with ironrun mcp.

ironrun acts as an MCP (Model Context Protocol) server. When you run `ironrun mcp`, it exposes a set of tools that AI agents — Claude Code, Cursor, Codex, and others — can call to run commands and interact with secrets. The key design constraint is that none of these tools ever return a raw secret value. Secrets flow into child processes, and anything that looks like a secret in the output is replaced with `[REDACTED]` before the agent sees it.

## Starting the server

```bash theme={null}
ironrun mcp
```

In practice you configure this once in `.mcp.json` so the agent host starts it automatically. `ironrun setup` writes that file for you.

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

## Available tools

Every tool the server exposes is value-blind by design: none of them accept a plaintext secret value as a parameter, and none of them return one.

| Tool                       | Description                                                                            |
| -------------------------- | -------------------------------------------------------------------------------------- |
| `list_commands`            | List all command IDs and their argv from the current policy                            |
| `run_sealed`               | Execute a command by ID or arbitrary argv (in a trusted workspace session)             |
| `request_workspace_access` | Ask the human to grant a trusted development session for this project                  |
| `workspace_status`         | Get value-blind project name, active environment, entry names, and session trust state |
| `validate_policy`          | Check that the policy file is well-formed and return a provider and command count      |
| `propose_command`          | Stage a new command for human review; it is not executed until a human approves it     |
| `request_secret`           | Ask the human to configure a named secret through the local masked prompt              |
| `claim_capsule`            | Decrypt and locally store a secret delivered as an encrypted `ir1.` capsule            |
| `list_environments`        | List environment names, active state, expiry, and configured entry counts              |
| `request_lease`            | Request temporary permission to run specific policy commands (lease-based strict mode) |
| `lease_status`             | List this session's leases, scopes, and expiry                                         |
| `revoke_own_lease`         | Voluntarily surrender a lease before it expires                                        |

## Audit session

When the MCP server starts, it opens one audit log session. Every `run_sealed` call from the same agent session shares a session ID in the audit log, so you can trace all commands back to a single agent interaction.

```bash theme={null}
ironrun audit verify   # confirm the log hasn't been tampered with
```

## Key principle

None of these tools ever return a secret value. If you review the source at `mcp/server.go`, you'll see there is no code path that reads a secret and returns it to the caller. The agent gets back exit codes, durations, and redacted output — nothing else.

<CardGroup cols={2}>
  <Card title="run_sealed" icon="play" href="/mcp/run-sealed">
    Execute commands with secrets injected below agent visibility
  </Card>

  <Card title="Workspace Access" icon="shield-check" href="/mcp/workspace-access">
    Request and check trusted development session status
  </Card>

  <Card title="propose_command" icon="lightbulb" href="/mcp/propose-command">
    Let agents suggest new policy commands for human review
  </Card>

  <Card title="Agent Setup Guide" icon="robot" href="/guides/agent-setup">
    Configure Claude Code, Cursor, and Codex to use ironrun
  </Card>
</CardGroup>