Remote MCP

A hosted AI agent has no local ironflow binary, so it cannot run ironflow mcp. The engine can serve MCP itself. The agent connects over HTTP and sends its own API key. Every tool call runs with the permissions of that key.

Remote MCP is off by default. It opens a new network endpoint, so turn it on only when you need it.

Enable it

With a config file, set spec.mcp.remote:

apiVersion: ironflow/v1
kind: Server
spec:
  mcp:
    remote: true

Without a config file, set the environment variable before ironflow serve:

IRONFLOW_MCP_REMOTE=true ironflow serve

IRONFLOW_MCP_REMOTE is not read when you use -f. serve logs a warning if you set it there.

The endpoint is https://<engine>/api/v1/mcp. The transport is streamable HTTP.

Connect an agent

Create a key for the agent first. Give it the least role it needs:

• viewer for read-only work. Write tools return a permission error.
• developer when the agent must emit events, invoke functions or change state.

Then point the MCP client at the endpoint with the key in the Authorization header:

{
  "mcpServers": {
    "ironflow": {
      "type": "http",
      "url": "https://ironflow.example.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer ${IRONFLOW_API_KEY}" }
    }
  }
}

How authority works

The engine does not hold a key for the agent. For each tool call, it calls its own API with the Authorization header the agent sent. The normal checks run on that call: authentication, role permissions, and deny policies when you enforce them. A viewer key that calls ironflow_emit_event gets a permission_denied tool error from the engine.

A request with no Authorization: Bearer header gets 401. Cookies and ?token= do not work on this route.

The role needs the mcp:use action to reach the endpoint. The built-in admin, developer and viewer roles have it. Custom roles need it added.

Destructive tools

Six tools delete or redact data permanently. See Confirming irreversible operations. Remote MCP keeps no session between requests. A client on protocol version 2026-07-28 or later can still be asked to confirm, because that protocol needs no session. An older client cannot be asked, so these tools need confirm: true. The agent should set it only after the user agrees.

In a multi-node cluster, a confirmation retry can reach a different node than the first request. That node asks again.

What is not available

These tools exist only in a local ironflow mcp process, and remote MCP does not serve them:

• Terminal tools (ironflow_terminal_*)
• The evidence trail
• ironflow_await_reload
• Dynamic agent tools that SDK clients register

OAuth is not supported. Use an API key as a bearer token.

Network security

The endpoint sends API keys. Put TLS in front of the engine for any address that is not localhost. Use a reverse proxy or load balancer that ends TLS and forwards to the engine. The proxy must pass the Authorization header through unchanged.

Dev mode refuses remote MCP. In dev mode the engine accepts any bearer token, so a key would not limit what the agent can do. ironflow serve exits with an error if spec.mcp.remote and dev mode are both on.

Each tool call reaches the engine from the engine itself. The audit trail records the loopback address as the source, not the agent’s address. To tell agents apart, give each one its own key.

Limits: a request body can be at most 4 MiB. The endpoint has no server-sent event stream, so a GET returns 405.

Rotate the agent’s key with ironflow apikey rotate if it leaks. Set an expiry when you create it.