@addai/flows-mcp

MCP (Model Context Protocol) server for +AI Flows. Gives AI assistants full control over your flows — create, edit, run, publish, and manage everything from Claude or any MCP-compatible client.

Quick Install

npx @addai/flows-mcp install

This will:

1. Ask for your API key (ait_... from Settings > API Keys)
2. Validate the key
3. Add the MCP server to your Claude configuration
4. Optionally start Claude

Manual Setup

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "addai-flows": {
      "command": "npx",
      "args": ["-y", "@addai/flows-mcp"],
      "env": {
        "ADDAI_API_KEY": "ait_your_key_here",
        "ADDAI_API_URL": "https://api.addai.com"
      }
    }
  }
}

For Claude Code, add to ~/.claude/settings.local.json:

{
  "mcpServers": {
    "addai-flows": {
      "command": "npx",
      "args": ["-y", "@addai/flows-mcp"],
      "env": {
        "ADDAI_API_KEY": "ait_your_key_here"
      }
    }
  }
}

Tools (46)

Flow Management

| Tool | Description | |------|-------------| | list_flows | List all flows in the workspace | | get_flow | Get a flow with full node/edge data | | create_flow | Create a new flow with trigger | | update_flow | Save flow state (full replace) | | delete_flow | Delete a flow | | duplicate_flow | Clone a flow | | validate_flow | Check for errors/warnings | | describe_flow | Compact graph summary with validation headline (token-efficient) |

Node Operations

| Tool | Description | |------|-------------| | add_nodes | Add nodes + edges (with temp_id system) | | update_node | Update a node's data or position | | remove_nodes | Remove nodes and connected edges | | connect_nodes | Add an edge between nodes | | disconnect_nodes | Remove an edge | | preview_flow | Dry-run add_nodes — validate changes without saving |

Publishing & Versions

| Tool | Description | |------|-------------| | publish_flow | Publish as production version | | list_versions | List save history | | list_publish_history | List published versions | | revert_to_version | Restore previous version | | create_version | Create named checkpoint |

Run Operations

| Tool | Description | |------|-------------| | run_flow | Start a production run | | list_runs | List runs (filterable) | | get_run | Get run details + outputs | | get_node_output | Full output for a node | | manage_run | Cancel/pause/unpause/delete | | list_node_logs | Execution log summary |

Folder Management

| Tool | Description | |------|-------------| | list_folders | List all folders | | create_folder | Create folder | | update_folder | Rename/recolor/move | | delete_folder | Delete folder | | move_flow_to_folder | Organize flows |

Variables

| Tool | Description | |------|-------------| | list_variables | List flow variables | | set_variable | Create/update variable | | delete_variable | Remove variable |

Split Tests (A/B)

| Tool | Description | |------|-------------| | get_split_test | Get active test | | create_split_test | Create A/B test | | start_split_test | Start routing traffic | | stop_split_test | Stop test | | declare_split_test_winner | Pick winner |

Review Tasks

| Tool | Description | |------|-------------| | list_review_tasks | List pending reviews | | respond_to_review | Approve/reject |

Stats

| Tool | Description | |------|-------------| | get_flow_stats | Flow stats over date range | | get_runs_stats | Aggregate run counts | | get_outcome_breakdown | Goal/exit breakdown |

Custom Nodes

| Tool | Description | |------|-------------| | list_custom_nodes | List workspace nodes | | create_custom_node | Create with code/schema | | update_custom_node | Update code/metadata | | publish_custom_node | Publish version |

Reference

| Tool | Description | |------|-------------| | list_node_types | All available node types | | get_node_type_info | Detailed node type config |

Reliability Features (v0.3+)

• Phased validation — validate_flow runs 7 phases: structure, nested IDs, shape (required fields + enum values), handles, references, syntax mixups, reachability. Each error includes node_id + path for precise fixes.
• Auto-heal — add_nodes and update_node inject missing UUIDs on conditions/cases/mappings/options/elements/abandonments/variants/fields. The response's _healed array lists what was patched.
• Dry-run — preview_flow simulates add_nodes in memory and returns the full validation report without saving.
• Enriched errors — API failures surface backend node_id + path + hint in the error message.

building-aiflows Skill

This package ships a Claude skill that encodes the correct authoring workflow. The installer (npx @addai/flows-mcp install) copies it to ~/.claude/skills/building-aiflows/. Start any flow-authoring session by invoking Skill("building-aiflows") to load the 11-step checklist, recipes, and anti-patterns.

Realtime Presence

When the MCP makes flow-modifying calls, the API key appears as a collaborator on the flow canvas — just like a teammate editing in realtime. The entity shows with a purple bot icon and the API key name, and disappears after 3 minutes of inactivity.

Adding Nodes Example

The add_nodes tool supports a temp_id system so you can reference new nodes in edges before they get real IDs:

add_nodes({
  flow_id: "abc-123",
  nodes: [
    { type: "httpRequest", temp_id: "req1", data: { label: "Fetch Users", url: "https://api.example.com/users", method: "GET" } },
    { type: "code", temp_id: "transform", data: { label: "Transform", code: "return { users: $input.data }" } }
  ],
  edges: [
    { source: "existing-trigger-id", target: "req1" },
    { source: "req1", target: "transform" }
  ]
})

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | ADDAI_API_KEY | Yes | — | Your ait_... API key | | ADDAI_API_URL | No | https://api.addai.com | API base URL | | ADDAI_PRESENCE_URL | No | Production URL | Presence heartbeat endpoint |

License

MIT