# Floom MCP server

> Deploy and supervise background AI workers that run on schedules, webhooks, or manual triggers with full audit logs and human-in-the-loop approvals.

- Repository: https://github.com/floomhq/floom
- Page: https://hostedmcp.org/servers/floomhq/floom
- Transport: stdio
- Stars: 47
- License: MIT
- Latest version: 0.1.6

## Install

### Claude Code

```sh
claude mcp add --env 'FLOOM_API_KEY=<YOUR_FLOOM_API_KEY>' --env 'FLOOM_BASE_URL=<FLOOM_BASE_URL>' floom -- npx -y @floomhq/mcp-server
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "floom": {
      "command": "npx",
      "args": [
        "-y",
        "@floomhq/mcp-server"
      ],
      "env": {
        "FLOOM_API_KEY": "<YOUR_FLOOM_API_KEY>",
        "FLOOM_BASE_URL": "<FLOOM_BASE_URL>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "floom": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@floomhq/mcp-server"
      ],
      "env": {
        "FLOOM_API_KEY": "<YOUR_FLOOM_API_KEY>",
        "FLOOM_BASE_URL": "<FLOOM_BASE_URL>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"floom","type":"stdio","command":"npx","args":["-y","@floomhq/mcp-server"],"env":{"FLOOM_API_KEY":"<YOUR_FLOOM_API_KEY>","FLOOM_BASE_URL":"<FLOOM_BASE_URL>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "floom": {
      "command": "npx",
      "args": [
        "-y",
        "@floomhq/mcp-server"
      ],
      "env": {
        "FLOOM_API_KEY": "<YOUR_FLOOM_API_KEY>",
        "FLOOM_BASE_URL": "<FLOOM_BASE_URL>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add floom --env 'FLOOM_API_KEY=<YOUR_FLOOM_API_KEY>' --env 'FLOOM_BASE_URL=<FLOOM_BASE_URL>' -- npx -y @floomhq/mcp-server
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.floom]
command = "npx"
args = ["-y", "@floomhq/mcp-server"]

[mcp_servers.floom.env]
FLOOM_API_KEY = "<YOUR_FLOOM_API_KEY>"
FLOOM_BASE_URL = "<FLOOM_BASE_URL>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'FLOOM_API_KEY=<YOUR_FLOOM_API_KEY>' -e 'FLOOM_BASE_URL=<FLOOM_BASE_URL>' floom npx -- -y @floomhq/mcp-server
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "floom": {
      "command": "npx",
      "args": [
        "-y",
        "@floomhq/mcp-server"
      ],
      "env": {
        "FLOOM_API_KEY": "<YOUR_FLOOM_API_KEY>",
        "FLOOM_BASE_URL": "<FLOOM_BASE_URL>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `FLOOM_API_KEY` | yes | yes | API key for authenticating with Floom |
| `FLOOM_BASE_URL` | yes | no | Base URL of the Floom control plane |

## Tools (32)

- `deploy`: Deploy Python code to Floom and get a usable URL. Accepts raw Python source or a base64-encoded ZIP. Optionally include a floom.yaml config to declare endpoint schemas, secrets, and resource requirements.
- `run`: Execute an action on a deployed Floom app. Preferred: use app_slug + action for simple invocation. Alternative: use project_id + endpoint_id + version_id for explicit control.
- `list_projects`: List all deployed Floom projects.
- `get_project`: Get details for a Floom project including endpoint schemas and input parameters. Use this before calling run to see what inputs an endpoint expects.
- `manage_secrets`: Manage secrets for a Floom project. Supports list, set, and delete operations.
- `get_logs`: Get recent run logs for a Floom project.
- `list_versions`: List all versions of a Floom project. Shows which version is dev (latest deploy) and which is prod (promoted).
- `promote`: Promote a version to production. By default promotes the current dev version. Runs a health check; auto-rolls back if the check fails.
- `rollback`: Rollback production to a previous version.
- `storage_set`: Store a persistent key-value pair for a Floom project. Values persist across runs and deploys.
- `storage_get`: Retrieve a stored value for a Floom project.
- `storage_delete`: Delete a stored value for a Floom project.
- `storage_list`: List all stored keys for a Floom project with usage info.
- `create_share_link`: Create a public share link for a Floom endpoint. Share links allow anyone to run the endpoint without authentication.
- `list_share_links`: List all share links for a Floom project.
- `disable_share_link`: Disable a share link for a Floom project. The link will no longer be accessible.
- `fetch_context`: Fetch external data from a URL and attach it as context to a Floom project. Context data enhances AI-powered endpoints.
- `list_contexts`: List all context entries for a Floom project.
- `delete_context`: Remove a context entry from a Floom project.
- `delete_project`: Delete a Floom project and all its data (versions, runs, secrets, storage).
- `update_project`: Update a Floom project name or slug.
- `deploy_from_github`: Deploy a Floom app directly from a GitHub repository URL.
- `list_templates`: List available starter templates for Floom projects.
- `get_template`: Get details and code preview for a Floom starter template.
- `create_from_template`: Create a new Floom project from a starter template.
- `get_context`: Retrieve stored context data for a Floom project.
- `refresh_context`: Re-fetch context data from its source URL.
- `create_schedule`: Create a cron schedule that automatically runs an endpoint at specified intervals.
- `list_schedules`: List all cron schedules for a Floom project.
- `delete_schedule`: Delete a cron schedule from a Floom project.
- `enable_webhooks`: Enable public inbound webhooks for a Floom project. Once enabled, external services can trigger runs via POST /v1/webhooks/:slug/:action without authentication.
- `disable_webhooks`: Disable public inbound webhooks for a Floom project.

## FAQ

### What is Floom?

Floom is a loop engineering harness that provides a runtime for background AI workers to run without constant supervision.

### How are script workers isolated?

Script workers run in E2B sandbox microVMs, which provide an isolated filesystem, environment, and process to ensure security.

### Can I run workers on a schedule?

Yes, workers can be triggered manually, via a schedule (cron), webhooks, or Composio events.

### Does Floom charge per task?

No, Floom does not charge a per-task fee; you only pay for your E2B sandbox runtime and your model/API provider usage.
