# MCP (Model Context Protocol) (/docs/plugins/mcp)





The MCP plugin exposes Flowlib as a [Model Context Protocol](https://modelcontextprotocol.io) 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 [#installation]

<Tabs items="['pnpm', 'npm', 'yarn', 'bun']">
  <Tab value="pnpm">
    ```bash
    pnpm add @flowlib/mcp
    ```
  </Tab>

  <Tab value="npm">
    ```bash
    npm install @flowlib/mcp
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add @flowlib/mcp
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add @flowlib/mcp
    ```
  </Tab>
</Tabs>

## Setup [#setup]

Register the plugin in your Flowlib config:

```ts title="flowlib.config.ts"
import { mcp } from '@flowlib/mcp';

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

### Options [#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.       |

```ts title="flowlib.config.ts"
mcp({
  sessionTtlMs: 60 * 60 * 1000, // 1 hour sessions
  audit: { enabled: true, persist: true, logLevel: 'debug' },
});
```

## Connecting an AI assistant [#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 [#claude-desktop]

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

```bash
npx flowlib-cli mcp --print-config
```

Output:

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

### VS Code (Copilot / Copilot Chat) [#vs-code-copilot--copilot-chat]

Add to your `.vscode/mcp.json`:

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

### Cursor [#cursor]

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

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

### Manual [#manual]

Run the server directly:

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

You can also use environment variables instead of flags:

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

## Available tools [#available-tools]

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

### Flow management [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#architecture]

The plugin supports two connection modes:

1. **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.
2. **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)    │
└──────────────┘          └────────────────────────────────────┘
```