Skip to content
OverviewAuthenticationCLIMCP serverworker.ymlREST API
MCP server

MCP server

Connect any MCP client and drive Floom with 15 default hosted tools.

Overview

Floom is a Model Context Protocol (MCP) server. Point any MCP client (Claude Code, Cursor, VS Code, Windsurf, Continue, or point Codex at the generated MCP config) at Floom and your assistant can run workers, read runs, edit the company brain, list connections, manage secret names, and ask the workspace agent for workspace-level help, all scoped to one workspace.

Hosted Floom Cloud exposes 15 default tools across 6 categories. This is the lean hosted surface an agent sees after floom mcp install. The broader engine/admin registry is not served by default. Secrets and tokens are automatically redacted from tool results.

Connect a client

The CLI writes the right config for your client. For hosted Floom Cloud, this is the whole setup: install opens login only when no valid credentials are saved, then writes the MCP config for your active workspace.

$ npx -y @floomhq/floom mcp install --target claude

For clients that take a raw URL, point them at your workspace endpoint with a token header (see below). Verify any time with floom mcp test.

Transport & auth

Floom Cloud serves MCP over HTTP JSON-RPC at a per-workspace endpoint. Authenticate with a Bearer token: a personal/workspace API token is ideal because, unlike a session JWT, it does not expire and suits static client config.

MCP client config (generic)
{
  "mcpServers": {
    "floom": {
      "url": "https://workeros-api.floom.dev/mcp/<workspace_id>",
      "headers": { "Authorization": "Bearer <floom_token>" }
    }
  }
}
  • Endpoint: POST https://workeros-api.floom.dev/mcp/{workspace_id}. The path’s workspace must match your token’s workspace.
  • Auth: Authorization: Bearer <token> (API token recommended; Supabase JWT also accepted).
  • Self-hosted: the OSS server runs over stdio (the floom-mcp binary) using x-floom-secret or x-floom-token.
Self-hosted is opt-in
Use WORKEROS_API_BASE, WORKEROS_API_SECRET, or floom login --local only when you are intentionally connecting to your own Floom API. Hosted Cloud does not require local.env provider keys or an E2B key.
Tip
floom mcp install fills in the URL, workspace, and token for you; reach for the raw config only when a client isn’t a supported target.

Tool reference

15 hosted default tools, grouped by category. Names are the registered tool names; some clients render dots as underscores when they namespace tools (e.g. workers.list → workers_list). Worker creation tools that accept worker_yml use the worker.yml file format.

Workspace agent · 1

Ask the workspace agent to inspect or operate the workspace.

ask_workspace_agentAsk the Floom workspace agent to inspect or operate workers, runs, approvals, brain packs, connections, and secret names.
messagestringrequired
Instruction or question for the workspace agent.
conversation_idstring
Optional stable client thread or chat id for continuity.

Workers · 5

Create, inspect, edit, and run workers.

workers.listList Floom workers.
include_systemboolean
Include system workers. Default: false.
include_archivedboolean
Include archived workers. Default: false.
workers.getGet a Floom worker by id.
idstringrequired
Worker id.
workers.createCreate a Floom worker from WorkerContract YAML and Python source.
worker_ymlstringrequired
WorkerContract YAML content.
run_pystringrequired
Python source for run.py.
skill_mdstring
Optional SKILL.md content.
workers.updateUpdate worker settings such as trigger, cron, defaults, and capabilities.
idstringrequired
Worker id.
trigger_typestring
manual | cron | webhook.
cron_exprstring
Cron expression for cron workers.
cron_timezonestring
IANA timezone for cron workers.
input_valuesobject
Saved default inputs.
capabilitiesobject
Capability/permission overrides.
webhook_secret_rotateboolean
Rotate the webhook secret.
workers.runStart a manual Floom worker run.
idstringrequired
Worker id.
inputsobject
Input values for the run. Default: {}.

Runs · 3

List runs, inspect them, and wait for completion.

runs.listList Floom runs, optionally filtered by worker id or status.
worker_idstring
Filter by worker.
statusstring
Filter by status.
limitnumber
Page size (1-200). Default: 50.
offsetnumber
Offset for pagination. Default: 0.
include_systemboolean
Include system runs. Default: false.
runs.getGet a run by id, including logs, outputs, artifacts, and approval status.
idstringrequired
Run id.
runs.watchPoll a run until terminal status or timeout.
idstringrequired
Run id.
timeout_msnumber
Max wait in ms (1000-30000). Default: 30000.

Secrets · 2

List secret names and update encrypted credentials.

secrets.listList configured secret names and status. Values are never returned.
No parameters.
secrets.setCreate or update a secret value.
keystringrequired
Secret name.
valuestringrequired
Secret value.

Connections · 1

List app and MCP connections available to the workspace.

connections.listList configured app and MCP connections.
No parameters.

Contexts (brain) · 3

Read and write the file packs workers draw on at run time.

contexts.listList Floom brain packs.
No parameters.
contexts.readRead a UTF-8 brain-pack file, or return metadata for binary files.
namestringrequired
Brain-pack name.
pathstringrequired
File path within the pack.
contexts.writeCreate or update a UTF-8 text file inside a brain pack.
namestringrequired
Brain-pack name.
pathstringrequired
File path.
contentstringrequired
File content.