MCP Integration

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

Overview

Backflow provides two MCP components:

1. MCP Server - Exposes Backflow tools to AI assistants (Claude, etc.)
2. 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):

{
  "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

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

MCP Configuration

Create mcp-config.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:

create_integration

Create a custom API 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"

list_integrations

List all custom integrations.

Tool: list_integrations
Arguments: none

get_integration

Get details of a specific integration.

Tool: get_integration
Arguments:
  - name: "airtable"

delete_integration

Delete a custom integration.

Tool: delete_integration
Arguments:
  - name: "airtable"

create_route

Create an API route using integrations.

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

list_routes

List all configured routes.

Tool: list_routes
Arguments: none

delete_route

Delete a route.

Tool: delete_route
Arguments:
  - path: "/airtable/records"
  - method: "get"

Example: Setting Up a Tenant API with Claude

Ask Claude:

"I need to set up an API for a property management company. They need:

1. A Buildium integration for property data
2. A Stripe integration for payments
3. Routes for listing properties, processing payments, and generating reports"

Claude will use the MCP tools to:

1. Create the Buildium integration with appropriate endpoints
2. Create the Stripe integration for payment processing
3. 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:

{
  "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": "{{env.GITHUB_TOKEN}}"
      }
    },
    {
      "name": "sqlite",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/db.sqlite"]
    }
  ]
}

Using MCP Tools in Workflows

{
  "id": "file-analysis",
  "workflows": [{
    "name": "analyze",
    "steps": [
      {
        "id": "read-file",
        "action": "read_file",
        "params": {
          "path": "{{input.filePath}}"
        }
      },
      {
        "id": "analyze",
        "action": "llm",
        "params": {
          "prompt": "Analyze this file content:\n{{steps.read-file.result}}"
        }
      }
    ]
  }],
  "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

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

Execute Any MCP Tool

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

MCP API Endpoints

List MCP Servers

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

Response:

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

List Tools from Server

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

Execute MCP Tool

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

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

2. Configure Claude Desktop

{
  "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:

1. Create Mindbody integration with schedule/booking endpoints
2. Create Stripe integration for subscriptions
3. Create Twilio integration for SMS
4. 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

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

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

5. Start Backflow

npm start

Your tenant's API is now ready.

Troubleshooting

MCP Server Not Starting

# Check if MCP module is built
npm run build

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

Claude Not Finding Tools

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

Permission Errors

# Ensure integrations directory is writable
chmod 755 ./integrations

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