MCP Server - SuperAI Flows

The SuperAI Flows MCP (Model Context Protocol) server lets external AI agents and MCP-compatible clients interact with flows programmatically — creating workflows, reading state, managing definitions, and downloading files — without going through the UI.

Overview

The MCP server exposes a curated subset of the SuperAI Flows API as MCP tools over the Streamable HTTP transport. It’s mounted at /mcp on the main API service and secured via the service-account API key system.


Endpoint	`https://flows.super.ai/mcp` (production)
Transport	Streamable HTTP (POST)
Authentication	`X-API-Key` header with a valid service-account key

Authentication

All MCP requests require a valid service-account API key passed via the X-API-Key header.

Navigate to Settings → Service Accounts in the SuperAI Flows UI.
Create a new service account or use an existing one.
Copy the API key (format: saf_org_...).

Bearer token (Authorization header) authentication is not supported for MCP — use API keys only.

Client configuration

Claude Code
Claude Desktop
Native header support

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "superai-flows": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://flows.super.ai/mcp",
        "--header",
        "X-API-Key:saf_org_..."
      ]
    }
  }
}

Add .mcp.json to .gitignore if it contains API keys.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "superai-flows": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://flows.super.ai/mcp",
        "--header",
        "X-API-Key:saf_org_..."
      ]
    }
  }
}

Some MCP clients support the url + headers format directly:

{
  "mcpServers": {
    "superai-flows": {
      "url": "https://flows.super.ai/mcp",
      "headers": {
        "X-API-Key": "saf_org_..."
      }
    }
  }
}

To avoid hardcoding keys, use shell variable expansion — for example "X-API-Key:${SAF_API_KEY}".

Available tools

The MCP server exposes 5 tools across three categories.

Discovery

`get_task_executors`

List all available task executors (building blocks) for workflow composition. Use when: you need to know what task types exist before creating or modifying a flow. Parameters: none. Returns an array of task executor definitions, each including task_executor_name, task_executor_description, parameters_schema, flow_input_schema, is_input_task_executor, and is_schedulable_executor.

Flow management

`create_flow`

Create a new flow in draft status.

Parameter	Type	Required	Description
`display_name`	string	Yes	Human-readable name (max 255 chars)
`definition`	object	Yes	Flow definition in DSL format (tasks, edges, version)
`description`	string	No	Markdown description (max 5000 chars)
`visibility`	string	No	`private`, `organization`, or `public`
`settings`	object	No	Flow-level settings (TTL, reexecute_on_update, etc.)

Returns a complete FlowResponse with ID, version, status, and definition.

`update_flow_definition`

Replace the entire definition of a draft flow. Creates a new version.

Parameter	Type	Required	Description
`flow_id`	UUID	Yes	The flow to update
`definition`	object	Yes	New complete flow definition

Only flows in draft status can be updated; published flows are immutable. Each update increments the version number.

Flow inspection

`get_flow`

Retrieve a specific flow by ID with its complete definition and metadata.

Parameter	Type	Required	Description
`flow_id`	UUID	Yes	The flow to retrieve
`include_validation_errors`	boolean	No	Include DSL validation errors
`include_ordered_task_names`	boolean	No	Include topologically sorted task names
`include_output_schemas`	boolean	No	Include output JSON Schemas

Only request the expansion parameters you need. The base response is ~50–100ms; include_dynamic_data can add 100–500ms.

File access

`generate_download_url`

Generate a pre-signed URL (valid for 1 hour) for downloading a flow file.

Parameter	Type	Required	Description
`file_key`	string	Yes	File key from a file listing or upload response

Common workflows

Build a new flow:
  get_task_executors → create_flow → get_flow (validate) → update_flow_definition

Inspect and modify:
  get_flow → get_task_executors → update_flow_definition → get_flow (validate)

Download files:
  get_flow → generate_download_url

Testing

The MCP Inspector is the easiest way to debug:

npx @modelcontextprotocol/inspector

Connect to https://flows.super.ai/mcp with Streamable HTTP transport and add the X-API-Key header. Or check the endpoint with curl:

curl -X POST https://flows.super.ai/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: saf_org_..." \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Limitations

API key auth only — JWT / bearer token authentication is not supported for MCP connections.
Read/write scope — The API key’s permissions determine which flows are accessible.
No streaming — Tool responses are returned as complete JSON.
5 tools only — Only core flow management endpoints are exposed; flow executions, task outputs, and admin endpoints are not available via MCP.

​Overview

​Authentication

​Client configuration

​Available tools

​Discovery

​get_task_executors

​Flow management

​create_flow

​update_flow_definition

​Flow inspection

​get_flow

​File access

​generate_download_url

​Common workflows

​Testing

​Limitations

Overview

Authentication

Client configuration

Available tools

Discovery

`get_task_executors`

Flow management

`create_flow`

`update_flow_definition`

Flow inspection

`get_flow`

File access

`generate_download_url`

Common workflows

Testing

Limitations