MCP Integration

Connect Backflow with Claude and other AI assistants using the Model Context Protocol.

Overview

Backflow provides two MCP components:

MCP Server - Exposes Backflow tools to AI assistants (Claude, etc.)
MCP Client - Connects to external MCP servers in workflows

Backflow MCP Server

Allow AI assistants to create integrations and routes for your tenants.

Setup with Claude Desktop

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

json

{
  "mcpServers": {
    "backflow": {
      "command": "node",
      "args": ["/path/to/backflow/dist/mcp.js"],
      "env": {
        "BACKFLOW_CONFIG_PATH": "/path/to/config.json",
        "BACKFLOW_INTEGRATIONS_PATH": "/path/to/integrations"
      }
    }
  }
}

Setup with Claude Code

bash

claude mcp add backflow node /path/to/backflow/dist/mcp.js

Remote Setup (API Mode)

Tenants can connect Claude to their Backflow instance remotely without installing the full server. This enables access to the complete set of Backflow tools — including workflows, apps, and entities — through an API key.

Method A: npx package (recommended)

The @backflow.mcp/client package runs a lightweight MCP bridge that connects to your Backflow instance over the API. No local server install required.

Claude Code:

bash

# Default endpoint (api.backflow.dev)
claude mcp add backflow -- npx -y @backflow.mcp/client --api-key YOUR_API_KEY

# Custom endpoint (self-hosted or dedicated instance)
claude mcp add backflow -- npx -y @backflow.mcp/client --api-key YOUR_API_KEY --endpoint https://your-instance.backflow.dev

Claude Desktop (claude_desktop_config.json):

json

{
  "mcpServers": {
    "backflow": {
      "command": "npx",
      "args": ["-y", "@backflow.mcp/client", "--api-key", "YOUR_API_KEY"]
    }
  }
}

Or using environment variables:

json

{
  "mcpServers": {
    "backflow": {
      "command": "npx",
      "args": ["-y", "@backflow.mcp/client"],
      "env": {
        "BACKFLOW_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

CLI flags:

Flag	Description
`--api-key`	API key for authentication (or use `BACKFLOW_API_KEY` env var)
`--endpoint`	Backflow API endpoint (default: `https://api.backflow.dev`)
`--scope`	Limit tool access to a specific tenant scope
`--allow-integrations`	Enable integration management tools
`--allow-routes`	Enable route management tools

Method B: SSE URL (for HTTP-native MCP clients)

If your MCP client supports HTTP-based transports, connect directly via Server-Sent Events — no local install needed.

SSE endpoint:

GET https://api.backflow.dev/mcp/sse?token=YOUR_API_KEY

Message endpoint:

POST https://api.backflow.dev/mcp/messages?sessionId=SESSION_ID
Authorization: Bearer YOUR_TOKEN

The SSE connection returns a sessionId on connect. Use that session ID when posting messages to the message endpoint.

Local vs Remote Comparison

	Local Mode	Remote (npx)	Remote (SSE)
Requires local install	Yes	No (npx)	No
Auth	Filesystem access	API key	API key / JWT
Integrations	Read/write files	Via API	Via API
Workflows	Not available	Full CRUD	Full CRUD
Apps	Not available	Full CRUD	Full CRUD
Entities	Not available	Full CRUD	Full CRUD

MCP Configuration

Create mcp-config.json:

json

{
  "enabled": true,
  "allowIntegrationCreation": true,
  "allowRouteCreation": true,
  "integrationsPath": "./integrations",
  "configPath": "./config.json",
  "autoReload": false
}

Available Tools

The MCP server exposes these tools to AI assistants. The tools available depend on your connection mode (see Local vs Remote Comparison above).

Integration Tools

Tool	Description
`create_integration`	Create a custom API integration with endpoints and auth config
`list_integrations`	List all custom integrations for the tenant
`get_integration`	Get full details of a specific integration by name
`update_integration`	Update an existing integration's config, endpoints, or auth
`delete_integration`	Delete a custom integration by name

Route Tools

Tool	Description
`create_route`	Create an API route that chains integration actions
`list_routes`	List all configured routes
`get_route`	Get details of a specific route by path and method
`update_route`	Update an existing route's config or integration actions
`delete_route`	Delete a route by path and method

Workflow Tools (remote only)

Tool	Description
`list_workflows`	List all workflows for the tenant
`get_workflow`	Get a workflow definition by ID
`create_workflow`	Create a new workflow with steps and triggers
`update_workflow`	Update an existing workflow's steps, triggers, or config
`delete_workflow`	Delete a workflow by ID

App Tools (remote only)

Tool	Description
`list_apps`	List all apps for the tenant
`get_app`	Get an app definition by ID
`create_app`	Create a new app with pages, components, and data bindings
`update_app`	Update an existing app's pages or config
`delete_app`	Delete an app by ID

Entity Tools (remote only)

Tool	Description
`list_collections`	List all entity collections for the tenant
`list_entities`	List entities within a collection with optional filters
`get_entity`	Get a single entity by collection and ID
`create_entity`	Create a new entity in a collection
`update_entity`	Update an existing entity's fields
`delete_entity`	Delete an entity by collection and ID

Tool Examples

create_integration:

Tool: create_integration
Arguments:
  - name: "airtable"
  - displayName: "Airtable"
  - description: "Airtable API integration"
  - baseUrl: "https://api.airtable.com/v0"
  - auth: { type: "bearer" }
  - endpoints: [...]

Example prompt to Claude:

"Create an Airtable integration with endpoints for listing records, creating records, and updating records"

create_route:

Tool: create_route
Arguments:
  - path: "/airtable/records"
  - method: "get"
  - description: "List Airtable records"
  - requireAuth: true
  - integrations: { actions: [...] }

Example: Setting Up a Tenant API with Claude

Ask Claude:

"I need to set up an API for a property management company. They need:
A Buildium integration for property data
A Stripe integration for payments
Routes for listing properties, processing payments, and generating reports"

Claude will use the MCP tools to:

Create the Buildium integration with appropriate endpoints
Create the Stripe integration for payment processing
Create routes that chain these integrations together

Security Considerations

Setting	Description	Recommendation
`allowIntegrationCreation`	Allow AI to create integrations	`true` for dev, `false` for prod
`allowRouteCreation`	Allow AI to create routes	`true` for dev, `false` for prod
`autoReload`	Auto-reload on changes	`false` for production

MCP Client (Workflows)

Connect to external MCP servers from workflows.

Configuration

In config.json:

json

{
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/files"
      ]
    },
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "&#123;&#123;env.GITHUB_TOKEN&#125;&#125;"
      }
    },
    {
      "name": "sqlite",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "/path/to/db.sqlite"
      ]
    }
  ]
}

