@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 an MCP Token

1. Go to flowdot.ai
2. Navigate to Settings > MCP Tokens
3. Click Create New Token
4. Select the scopes you need (see Token Scopes below)
5. Copy the token (starts with fd_mcp_)

2. Configure Claude Desktop

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

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

3. Restart Claude Desktop

After adding the configuration, restart Claude Desktop to load the MCP server.

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)

npx @flowdot.ai/mcp-server

Or install globally:

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_input_presets — Pre-configured input sets for a workflow
• get_input_preset — Specific preset with all values
• create_input_preset — Create a shareable preset
• update_input_preset — Update preset description/values
• delete_input_preset — Delete a preset
• vote_input_preset — Vote on a preset
• toggle_community_inputs — Enable/disable community inputs for a workflow

Teams (1)

• list_user_teams — List all teams the user belongs to (with role + member count)

Knowledge Base / RAG (14)

• list_knowledge_categories — Document categories in your knowledge base
• create_knowledge_category — New category with name, description, color
• update_knowledge_category — Update category properties
• delete_knowledge_category — Delete a category (documents become uncategorized)
• list_knowledge_documents — Documents with category/team/status filters
• get_knowledge_document — Document details by ID/hash
• upload_text_document — Upload text content directly
• upload_document_from_url — Download and add a document from a URL
• move_document_to_category — Move a document or make it uncategorized
• transfer_document_ownership — Transfer between personal and team knowledge base
• reprocess_document — Reprocess a failed/stuck document
• delete_knowledge_document — Permanently delete a document
• query_knowledge_base — Semantic + keyword RAG search
• get_knowledge_storage — Storage usage and limits

Agent Toolkits (24)

Agent Toolkits let an AI client create new tools through the MCP interface — effectively MCP within MCP. Once installed, toolkit tools become callable via invoke_toolkit_tool.

Toolkit Management (12)

• list_agent_toolkits — Your toolkits
• search_agent_toolkits — Search public toolkit marketplace
• get_agent_toolkit — Toolkit details (tools, credentials, metadata)
• get_toolkit_comments — Comments on a toolkit
• create_agent_toolkit — Create a new toolkit with credential requirements
• update_agent_toolkit — Update title, description, category, credentials
• delete_agent_toolkit — Delete a toolkit
• copy_agent_toolkit — Create a private copy of a public toolkit
• toggle_toolkit_visibility — Change visibility (private/public/unlisted)
• vote_toolkit — Vote on a toolkit
• favorite_toolkit — Add/remove from favorites
• add_toolkit_comment — Add comment to a toolkit

Toolkit Usage & Invocation (12)

• install_toolkit — Install a toolkit on your account
• uninstall_toolkit — Uninstall
• list_installed_toolkits — Installed toolkits with credential status
• toggle_toolkit_active — Enable/disable an installation
• check_toolkit_credentials — Show which credentials are missing
• update_toolkit_installation — Map toolkit credentials to your API keys
• invoke_toolkit_tool — Execute a tool from an installed toolkit
• list_toolkit_tools — All tools in a toolkit
• get_toolkit_tool — Tool details with input/output schemas
• create_toolkit_tool — Create an HTTP- or Workflow-backed tool inside a toolkit
• update_toolkit_tool — Update tool configuration, schema, endpoint
• delete_toolkit_tool — Delete a tool from a toolkit

Credential types supported: api_key, oauth (with PKCE + scopes + refresh tokens), bearer, basic, custom Tool types supported: http (REST API), workflow (invoke a FlowDot workflow)

Agent Recipes (19)

Recipes are reusable agentic programs with multiple step types and persistent stores. MCP can DESIGN recipes; only the CLI can RUN them.

Recipe Core (8)

• list_recipes — List recipes (with favorites_only filter)
• get_recipe — Recipe details with steps, stores, metadata
• get_recipe_definition — Full recipe in YAML or JSON format
• browse_recipes — Public recipe browsing with pagination/sorting
• create_recipe — Create a new agent recipe
• update_recipe — Update metadata and entry_step_id (critical for execution)
• delete_recipe — Delete a recipe
• fork_recipe — Create a private copy of a public recipe

Step Management (4)

• list_recipe_steps — All steps with types, connections, config
• add_recipe_step — Add step (agent, parallel, loop, gate, branch, invoke)
• update_recipe_step — Update step name, description, config, connections
• delete_recipe_step — Delete a step

Store Management (4)

• list_recipe_stores — Stores (variables) in a recipe
• add_recipe_store — Add a store for data flow between steps
• update_recipe_store — Update key, label, type, default, I/O flags
• delete_recipe_store — Delete a store

Engagement (3)

• link_recipe — Link recipe for CLI execution with an alias
• vote_recipe — Vote on a public recipe
• favorite_recipe — Add/remove from favorites

Step types: agent (LLM with tools), parallel (concurrent), loop (iterate array), gate (approval checkpoint), branch (conditional), invoke (subroutine), output (emit coloured message to terminal)

Output step config: message — template string (supports {{stores.x}} interpolation), color — green | red | yellow (default green). Executes instantly with no LLM call. Use it to emit progress updates, warnings, or final summaries during long-running recipes.

