MCP Integration

Connect FlowMason to AI assistants via Model Context Protocol for AI-native pipeline management.

Beta Feature - This feature is currently under heavy testing. For early access, contact [email protected].

FlowMason includes a Model Context Protocol (MCP) server that enables AI assistants like Claude to directly interact with your pipelines.

Overview

The MCP integration provides:

• Pipeline Management - Create, read, update, delete pipelines via AI
• Execution Control - Run pipelines and get results
• Component Discovery - Browse available components
• Natural Language - Describe what you want, AI builds it
• IDE Integration - Works with Claude Desktop, VSCode, and more

Quick Start

Start the MCP Server

fm mcp start

Or run as part of Studio:

fm studio start --mcp

Configure Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "flowmason": {
      "command": "fm",
      "args": ["mcp", "stdio"],
      "env": {
        "FLOWMASON_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

The MCP server exposes these tools to AI assistants:

Pipeline Operations

Execution

Components

Generation

Example Interactions

Create a Pipeline via AI

User: “Create a pipeline that summarizes articles and translates to Spanish”

Claude uses tools:

1. generate_pipeline - Creates pipeline structure
2. create_pipeline - Saves to FlowMason
3. validate_pipeline - Verifies it’s valid

Result: Working pipeline created and ready to run.

Run a Pipeline

User: “Run the content-summarizer pipeline with this article: [text]”

Claude uses tools:

1. get_pipeline - Finds the pipeline
2. run_pipeline - Executes with input
3. get_run_result - Returns output

Browse Components

User: “What components can I use for data filtering?”

Claude uses tools:

1. search_components - Finds relevant components
2. Returns: filter, json_transform, conditional, router

Tool Schemas

list_pipelines

{
  "name": "list_pipelines",
  "description": "List all pipelines with optional filters",
  "inputSchema": {
    "type": "object",
    "properties": {
      "status": {
        "type": "string",
        "enum": ["draft", "published", "archived"]
      },
      "category": { "type": "string" },
      "limit": { "type": "integer", "default": 20 }
    }
  }
}

run_pipeline

{
  "name": "run_pipeline",
  "description": "Execute a pipeline with input data",
  "inputSchema": {
    "type": "object",
    "properties": {
      "pipeline_id": { "type": "string" },
      "input": { "type": "object" },
      "async": { "type": "boolean", "default": false }
    },
    "required": ["pipeline_id", "input"]
  }
}

generate_pipeline

{
  "name": "generate_pipeline",
  "description": "Generate a pipeline from natural language",
  "inputSchema": {
    "type": "object",
    "properties": {
      "description": {
        "type": "string",
        "description": "Natural language description"
      },
      "save": {
        "type": "boolean",
        "default": false
      }
    },
    "required": ["description"]
  }
}

Resources

The MCP server also exposes resources:

Pipeline Resources

flowmason://pipelines
flowmason://pipelines/{id}
flowmason://pipelines/{id}/stages
flowmason://pipelines/{id}/runs

Component Resources

flowmason://components
flowmason://components/{type}
flowmason://components/categories

Documentation Resources

flowmason://docs/getting-started
flowmason://docs/components/{type}
flowmason://docs/best-practices

VSCode Integration

The FlowMason VSCode extension includes MCP support:

1. Command Palette - FlowMason: Ask AI Assistant
2. Context Menu - Right-click pipeline for AI suggestions
3. Inline Assist - AI-powered stage configuration
4. Chat Panel - Conversational pipeline building

Enable in VSCode

{
  "flowmason.mcp.enabled": true,
  "flowmason.mcp.provider": "claude"
}

Security

API Key Scopes

MCP operations respect API key scopes:

Audit Logging

All MCP operations are logged:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "tool": "run_pipeline",
  "user": "mcp_client",
  "pipeline_id": "content-summarizer",
  "status": "success"
}

Python Client

Use the MCP client programmatically:

from flowmason_core.mcp.client import FlowMasonMCPClient

client = FlowMasonMCPClient(
    server_url="http://localhost:8999/mcp",
    api_key="your-api-key"
)

# List pipelines
pipelines = await client.call_tool("list_pipelines", {
    "status": "published"
})

# Run a pipeline
result = await client.call_tool("run_pipeline", {
    "pipeline_id": "content-summarizer",
    "input": {"text": "Article content here..."}
})

# Generate from description
generated = await client.call_tool("generate_pipeline", {
    "description": "Filter products by price and sort by rating",
    "save": True
})

Configuration

Server Options

fm mcp start \
  --port 8998 \
  --host 0.0.0.0 \
  --api-key-required \
  --log-level debug

Environment Variables

Best Practices

1. Use descriptive names - Help AI understand your pipelines
2. Add descriptions - Document what each stage does
3. Validate before run - Use validate_pipeline first
4. Review generated pipelines - AI suggestions may need refinement
5. Use scoped API keys - Limit MCP client permissions