Using MCP Tools in Workflows

json

{
  "id": "file-analysis",
  "workflows": [
    {
      "name": "analyze",
      "steps": [
        {
          "id": "read-file",
          "action": "read_file",
          "params": {
            "path": "&#123;&#123;input.filePath&#125;&#125;"
          }
        },
        {
          "id": "analyze",
          "action": "llm",
          "params": {
            "prompt": "Analyze this file content:\n&#123;&#123;steps.read-file.result&#125;&#125;"
          }
        }
      ]
    }
  ],
  "tools": [
    {
      "name": "read_file",
      "type": "mcp_tool",
      "params": {
        "mcpServer": "filesystem",
        "toolName": "read_file"
      }
    },
    { "name": "llm", "type": "llm_call" }
  ]
}

Available MCP Servers

Popular MCP servers from the community:

Server	Package	Description
Filesystem	`@modelcontextprotocol/server-filesystem`	Read/write local files
GitHub	`@modelcontextprotocol/server-github`	GitHub API operations
SQLite	`@modelcontextprotocol/server-sqlite`	SQLite database queries
PostgreSQL	`@modelcontextprotocol/server-postgres`	PostgreSQL operations
Slack	`@modelcontextprotocol/server-slack`	Slack messaging
Google Drive	`@modelcontextprotocol/server-gdrive`	Google Drive files
Brave Search	`@modelcontextprotocol/server-brave-search`	Web search

Dynamic MCP Tool Discovery

json

{
  "id": "discover",
  "action": "mcp.listTools",
  "params": {
    "server": "filesystem"
  }
}

Execute Any MCP Tool

json

{
  "id": "execute",
  "action": "mcp.execute",
  "params": {
    "server": "github",
    "tool": "create_issue",
    "arguments": {
      "repo": "owner/repo",
      "title": "&#123;&#123;input.title&#125;&#125;",
      "body": "&#123;&#123;input.body&#125;&#125;"
    }
  }
}

MCP API Endpoints

List MCP Servers

bash

GET /agent/mcp/servers
Authorization: Bearer <token>

Response:

json