To execute a recipe, use the FlowDot CLI:

npx @flowdot.ai/cli recipes run <aliasOrHash> --input '{"key":"value"}'

Agent Characters (8)

Voice-call personas — name + persona prompt + complete provider stack (TTS / STT / LLM). The Hub server-side validates voice-config completeness against the same App\Support\AgentCharacterCompleteness helper the runtime uses, so every read of a character carries an is_complete flag plus a missing_fields[] list. Read learn://characters for the per-provider settings shapes.

• list_agent_characters — List your characters with completeness badges
• get_agent_character — Full detail with per-field Completeness section
• create_agent_character — Create a new character (rejects with CHARACTER_VOICE_CONFIG_INCOMPLETE 422 if any required field is missing)
• update_agent_character — Partial update with post-merge completeness validation
• delete_agent_character — Hard delete (requires confirm: true)
• fork_agent_character — Copy a public character; LLM choice resets to default
• duplicate_agent_character — Copy your own character including LLM choice
• toggle_agent_character_public — Flip public/private (auto-mints stable hash on first publish)

Required fields: voice_provider, voice_id, tts_model, voice_settings, stt_provider, stt_model, llm_provider, llm_model, llm_temperature, personality_prompt. See learn://characters for recommended values per provider.

Token Scopes

When creating an MCP token in FlowDot Settings, you can select exactly which scopes to grant. Restrict tokens to the minimum scope they need:

| Scope namespace | Tools it covers | |---|---| | workflows:read | List, search, get, view public workflows | | workflows:execute | Execute workflows | | workflows:manage | Create, update, delete, validate, build workflow graphs | | executions:read | Status, history, stream | | executions:manage | Cancel, retry | | agent:chat | Agent chat | | custom_nodes:read | List, search, get, get template | | custom_nodes:manage | Create, update, delete, copy, toggle visibility, vote, comment | | apps:read | List, search, get apps and files | | apps:manage | Create, update, delete, publish, code editing, file management | | recipes:read | List, get, browse, get definition | | recipes:manage | Create, update, delete, fork, link, manage steps and stores | | agent_characters:read | List and view agent characters (with completeness state) | | agent_characters:manage | Create, edit, delete, fork, duplicate, and publish agent characters | | knowledge:read | List, get, query | | knowledge:manage | Upload, delete, categorize, transfer, reprocess | | agent_toolkits:read | List, search, get toolkits and tools | | agent_toolkits:manage | Create, update, delete, install, invoke | | sharing:read | Get shared results, public URLs | | sharing:manage | Create shared results, vote, comment | | input_presets:read | List, get presets | | input_presets:manage | Create, update, delete | | teams:read | List teams | | discovery:read | Search, tags, public browsing | | analytics:read | Metrics, comments, history |

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | FLOWDOT_API_TOKEN | Yes | — | Your MCP token (must start with fd_mcp_) | | FLOWDOT_HUB_URL | No | https://flowdot.ai | FlowDot Hub URL (override for self-hosted) | | INTERNAL_API_SECRET | No | — | Optional shared secret for internal API calls |

Configuring Other MCP Clients

Cursor

Settings > MCP Servers > Add Server:

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

Windsurf

Same configuration as Cursor — see the Windsurf documentation for the exact location of the MCP config file.

Claude Code

Add to your Claude Code MCP configuration (typically ~/.config/claude-code/mcp.json):

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

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
FLOWDOT_API_TOKEN=fd_mcp_xxx npm start

# Watch mode
npm run dev

# Run tests
npm test

# Coverage report
npm run test:coverage

# Build the .mcpb Claude Desktop extension bundle
npm run build:mcpb

Architecture

The MCP server is a thin protocol adapter. All HTTP communication with the FlowDot Hub is delegated to a shared @flowdot.ai/api package, which is also used by the FlowDot CLI and daemon. This means the same client logic, authentication, retry semantics, and pagination apply across every FlowDot surface.

Source Layout

mcp-server/
├── bin/
│   └── flowdot-mcp.js          # Executable wrapper
├── src/
│   ├── index.ts                # Entry point
│   ├── server.ts               # createServer() / startServer()
│   ├── api-client.ts           # FlowDotApiClient re-export
│   ├── tools/
│   │   ├── index.ts            # Central registry (one switch case per tool)
│   │   └── *.ts                # 119 individual tool source files
│   └── utils/
│       └── script-validator.ts # AST-based custom node script validation
├── manifest.json               # MCPB Claude Desktop bundle manifest
├── scripts/
│   └── build-mcpb.js           # Builds the .mcpb extension archive
└── package.json

Custom Node Script Validation

User-submitted custom node JavaScript is validated using acorn AST parsing, not regex. The validator checks:

• Syntax correctness
• Required processData(inputs, properties, llm) function exists
• Return statement exists and matches declared output keys exactly
• No top-level return statements
• Security patterns (no eval, process, global, require, etc.)
• Best practices (unused inputs, unhandled errors)

The script validator has its own test suite with 100% coverage thresholds enforced via vitest.config.ts.

License

See LICENSE.