Run the Ironflow Agent Against a Team Server

This page is for the person who sets up a shared Ironflow server for a team that uses the Ironflow agent in Zed or JetBrains. For local work with ironflow serve --dev, you do not need this page.

Server setup

The agent starts a local ironflow mcp process when ironflow is on the user’s PATH. If it is not, the agent uses the server’s remote MCP endpoint, /api/v1/mcp. Remote MCP is off by default, and the server refuses it in dev mode.

1. Start the server with remote MCP on. A machine with ironflow on its PATH does not need this: the local ironflow mcp process calls your server with the user’s key. With a config file, set spec.mcp.remote: true. Without one:

   IRONFLOW_MCP_REMOTE=true ironflow serve

2. Put TLS in front of the server for any address that is not localhost. The agent sends its API key on every request.

3. Create one API key for each person or each machine, so the audit trail can tell them apart:

   • viewer is enough for the read tools: functions, runs, steps, events, projections and entity streams. Workers and KV keys need developer.
   • developer is necessary if the agent must emit events, invoke functions, append to entity streams, resume runs or rebuild projections. The agent asks the user before each of these calls.

   A custom role needs the mcp:use action. Remote MCP has the details.

4. Give each user the key and the server URL. They set them in the agent’s env block:

   {
     "agent_servers": {
       "Ironflow": {
         "type": "custom",
         "command": "npx",
         "args": ["-y", "@ironflow/agent"],
         "env": {
           "IRONFLOW_SERVER_URL": "https://ironflow.example.com",
           "IRONFLOW_API_KEY": "ifkey_..."
         }
       }
     }
   }

The agent never offers the tools that delete runs, redact data, read secrets or run SQL, whatever role the key has. A shell command that the user approves can still call the ironflow CLI. The agent passes IRONFLOW_API_KEY on to shell commands, and the CLI reads it, so the key’s role is the real limit. Give the key the smallest role that does the job.

Keys and data

Item	Where it goes
Model key (BYOK)	~/.ironflow/agent/credentials.json with mode 0600, or an environment variable in the editor config. The agent refuses a credentials file that other users can read.
Prompts, the files the agent reads, tool output	Sent to the model provider of the key: Anthropic, OpenAI, Google or OpenRouter. Nothing goes to Ironflow.
Ironflow API key	Sent to your Ironflow server only. Shell commands that the user approves can read it, because the agent passes its environment on to them.
Session transcripts	~/.ironflow/agent/sessions/*.jsonl, in plain text, on the user’s machine. Deleted after 30 days (IRONFLOW_AGENT_SESSION_DAYS). logout --purge deletes all of them.
Agent runtime state	~/.ironflow/agent/flue.db, a SQLite file on the user’s machine. logout --purge deletes it.
Logs	stderr, shown in the editor’s agent log. No prompt text and no keys.

Set IRONFLOW_AGENT_HOME to move the key, the transcripts and flue.db to another folder.

Team rollout

• Pin the version. npx -y @ironflow/agent gets the latest version each time npx refreshes its cache. To keep the team on one version, pin it in the config: "args": ["-y", "@ironflow/agent@<version>"]. Move the pin when you have tried the new version.
• Global install. npm install -g @ironflow/agent installs the ironflow-agent command. Then set "command": "ironflow-agent" and "args": []. The team then updates when they run the install again.
• One model for the team. Set IRONFLOW_AGENT_MODEL, for example anthropic/claude-sonnet-5-5, so every user gets the same results.
• Proxy. IRONFLOW_AGENT_ANTHROPIC_BASE_URL sends Anthropic requests to another URL, for example a company proxy. With it set, only Anthropic is available. The agent has no base URL setting for the other providers.
• Platforms. macOS and Linux. On Windows, use WSL.

Troubleshooting

“Ironflow tools unavailable” in the first reply. The agent could not mount the MCP tools. It still works with the skills and the ironflow CLI. The rest of the line names the cause:

Message says	Fix
rejected the token	IRONFLOW_API_KEY is missing, wrong, expired, or its role has no mcp:use.
does not serve /api/v1/mcp	The server runs with --dev, or remote MCP is off. Start it with IRONFLOW_MCP_REMOTE=true and no --dev.
no server at	Nothing answers at IRONFLOW_SERVER_URL. Check the URL, the network path and TLS.

A tool call fails with a permission error. The key’s role does not allow the action. Use a developer key for calls that change the server.

The agent asks for every shell command. This is the design. Read-only commands inside the project run with no prompt. Any other command asks. “Allow this exact command this session” stops the prompts for one exact command text.

A turn hangs or ends with no answer. Open the editor’s agent log first. To look deeper, open flue.db read-only:

sqlite3 -readonly ~/.ironflow/agent/flue.db .tables

It holds the agent runtime’s state. Do not edit it while the agent runs.