floom — Claude Code MCP server for background AI workers
The floom MCP server connects an agent to a runtime for background AI workers: deploy, run, schedule and inspect every execution.
claude mcp add floom -e FLOOM_BASE_URL=<FLOOM_BASE_URL> -e FLOOM_API_KEY=<FLOOM_API_KEY> -- npx -y @floomhq/mcp-serverWhat floom does
Floom is a self-hosted runtime for background AI workers. A worker is a folder holding worker.yml plus either run.py for a script or SKILL.md for a plain-English agent. The manifest declares inputs, outputs, trigger, secrets and the tools that worker may call. Script workers execute inside E2B sandbox microVMs with an isolated filesystem, environment and process; platform secrets stay out of the sandbox.
Triggers cover manual runs, cron schedules, webhooks and Composio events. Each run keeps logs, outputs, tool calls and approval state, and you can open, replay or roll back it from the UI. The MCP server is how an agent reaches all of that. There is no per-task fee from Floom itself — you pay for E2B sandbox seconds and for your model provider.
You need FLOOM_BASE_URL and FLOOM_API_KEY before anything works. Point them at your own Floom instance. Agent-mode workers built on SKILL.md run inside the API process and are not microVM-isolated, so keep those bundles trusted.
What it helps with
- run a Python script on a cron schedule unattended
- expose one worker to a UI, REST and an agent at once
- restrict which tools an agent may call
- keep logs and output files for every run
- roll back a failed run and start it again
Example prompts for the agent
- List my floom workers and run
github-digest - Deploy the worker in
workers/my-worker - Show me the logs from the last
github-digestrun
How to install floom
Platform CLI
claude mcp add floom -e FLOOM_BASE_URL=<FLOOM_BASE_URL> -e FLOOM_API_KEY=<FLOOM_API_KEY> -- npx -y @floomhq/mcp-serverReplace <…> with your own values
Platform CLI
codex mcp add floom --env FLOOM_BASE_URL=<FLOOM_BASE_URL> --env FLOOM_API_KEY=<FLOOM_API_KEY> -- npx -y @floomhq/mcp-serverReplace <…> with your own values
Config file
{
"mcpServers": {
"floom": {
"command": "npx",
"args": [
"-y",
"@floomhq/mcp-server"
],
"env": {
"FLOOM_BASE_URL": "<FLOOM_BASE_URL>",
"FLOOM_API_KEY": "<FLOOM_API_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"floom": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@floomhq/mcp-server"
],
"env": {
"FLOOM_BASE_URL": "<FLOOM_BASE_URL>",
"FLOOM_API_KEY": "<FLOOM_API_KEY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e FLOOM_BASE_URL=<FLOOM_BASE_URL> -e FLOOM_API_KEY=<FLOOM_API_KEY> floom npx -y @floomhq/mcp-serverReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about floom
How do I install floom in Claude Code?
Run claude mcp add floom -e FLOOM_BASE_URL=<FLOOM_BASE_URL> -e FLOOM_API_KEY=<FLOOM_API_KEY> -- npx -y @floomhq/mcp-server. Fill in the address of your Floom instance and your API key.
What does floom do?
It is an MCP server in front of a runtime for background AI workers. An agent can deploy a worker from a folder, start it by hand or on a schedule, and read run history.
How is a script worker different from an agent worker?
A script (run.py, .sh, .js, .ts) runs in an E2B microVM with an isolated filesystem and process. A SKILL.md agent runs in the API process without that isolation.
