Flowlib Docs

The MCP plugin exposes Flowlib as a Model Context Protocol server. AI assistants like Claude Desktop, VS Code Copilot, and Cursor can connect and manage flows, execute runs, debug failures, and more — all through natural language.

Installation

pnpm add @flowlib/mcp

npm install @flowlib/mcp

yarn add @flowlib/mcp

bun add @flowlib/mcp

Setup

flowlib.config.ts

import { mcp } from '@flowlib/mcp';

export const flowlibConfig = defineConfig({
  // ...
  plugins: [mcp()],
});

Options

Option	Type	Default	Description
`sessionTtlMs`	`number`	`1800000` (30 min)	How long idle MCP sessions stay alive.
`audit.enabled`	`boolean`	`true`	Log every tool invocation.
`audit.persist`	`boolean`	`false`	Persist audit logs to the database.
`audit.logLevel`	`'debug' \| 'info' \| 'warn'`	`'info'`	Minimum level for audit entries.

flowlib.config.ts

mcp({
  sessionTtlMs: 60 * 60 * 1000, // 1 hour sessions
  audit: { enabled: true, persist: true, logLevel: 'debug' },
});

Connecting an AI assistant

The MCP server runs over stdio via the CLI. Start your Flowlib app, then point your AI assistant at it.

Claude Desktop

Generate the config snippet and paste it into Claude Desktop's MCP settings:

npx flowlib-cli mcp --print-config

Output:

{
  "mcpServers": {
    "flowlib": {
      "command": "npx",
      "args": [
        "flowlib-cli",
        "mcp",
        "--url",
        "http://localhost:3000/flowlib",
        "--api-key",
        "YOUR_KEY"
      ]
    }
  }
}

VS Code (Copilot / Copilot Chat)

Add to your .vscode/mcp.json:

{
  "servers": {
    "flowlib": {
      "command": "npx",
      "args": [
        "flowlib-cli",
        "mcp",
        "--url",
        "http://localhost:3000/flowlib",
        "--api-key",
        "YOUR_KEY"
      ]
    }
  }
}

Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "flowlib": {
      "command": "npx",
      "args": [
        "flowlib-cli",
        "mcp",
        "--url",
        "http://localhost:3000/flowlib",
        "--api-key",
        "YOUR_KEY"
      ]
    }
  }
}

Manual

Run the server directly:

npx flowlib-cli mcp --url http://localhost:3000/flowlib --api-key YOUR_KEY

You can also use environment variables instead of flags:

export FLOWLIB_URL=http://localhost:3000/flowlib
export FLOWLIB_API_KEY=YOUR_KEY
npx flowlib-cli mcp

Available tools

Once connected, the AI assistant has access to the following tools:

Flow management

Tool	Description
`flow_list`	List all flows with names, IDs, and status.
`flow_get`	Get detailed metadata for a specific flow.
`flow_get_definition`	Get the full flow definition (nodes, edges, params).
`flow_create`	Create a new flow.
`flow_update`	Update a flow's definition or metadata.
`flow_delete`	Delete a flow.
`flow_validate`	Validate a flow definition for errors.

Version management

Tool	Description
`version_list`	List all versions of a flow.
`version_get`	Get a specific version's definition.
`version_publish`	Publish a new version of a flow.

Flow execution

Tool	Description
`run_start`	Start a flow run with inputs.
`run_to_node`	Run a flow up to a specific node (partial execution).
`run_list`	List recent flow runs.
`run_get`	Get details of a specific run.
`run_cancel`	Cancel a running flow.
`run_pause`	Pause a running flow.
`run_resume`	Resume a paused flow.

Debugging

Tool	Description
`debug_node_executions`	Get per-node execution traces for a run.
`debug_test_node`	Test a single node with custom input data.
`debug_test_expression`	Evaluate a template expression against test data.
`debug_test_mapper`	Test an input data mapper configuration.

Credentials & triggers

Tool	Description
`credential_list`	List available credentials.
`credential_test`	Test a credential's connectivity.
`trigger_list`	List triggers for a flow.
`trigger_get`	Get trigger details.
`trigger_create`	Create a new trigger.
`trigger_update`	Update an existing trigger.
`trigger_delete`	Delete a trigger.

Node reference

Tool	Description
`node_list_providers`	List all available node providers (core, gmail, slack, etc.).
`node_list_available`	List all available node types with their schemas.

Resources and prompts

The MCP server also exposes resources and prompts:

flowlib://flows/{flowId}/definition — Read a flow definition as a resource, useful for context injection.
debug-flow-run prompt — A guided prompt template that walks the AI through debugging a failed flow run step by step.

Architecture

The plugin supports two connection modes:

Stdio (CLI) — npx flowlib-cli mcp starts a standalone process that connects to Flowlib over HTTP. This is what MCP clients like Claude Desktop use.
Direct (in-process) — When registered as a plugin, the MCP server can call Flowlib services directly without HTTP overhead. Used by the Streamable HTTP endpoint at POST /plugins/mcp/mcp.

┌──────────────┐  stdio   ┌──────────────┐  HTTP  ┌────────────┐
│ Claude / VS  │ ───────► │ flowlib-cli   │ ─────► │  Flowlib    │
│ Code / Cursor│          │ mcp server   │        │  API       │
└──────────────┘          └──────────────┘        └────────────┘

┌──────────────┐  HTTP    ┌────────────────────────────────────┐
│  MCP Client  │ ───────► │  Flowlib (w/ mcpPlugin, direct)    │
└──────────────┘          └────────────────────────────────────┘

MCP (Model Context Protocol)