> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flows.super.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect external AI agents and MCP-compatible clients to SuperAI Flows over the Model Context Protocol.

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.

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

<Note>
  Bearer token (`Authorization` header) authentication is **not supported** for MCP — use API keys only.
</Note>

## Client configuration

<Tabs>
  <Tab title="Claude Code">
    Add to `.mcp.json` in your project root:

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Claude Desktop">
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "superai-flows": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://flows.super.ai/mcp",
            "--header",
            "X-API-Key:saf_org_..."
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Native header support">
    Some MCP clients support the `url` + `headers` format directly:

    ```json theme={null}
    {
      "mcpServers": {
        "superai-flows": {
          "url": "https://flows.super.ai/mcp",
          "headers": {
            "X-API-Key": "saf_org_..."
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

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             |

<Tip>
  Only request the expansion parameters you need. The base response is \~50–100ms; `include_dynamic_data` can add 100–500ms.
</Tip>

### 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

```text theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.