ironflow mcp

Start the Model Context Protocol (MCP) server for AI assistant integration.

ironflow mcp [flags]

AI assistants like Claude Code, Cursor, and Windsurf can use this to interact with your Ironflow server directly from the IDE. The MCP server runs on stdio by default. Supervisors can opt into authenticated streamable HTTP on a loopback address; HTTP mode requires IRONFLOW_MCP_BEARER_TOKEN and refuses non-loopback Host and Origin headers. With IRONFLOW_MCP_EXIT_ON_STDIN_CLOSE=1 it exits when its stdin closes.

By default, 27 read tools are registered, including ironflow_get_docs. --allow-writes adds 16 write tools (emit events, invoke functions, cancel/delete/resume runs, append entity events, delete entity streams, redact event, run and step payloads, set secrets and KV keys, requeue or discard outbox DLQ entries, rebuild projections, reset circuit breakers), for 43 core tools. Combining --allow-writes with --evidence-file registers one more, ironflow_await_reload, for 44. With --allow-writes, application tools the SDK registered with the server are also exposed dynamically, unless --static-only is passed. Read-only mode never exposes them. Desktop’s terminal bridge tools are optional extras outside the core counts.

Three documentation resources are available in every mode, including --static-only:

Resource URI	MIME type	ironflow_get_docs topic	Source
ironflow://docs/openapi	application/json	openapi	Configured engine’s authenticated GET /api/v1/openapi.json
ironflow://docs/push-protocol	text/markdown	push-protocol	Bundled push wire protocol
ironflow://docs/function-authoring	text/markdown	function-authoring	Bundled SDKless handler guide

OpenAPI describes REST only and excludes ConnectRPC methods and push callbacks; it is not the complete Ironflow API contract. Each read fetches it from the configured engine using the configured API key. The Markdown guides ship with the MCP binary and work offline; they may differ from the engine’s version or current website. ironflow_get_docs requires one of the three topics above and returns a source note followed by the full document. See the MCP guide for retrieval examples.

Five resource templates (ironflow://runs/{run_id}, ironflow://runs/{run_id}/steps, ironflow://functions/{function_id}, ironflow://streams/{entity_id}, ironflow://projections/{name}) read one record each, in every mode.

The six irreversible tools ask the user to confirm through elicitation when the client supports it, and otherwise need confirm: true. See Confirming irreversible operations.

Flags:

Flag	Type	Default	Description
--server-url	string		Ironflow server URL (default: IRONFLOW_SERVER_URL or http://localhost:9123). When IRONFLOW_SERVER_URL and IRONFLOW_API_KEY are both unset, the URL that ironflow serve wrote to the nearest .ironflow/engine.json replaces that default
--api-key	string		API key for authentication. Prefer IRONFLOW_API_KEY: a flag value is visible in the process list. Without the flag, IRONFLOW_API_KEY is used. When that and IRONFLOW_SERVER_URL are both unset, the key in the nearest .ironflow/engine.json is used
--allow-writes	bool	false	Enable write operations (emit events, invoke functions) and SDK-registered application tools
--evidence-file	string		Append a JSONL trail of every tool call and resource read, with credentials masked; with --allow-writes it also registers ironflow_await_reload
--transport	string	stdio	MCP transport: stdio or streamable-http
--host	string	127.0.0.1	Loopback host for streamable HTTP
--port	int	0	HTTP port; 0 lets the OS choose
--port-file	string		Write bound HTTP port as mode-0600 JSON {"http_port":N}
--static-only	bool	false	Exclude SDK-registered application tools (read-only mode never registers them)
--terminal-bridge-url	string		Loopback URL of Ironflow Desktop’s terminal bridge. Adds ironflow_terminal_run and ironflow_terminal_read; needs --allow-writes and IRONFLOW_TERMINAL_BRIDGE_TOKEN. Set by Desktop, not meant for hand use

Examples:

# Start read-only MCP server
ironflow mcp

# Start with write access
ironflow mcp --allow-writes

# Custom server URL, API key from the environment
IRONFLOW_API_KEY=ifkey_... ironflow mcp --server-url http://prod:9123

# Record a tool-call evidence trail
ironflow mcp --allow-writes --evidence-file /path/to/agent-evidence.jsonl

# Authenticated, static-only loopback HTTP on an ephemeral port
IRONFLOW_MCP_BEARER_TOKEN=... ironflow mcp --transport=streamable-http \
  --host=127.0.0.1 --port=0 --port-file=/path/to/mcp-port.json --static-only

---