Connect an AI (MCP)

Every Nucleus serves the Model Context Protocol at /mcp. Point an AI client at that URL and it can do real work on your instance: search the node catalog, learn any node’s exact configuration contract, build and validate workflow graphs, save them, and test-run them — with a verifiable trace back.

Connecting is one step. With your Nucleus at http://localhost:48170:

Claude Code

claude mcp add --transport http flowdrome http://localhost:48170/mcp

Claude Desktop / claude.ai — Settings → Connectors → add custom connector → http://localhost:48170/mcp

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "flowdrome": { "url": "http://localhost:48170/mcp" }
  }
}

Then just ask:

“Create a workflow that runs every minute, gets the current time, and logs it to the console.”

The agent discovers everything else itself — the catalog, each node’s contract, the authoring guide — builds the graph, saves it (validated and auto-laid-out), test-runs it, and reports the result. The workflow lands in your Nucleus like anything you built by hand: open it in the Studio, edit it, deploy it to a host.

The tools

Tool	What it does
`list_node_types`	The node catalog — type, label, category, one-line description. Optional `query` filter.
`describe_node`	One node’s full contract: properties, defaults, ports, and its `configSchema` (the exact enums and required keys). Pass `config` to resolve config-dependent ports — a Switch’s rule ports, Execute Workflow’s parallel `w0/w1/…`, Merge’s `input1…N`, a routed trigger’s route ports.
`get_authoring_guide`	The authored guide: document format, envelope model, expressions, frames.
`list_workflows`	Stored workflows (id, name, version, updatedAt). Optional name filter.
`get_workflow`	One workflow document by id.
`validate_workflow`	Validate nodes + edges without saving — coded issues back.
`create_workflow`	Create a brand-new workflow from raw nodes + edges — for branching graphs. Never used for edits — that’s the surgical set below.
`create_chain_workflow`	The easy create: `name` + `steps` in order (types accept catalog labels like “HTTP Request”); the server resolves types, wires the sequence, validates and saves. `workflowId` builds INTO an open empty workflow instead.
`create_api_workflow`	The API builder: `name` + `endpoints` (`{ path, method?, body? }`) — one routed HTTP trigger, a response per route, and the result reports the real `/api/mock/<slug>` urls.
`update_workflow`	Replace a whole graph (big rewires). `baseVersion` turns concurrent human edits into an explicit conflict instead of a silent clobber; `force` overrides.
`update_node_config`	Surgical edit: patch one node’s config (and/or label) by id — change a message, URL, prompt or schedule without resending the graph.
`insert_node_between`	Surgical edit: splice a new node into an existing connection — “add a console log between these two nodes” is one call. The server finds the edge, rewires it through the new node, and saves.
`add_node`	Surgical edit: add one node, optionally auto-wired from/to existing nodes (`connectFromNodeId` / `connectToNodeId`).
`delete_node`	Surgical edit: remove one node and its edges; a single-in/single-out chain is healed (upstream re-connected to downstream).
`connect_nodes`	Surgical edit: draw one edge between two existing nodes (ports optional — defaults to `output` → `input`).
`disconnect_nodes`	Surgical edit: remove the connection(s) between two nodes; the nodes stay. Optional ports narrow the match.
`rename_workflow`	Surgical edit: rename the workflow itself (a node’s display name is `update_node_config` with `label`).
`test_workflow`	Run a saved workflow (or an inline doc) and get a verifiable trace: per-node status, which output ports actually fired, skipped branches, capped output previews, and the run’s console feed.

The surgical set exists so an AI never has to resend a whole graph to make a small change — each tool takes node references (an id, or a unique label — “Start” works as well as t), does the graph surgery server-side, validates and saves. A reference that doesn’t resolve fails the whole call with the node roster in the error, so nothing is ever half-applied, and every result carries a did field stating exactly what changed. Small local models handle these reliably; whole-graph composition is reserved for create_workflow / update_workflow.

Errors always come back as readable tool results — a bad graph returns the same coded issues the editor’s validation badges show, so the agent reads them and fixes its own graph.

Security model

Same machine: loopback connections need no token — the local dev loop just works.
Other machines: requests must carry a Nucleus token with Run capability (Authorization: Bearer …).
Off switch: Admin → AI · MCP (stored org-wide), or FLOWDROME_MCP_ENABLED=0 as a deployment pin the toggle cannot override.
The workflows implementing the endpoint ship locked (view-only) — an agent can read them but cannot modify the API it is standing on.

Clients without HTTP transport

A stdio relay ships with the platform for MCP clients that only spawn local processes:

node oss/apps/mcp-authoring/server.mjs --base http://localhost:48170

It is a dumb pipe — every JSON-RPC line from stdin is POSTed to /mcp verbatim and the reply goes to stdout. All behavior stays on the server.

Under the hood

/mcp contains no protocol logic at all — it forwards each JSON-RPC message to the MCP Server workflow, a canvas graph that parses the envelope, switches on the method, fans tools/call out to one node per tool, and calls the Authoring API workflow for the actual work. The entire AI integration is built out of the product’s own primitives — see The API is workflows.