mcp-server

# @flowdot.ai/mcp-server

Connect Claude Desktop, Cursor, Windsurf, Claude Code, and any other MCP-compatible AI client to the **entire FlowDot platform** — workflows, recipes, custom nodes, apps, knowledge bases, agent toolkits, and the full community/sharing layer.

## What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI models interact with external tools and services. The FlowDot MCP Server exposes **150 tools across 17 functional categories**, plus **8 educational `learn://` resources**, giving an AI client a complete operational interface to FlowDot — no web UI required.

With this server, an AI client can:

- **Build workflows from scratch** — create graphs, add nodes, wire connections, validate, execute, stream results
- **Author and share custom nodes** — write JavaScript components, validate them with AST parsing, publish to the community
- **Develop FlowDot Apps** — full React multi-file projects with surgical code editing operations
- **Design agent recipes** — multi-step agentic programs with stores, gates, branches, loops, parallel steps, and sub-recipes
- **Manage knowledge bases (RAG)** — categories, documents, uploads, semantic queries
- **Create and invoke agent toolkits** — define new tools, configure OAuth/API-key credentials, install, invoke
- **Set up agent characters for voice calls** — list/get/create/update/delete/fork/duplicate/publish, with server-side voice-config completeness validation
- **Share and discover** — public URLs, voting, comments, favorites, community browsing
- **Run and observe executions** — start, stream via SSE, cancel, retry, view history and metrics

> **Note:** Recipes can be **designed** through MCP but must be **executed** via the FlowDot CLI (`@flowdot.ai/cli`). Recipes are long-running agentic programs that exceed AI client timeouts and require local file/code/shell access.

## Quick Start

### 1. Get a free MCP Token

[Create a free FlowDot account](https://flowdot.ai/register?next=%2Fdashboard%3Fsettings%3Dmcp_tokens). You land on the **MCP Tokens** tab: click **Select all** (or pick scopes, see [Token Scopes](#token-scopes)), then **Create Token**. The token starts with `fd_mcp_`, and the page shows the ready-to-paste setup below with your token filled in.

The free plan includes 5 workflow runs a day and 10 toolkit calls a day. The Creator plan is $19 a month (500 runs a month, 200 toolkit calls a day). Details: [flowdot.ai/mcp](https://flowdot.ai/mcp).

### 2. Connect your client

**Claude Code** (one command):

```bash
claude mcp add flowdot -e FLOWDOT_API_TOKEN=fd_mcp_your_token_here -- npx -y @flowdot.ai/mcp-server
```

**Claude Desktop, Cursor and other clients:** add the block below to the client's config file.

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "flowdot": {
      "command": "npx",
      "args": ["-y", "@flowdot.ai/mcp-server"],
      "env": {
        "FLOWDOT_API_TOKEN": "fd_mcp_your_token_here"
      }
    }
  }
}
```

### 3. Restart the client

Restart Claude Desktop, Cursor or your MCP client so it loads the server. Claude Code picks it up on the next session.

## Installation Options

### Option A: Claude Desktop Extension (.mcpb)

Download the `.mcpb` extension bundle and double-click to install in Claude Desktop. The extension includes Node.js runtime and all dependencies — no separate installation needed.

### Option B: npm (Cursor, Claude Code, manual config)

```bash
npx @flowdot.ai/mcp-server
```

Or install globally:

```bash
npm install -g @flowdot.ai/mcp-server
flowdot-mcp
```

## Educational Resources (`learn://`)

The server exposes 8 standalone concept guides via the MCP `ReadResourceRequest` interface. Read these *before* invoking tools to scaffold your understanding:

| Resource | Content |
|----------|---------|
| `learn://overview` | FlowDot platform overview |
| `learn://workflows` | Workflow creation guide |
| `learn://recipes` | Agent recipe orchestration guide |
| `learn://custom-nodes` | Custom node development guide |
| `learn://apps` | App development guide |
| `learn://toolkits` | Agent toolkit guide |
| `learn://knowledge-base` | Knowledge base & RAG guide |
| `learn://characters` | Agent character (voice call) setup guide |

## Available Tools

The server exposes **150 tools** organized into 17 categories.

### Core (4)
- `list_workflows` — List all workflows accessible to the authenticated user
- `execute_workflow` — Execute a workflow with optional inputs (sync or async)
- `get_execution_status` — Get the status and results of a workflow execution
- `agent_chat` — Chat with the FlowDot AI agent for workflow assistance

### Analytics & Feedback (3)
- `get_workflow_metrics` — Impressions, success/failure rates, average duration
- `get_workflow_comments` — Comments and ratings on workflows
- `get_execution_history` — Past execution history with timestamps and status