{
  "servers": [
    { "name": "filesystem", "connected": true, "tools": 5 },
    { "name": "github", "connected": true, "tools": 12 }
  ]
}

List Tools from Server

bash

GET /agent/mcp/servers/filesystem/tools
Authorization: Bearer <token>

Execute MCP Tool

bash

POST /agent/mcp/execute
Authorization: Bearer <token>
Content-Type: application/json

{
  "server": "filesystem",
  "tool": "read_file",
  "arguments": {
    "path": "/app/data/config.json"
  }
}

Example: Full Tenant Setup with Claude

1. Start Backflow MCP Server

bash

npm run mcp
# Or: node dist/mcp.js

2. Configure Claude Desktop

json

{
  "mcpServers": {
    "backflow": {
      "command": "node",
      "args": ["/app/backflow/dist/mcp.js", "/app/config/mcp-config.json"]
    }
  }
}

3. Ask Claude to Set Up API

Prompt:

"I'm setting up a SaaS for fitness studios. Create integrations and routes for:
Mindbody API for class schedules and bookings
Stripe for membership payments
Twilio for class reminders
A dashboard endpoint that combines studio stats"

Claude will:

Create Mindbody integration with schedule/booking endpoints
Create Stripe integration for subscriptions
Create Twilio integration for SMS
Create routes that:
- GET /classes - List upcoming classes
- POST /bookings - Book a class
- POST /memberships - Create membership
- GET /dashboard - Aggregate stats

4. Review Generated Files

bash

ls integrations/
# mindbody.json
# stripe.json
# twilio.json

cat config.json | jq '.routes'
# Shows new routes added by Claude

5. Start Backflow

bash

npm start

Your tenant's API is now ready.

Troubleshooting

MCP Server Not Starting

bash

# Check if MCP module is built
npm run build

# Run directly with debug
DEBUG=mcp* node dist/mcp.js

Claude Not Finding Tools

Restart Claude Desktop after config changes
Check config path is correct
Verify the MCP server starts without errors

Permission Errors

bash

# Ensure integrations directory is writable
chmod 755 ./integrations

# Ensure config.json is writable for route creation
chmod 644 ./config.json

MCP Integration ​

Overview ​

Backflow MCP Server ​

Setup with Claude Desktop ​

Setup with Claude Code ​

Remote Setup (API Mode) ​

Method A: npx package (recommended) ​

Method B: SSE URL (for HTTP-native MCP clients) ​

Local vs Remote Comparison ​

MCP Configuration ​

Available Tools ​

Integration Tools ​

Route Tools ​

Workflow Tools (remote only) ​

App Tools (remote only) ​

Entity Tools (remote only) ​

Tool Examples ​

Example: Setting Up a Tenant API with Claude ​

Security Considerations ​

MCP Client (Workflows) ​

Configuration ​

Using MCP Tools in Workflows ​

Available MCP Servers ​

Dynamic MCP Tool Discovery ​

Execute Any MCP Tool ​

MCP API Endpoints ​

List MCP Servers ​

List Tools from Server ​

Execute MCP Tool ​

Example: Full Tenant Setup with Claude ​

1. Start Backflow MCP Server ​

2. Configure Claude Desktop ​

3. Ask Claude to Set Up API ​

4. Review Generated Files ​

5. Start Backflow ​

Troubleshooting ​

MCP Server Not Starting ​

Claude Not Finding Tools ​

Permission Errors ​

MCP Integration

Overview

Backflow MCP Server

Setup with Claude Desktop

Setup with Claude Code

Remote Setup (API Mode)

Method A: npx package (recommended)

Method B: SSE URL (for HTTP-native MCP clients)

Local vs Remote Comparison

MCP Configuration

Available Tools

Integration Tools

Route Tools

Workflow Tools (remote only)

App Tools (remote only)

Entity Tools (remote only)

Tool Examples

Example: Setting Up a Tenant API with Claude

Security Considerations

MCP Client (Workflows)

Configuration

Using MCP Tools in Workflows

Available MCP Servers

Dynamic MCP Tool Discovery

Execute Any MCP Tool

MCP API Endpoints

List MCP Servers

List Tools from Server

Execute MCP Tool

Example: Full Tenant Setup with Claude

1. Start Backflow MCP Server

2. Configure Claude Desktop

3. Ask Claude to Set Up API

4. Review Generated Files

5. Start Backflow

Troubleshooting

MCP Server Not Starting

Claude Not Finding Tools

Permission Errors