MCP Server - SuperAI Flows

The SuperAI Flows MCP (Model Context Protocol) server lets external AI agents and MCP-compatible clients work with SuperAI Flows programmatically — building and updating flows, starting and monitoring runs, reading task outputs, completing human reviews, and downloading files — without going through the UI.

Overview

The MCP server exposes the public SuperAI Flows API as MCP tools over the Streamable HTTP transport: every operation in the API reference is available as a tool, and nothing outside it. 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), stateless
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.

As an organization admin, open Organization settings → Service accounts from your profile menu 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

Each operation of the public API is one MCP tool. A tool’s name is the operation’s operationId from the OpenAPI specification, its input is the operation’s path, query and body parameters, and it returns the same JSON the API returns. Your client lists the tools with tools/list. The tools follow the sections of the API reference:

Area	What the tools cover	Example tool
Flows	List, create, read, update and delete flows and their definitions	`get_flow_api_flows__flow_id__get`
Task executors	Discover the task types you can build flows from	`get_task_executors_api_task_executors_get`
Flow executions	Start, list, read, cancel, re-execute and delete runs	`create_flow_execution_api_flow_executions_post`
Task executions and outputs	Read and update the results of each task in a run	`list_task_executions_api_task_executions_get`
Human review tasks	List, read and complete review tasks	`complete_human_review_task_api_human_review_tasks__task_id__complete_post`
Files	Resolve file references and download files	`download_file_api_files_download_get`
Integrations and plugins	Manage credentials and integration instances	`get_integration_catalog_api_integrations_catalog_get`
Organization and access	Service accounts, members, worker groups, SSO and your profile	`list_service_accounts_api_service_accounts_get`

What each tool may do follows the permissions of the service account behind the API key.

Common workflows

Build a new flow:
  get_task_executors_api_task_executors_get → create_flow_api_flows_post → get_flow_api_flows__flow_id__get (check validation)

Run a flow and read its results:
  create_flow_execution_api_flow_executions_post → get_flow_execution_api_flow_executions__flow_execution_id__get
  → list_task_executions_api_task_executions_get

Download a file:
  resolve_uri_api_files_resolve_post → download_file_api_files_download_get

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.
Public API only — Internal and admin-only endpoints are not exposed. If an operation isn’t in the API reference, it isn’t available as a tool.
Stateless — Each request is handled on its own, so there is no server-to-client notification stream (GET /mcp returns 405).

​Overview

​Authentication

​Client configuration

​Available tools

​Common workflows

​Testing

​Limitations

Overview

Authentication

Client configuration

Available tools

Common workflows

Testing

Limitations