MCP Server

Ironflow includes a built-in Model Context Protocol (MCP) server. This lets AI assistants operate your Ironflow server directly from the IDE — list runs, inspect step outputs, emit events, query projections, and more.

Setup

Claude Code

Add to your project’s .mcp.json:

{
  "mcpServers": {
    "ironflow": {
      "command": "ironflow",
      "args": ["mcp", "--allow-writes"]
    }
  }
}

Cursor

Add to your MCP settings (Settings → MCP):

{
  "ironflow": {
    "command": "ironflow",
    "args": ["mcp", "--allow-writes"]
  }
}

Custom Server URL

If the Ironflow server is running on a different port or host:

{
  "mcpServers": {
    "ironflow": {
      "command": "ironflow",
      "args": ["mcp", "--allow-writes", "--server-url", "http://localhost:9000"]
    }
  }
}

Authentication

For servers with auth enabled, pass an API key:

{
  "mcpServers": {
    "ironflow": {
      "command": "ironflow",
      "args": ["mcp", "--allow-writes", "--api-key", "ifkey_your_api_key"]
    }
  }
}

Or set the IRONFLOW_API_KEY environment variable.

Read-Only vs Read-Write Mode

By default, the MCP server starts in read-only mode — only observation tools are available. Add --allow-writes to enable tools that modify state (emitting events, invoking functions, writing to KV store, etc.).

Available Tools

Read Tools (always available)

Tool	Description
ironflow_server_info	Server health and version
ironflow_overview	Dashboard stats: function count, active runs, workers, recent events
ironflow_list_functions	All registered functions
ironflow_get_function	Function details: triggers, concurrency, config
ironflow_list_runs	Recent workflow runs with status
ironflow_get_run	Detailed run info including step outputs
ironflow_get_run_steps	Step-by-step execution details
ironflow_list_events	Recent events
ironflow_list_projections	All projections (read models)
ironflow_projection_status	Specific projection state
ironflow_list_entity_streams	All entity streams
ironflow_read_entity_stream	Entity event history
ironflow_list_projects	Projects (organizational boundaries)
ironflow_list_environments	Environments (deployment targets)
ironflow_list_workers	Connected pull-mode workers
ironflow_kv_list_buckets	KV store buckets
ironflow_kv_list_keys	Keys in a KV bucket
ironflow_kv_get	Get a KV value
ironflow_list_secrets	Available secret names
ironflow_sql_query	Read-only SQL queries

Write Tools (requires --allow-writes)

Tool	Description
ironflow_emit_event	Emit an event (triggers matching functions)
ironflow_invoke_function	Directly invoke a function
ironflow_cancel_run	Cancel a running workflow
ironflow_retry_run	Retry a failed run from the last successful step
ironflow_append_entity_event	Append an event to an entity stream
ironflow_kv_put	Store a value in a KV bucket
ironflow_secret_set	Set a secret value

Example Workflows

Building an App with AI

With the MCP server configured, you can ask your AI assistant to:

1. “What functions are registered?” → calls ironflow_list_functions
2. “Emit an order.placed event” → calls ironflow_emit_event
3. “Show me what happened in that run” → calls ironflow_get_run + ironflow_get_run_steps
4. “What’s the current state of the order-stats projection?” → calls ironflow_projection_status
5. “Query the database for failed runs in the last hour” → calls ironflow_sql_query

Debugging a Failed Run

You: "List recent failed runs"
AI:  → ironflow_list_runs (filters for failed status)
     "Run run_abc123 failed at step 'charge-payment'"

You: "Show me what happened step by step"
AI:  → ironflow_get_run_steps(run_id: "run_abc123")
     "Step 1 (validate-order) succeeded with output {...}
      Step 2 (charge-payment) failed: 'Payment gateway timeout'"

You: "What event triggered this?"
AI:  → ironflow_list_events
     "Event order.placed with data {orderId: 'ord-456', total: 99.99}"

CLI Reference

ironflow mcp                              # Read-only mode
ironflow mcp --allow-writes               # Enable write operations
ironflow mcp --server-url http://host:port # Custom server URL
ironflow mcp --api-key ifkey_xxx           # API key authentication

Flag	Default	Description
--allow-writes	false	Enable write operations
--server-url	http://localhost:9123	Ironflow server URL
--api-key	""	API key (or set IRONFLOW_API_KEY)

Pair with AI Skills

The MCP server provides runtime tools (the agent’s “hands”), while AI Skills provide structured knowledge and workflows (the agent’s “brain”). The debug skill automatically uses MCP tools when available and falls back to CLI when not. For the best AI experience, use both.

Dynamic Agent Tools

In addition to the 27 static tools listed above, the MCP server automatically discovers and registers dynamic agent tools at startup. These are tools registered by SDK clients via the AgentToolsService/RegisterTool RPC on the running ironflow serve process.

• The MCP CLI calls ListTools at startup to fetch SDK-registered tools
• Each returned tool is registered as a dynamic MCP tool
• Invocations are forwarded to the Ironflow server via InvokeTool
• This is best-effort — if the server is unreachable, static tools still work
• Restart the MCP CLI to pick up newly registered agent tools (no live tools/list_changed push in v1)

This means your effective MCP tool count may be higher than the 27 static tools listed in the tables above.