### Workflow Management (5)
- `get_workflow_details` — Detailed workflow info including nodes, connections, signature
- `get_workflow_inputs_schema` — Input schema with expected types and required fields
- `duplicate_workflow` — Create a copy of an existing workflow
- `toggle_workflow_public` — Make a workflow public or private
- `favorite_workflow` — Add/remove workflow from favorites

### Execution Enhancements (3)
- `cancel_execution` — Cancel running/pending workflow executions
- `retry_execution` — Retry failed executions with the same inputs
- `stream_execution` — Real-time SSE streaming of workflow execution

### Discovery & Search (5)
- `get_workflow_tags` — Get tags associated with a workflow
- `set_workflow_tags` — Set/update workflow tags
- `search_workflows` — Search workflows by name, description, tags
- `search` — Unified search across workflows, apps, custom nodes
- `get_public_workflows` — Browse public workflows shared by other users

### Workflow Building (4)
- `create_workflow` — Create a new empty workflow
- `delete_workflow` — Permanently delete a workflow
- `get_workflow_graph` — Get complete graph structure (all nodes + connections)
- `validate_workflow` — Validate for missing connections, invalid config, disconnected nodes

### Node Operations (5)
- `list_available_nodes` — List all node types organized by category
- `get_node_schema` — Full schema for a node type (inputs, outputs, properties)
- `add_node` — Add new node (built-in or custom via `custom_node_{hash}`)
- `update_node` — Update node position or properties
- `delete_node` — Delete node and all its connections

### Connection Operations (3)
- `add_connection` — Connect a node output to a node input
- `delete_connection` — Remove a connection between two nodes
- `get_node_connections` — Get all connections to/from a specific node

### Custom Nodes (13)
- `list_custom_nodes` — List your custom nodes with search/category filtering
- `search_public_custom_nodes` — Search public nodes shared by the community
- `get_custom_node` — Detailed custom node info (inputs, outputs, script code)
- `get_custom_node_comments` — Comments and ratings on a custom node
- `get_custom_node_template` — Generate a working script template based on I/O definitions
- `create_custom_node` — Create new custom node with script, inputs, outputs (validated with AST parsing)
- `update_custom_node` — Update name, description, code, properties
- `delete_custom_node` — Permanently delete a custom node
- `copy_custom_node` — Copy a public node to your library
- `toggle_custom_node_visibility` — Change visibility (private/public/unlisted)
- `vote_custom_node` — Upvote/downvote/remove vote
- `favorite_custom_node` — Add/remove from favorites
- `add_custom_node_comment` — Add comment or reply

### Apps (23)

#### Core App Operations (12)
- `list_apps` — List your React frontend apps
- `search_apps` — Search the public app marketplace
- `get_app` — Detailed app info including React code and linked workflows
- `create_app` — Create a new React app (Tailwind + React 18, sandboxed)
- `update_app` — Update name, description, code, config, mobile settings
- `delete_app` — Permanently delete app
- `publish_app` — Publish to the public marketplace
- `unpublish_app` — Make a published app private
- `clone_app` — Clone a public app to your library
- `link_app_workflow` — Link a workflow to an app for `invokeWorkflow()` use
- `unlink_app_workflow` — Unlink a workflow from an app
- `link_app_toolkit` — Link a toolkit to an app for `invokeTool()` use
- `unlink_app_toolkit` — Unlink a toolkit from an app
- `get_app_template` — Get starter code templates (basic, chat, dashboard, form-builder, data-viewer)

#### Surgical Code Editing (4)
- `edit_app_code` — Find/replace specific strings in app code
- `append_app_code` — Append content before the closing brace
- `prepend_app_code` — Prepend content to the start
- `insert_app_code` — Insert content after a specific pattern match

#### Multi-File App Operations (7)
- `list_app_files` — List all files in a multi-file app
- `get_app_file` — Get content of a specific file
- `create_app_file` — Create new file (jsx, js, ts, tsx, css, json, md)
- `update_app_file` — Update file content and type
- `delete_app_file` — Delete a file
- `rename_app_file` — Rename or move a file
- `set_app_entry_file` — Set a file as the app's entry point

### Sharing & Public URLs (9)
- `get_workflow_public_url` — Public shareable URL for a workflow
- `list_shared_results` — Shared execution results for a workflow
- `get_shared_result` — Specific shared result with outputs/inputs
- `get_shared_result_comments` — Comments on a shared result
- `create_shared_result` — Create a shareable link (with optional expiry)
- `add_workflow_comment` — Comment on a workflow
- `add_shared_result_comment` — Comment on a shared result
- `vote_workflow` — Upvote/downvote a workflow
- `vote_shared_result` — Upvote/downvote a shared result

### Input Presets (7)
- `list