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

# MCP

> Model Context Protocol: connect with OAuth or an API key, register servers, and call tools

## What is MCP?

**MCP** (Model Context Protocol) is an open standard that lets AI applications (e.g. Cursor, Claude Desktop, your own app) discover and call **tools** over a common protocol. Instead of each tool provider building a custom API, they expose an MCP server; clients connect once and get a list of tools (name, description, input schema) and can call them via JSON-RPC or SSE. Flowra fits into this: you **register** MCP servers (by URL) in your project, and Flowra’s **MCP endpoints** let external MCP clients connect and use the tools you've made available — so Cursor or another client can call your Flowra project's tools as if they were native MCP tools.

So: **MCP server** = something that exposes tools via MCP; **Flowra** = you register servers or use Flowra's own tools, and clients talk to Flowra's MCP endpoint to list and call those tools.

## Hosted URL

Use this for Cursor, Claude Code, Codex, OpenClaw, Hermes, Windsurf, and any streamable HTTP client:

```
https://mcp.flowra.dev/mcp
```

The first authenticated request creates a default **META** server for the project. You do not pick a server ID. Setup pages: [flowra.dev/agents](https://flowra.dev/agents). Per-server URLs (`https://mcp.flowra.dev/mcp/{serverId}`) still work for pinned tool sets.

### Authenticate

**OAuth (preferred for Cursor, Claude, and other MCP clients):** add the URL with no headers. The client opens Flowra sign-in (Google, GitHub, or email). You pick a project. The client then sends a Bearer token. Copy this from **Dashboard → MCP → Install & Config → Sign in (OAuth)** when you can.

```json theme={null}
{
  "mcpServers": {
    "flowra": {
      "url": "https://mcp.flowra.dev/mcp",
      "transport": "http"
    }
  }
}
```

**API key (CI, scripts, and clients without OAuth):** send **x-api-key** (project API key) and **x-username** (default `project_default_user`).

Connecting Gmail, Slack, or another catalog app is a separate toolkit OAuth step via `FLOWRA_MANAGE_CONNECTIONS`. That is not the same as MCP sign-in.

### The six tools

The hosted URL binds six [meta tools](/guides/native-tools/meta). Your client never loads the 1,000+ app catalog up front.

| Tool | Role |
| - | - |
| `FLOWRA_DISCOVER_TOOLS` | Find catalog tool slugs for a task |
| `FLOWRA_GET_TOOL_SCHEMAS` | Load input schemas for those slugs |
| `FLOWRA_MANAGE_CONNECTIONS` | Check or start a Gmail, Slack, or other app connection |
| `FLOWRA_MULTI_EXECUTE_TOOL` | Run one or more catalog tools by slug |
| `FLOWRA_JS_REMOTE_WORKBENCH` | Stateful JavaScript sandbox with `run_tool` for bulk work |
| `FLOWRA_REMOTE_BASH` | One-shot shell command in the same sandbox |

Each tool declares `annotations` (read-only, destructive, open-world hints) and an `outputSchema`. Successful calls return `structuredContent` that matches it.

Registries and scanners can read the tool list without a token at `https://mcp.flowra.dev/.well-known/mcp/server-card.json`. The MCP endpoint itself still requires OAuth or an API key.

### Install the agent skill

The skill teaches your coding agent the discover, connect, and run order:

```bash theme={null}
npx skills add flowradev/skills --skill flowra
```

[![skills.sh](https://skills.sh/b/flowradev/skills)](https://skills.sh/flowradev/skills)

### Example use cases

* **Cursor / IDE** — Add `https://mcp.flowra.dev/mcp` with no headers. Cursor opens Flowra sign-in, you pick a project, then the AI can call tools (e.g. "run this workflow", "search my knowledge base").
* **Claude Desktop** — Add the same URL as an MCP server. Claude signs in with OAuth and uses the tools you've configured for the project.
* **Preview tools without registering** — Call "load tools from URL" to fetch the list of tools an MCP server offers without adding it to your project yet. Then register the server when you're ready.

### Smart mode vs manual (Normal) mode

When you create an MCP server in Flowra, you choose a **mode** that determines which tools it exposes:

| Mode | What it does | When to use it |
| - | - | - |
| **Smart** (default) | Flowra exposes the six **meta tools**: discover, schemas, connections, execute, and the JavaScript and bash sandboxes. The client (e.g. Cursor) sees this curated list and can search Flowra’s catalog and run tools through Flowra. You don’t pick individual tools. | You want “Flowra as one MCP server” with discovery and execution out of the box. Best for: Cursor/IDE using Flowra’s full tool set. |
| **Normal** (manual) | You **manually select** which tools this MCP server exposes. Pass `selectedTools` (array of tool slugs) when creating or updating the server. Only those tools appear to the client. You control the exact list (e.g. only Slack + Gmail, or a few custom tools). | You want a narrow, predictable set of tools (e.g. only “send Slack message” and “create calendar event”) so the AI doesn’t see everything. |

Summary: **Smart** = Flowra’s six built‑in meta tools. **Normal** = you choose the exact tools by slug.

### External MCP servers

You can attach **external MCP servers** to the same Flowra MCP server. Those are third‑party MCP endpoints (any URL that speaks MCP). When you create or update an MCP server, you can pass **externalMcpConfigs**: an array of `{ name, url, headers?, tools }`. Flowra stores them on the workspace and returns them in the server config. The client (e.g. Cursor) can then talk to Flowra for Flowra tools and, using that config, to your external MCP URLs for their tools — so one “MCP server” in Flowra can expose both Flowra tools and external MCP tools.

* **Use case** — You have your own MCP server (e.g. internal APIs, custom tools). Instead of registering it separately in Cursor, you add it as an external config on a Flowra MCP server. Users connect once to Flowra and get both Flowra tools and your external server’s tools.
* **Create/update** — In **POST** `/api/v1/mcp_manager` or **PATCH** `/api/v1/mcp_manager/{id}`, send `externalMcpConfigs`: e.g. `[{ "name": "my-api", "url": "https://my-mcp.example.com/sse", "headers": { "Authorization": "Bearer ..." }, "tools": ["tool_a", "tool_b"] }]`. See the [API reference](/api-reference) for the full schema.

### How it works

1. **Register** an MCP server (POST with name, optional `mode`, `selectedTools` for Normal, `externalMcpConfigs` for external MCP). Flowra stores it and assigns a **server ID**.
2. **List tools** — Get the config (tools list, mode, external configs) for a server. Useful for building a tool picker or debugging.
3. **Runtime** — MCP clients connect to Flowra’s endpoint with OAuth or an API key. They use SSE or JSON-RPC to list and call tools; Flowra routes to the right server or to Flowra’s own tools.

MCP **runtime** accepts OAuth or **x-api-key**. **mcp\_manager** (list, create, update, delete, config, load-from-URL) still uses a project API key from your backend or the dashboard.

***

## API endpoints

### List MCP servers

**GET** `/api/v1/mcp_manager` returns a paginated list of your registered MCP servers. Query params: `page`, `limit`, `cursor`, etc. (see [API reference](/api-reference)).

### Create MCP server

**POST** `/api/v1/mcp_manager` creates a new MCP server. Request body (**CreateMcpServerDto**): `name` (required, slug), optional `description`, `mode` (`SMART` or `NORMAL` — see [Smart vs manual](#smart-mode-vs-manual-normal-mode) above), `selectedTools` (for NORMAL mode: array of tool slugs), `externalMcpConfigs` (optional: array of `{ name, url, headers?, tools }` for [external MCP servers](#external-mcp-servers)), and optional `config`, `isPublic`. Once created, the server’s tools (and any external configs) are available to MCP clients and in workflows.

### Get, update, delete

* **GET** `/api/v1/mcp_manager/{id}` — Get one MCP server’s connection details and metadata.
* **PATCH** `/api/v1/mcp_manager/{id}` — Update URL, name, headers, or other settings (**UpdateMcpServerDto**).
* **DELETE** `/api/v1/mcp_manager/{id}` — Remove the server; its tools will no longer be available.

### Get server config (tools list)

**GET** `/api/v1/mcp_manager/{id}/config` returns the list of tools exposed by this server in standard format (name, description, input schema). Use to build a tool picker or to call tools via the MCP JSON-RPC endpoint.

### Load tools from URL (without registering)

**POST** `/api/v1/mcp_manager/load-tools-from-url` fetches the list of tools from an MCP server URL **without** registering the server. Body: **LoadToolsFromUrlDto** (e.g. `url`, optional `headers`, `cacheMinutes`). Use to preview which tools a server offers before adding it.

### MCP runtime endpoints

Clients use these to talk to a registered server by **serverId**.

### SSE (Server-Sent Events)

**GET** `/api/v1/mcp/{serverId}` — MCP over SSE. Clients connect to this URL; the response includes the POST URL to use for JSON-RPC. Authenticate with MCP OAuth or **x-api-key**.

### JSON-RPC (POST)

**POST** `/api/v1/mcp/{serverId}` — Send MCP JSON-RPC 2.0 requests (e.g. `tools/list`, `tools/call`). Request body: **McpRequestDto**; response: **McpJsonRpcResponseDto** (see [API reference](/api-reference)).

### Authentication

* **Runtime** (`GET`/`POST` `/api/v1/mcp` and `/api/v1/mcp/{serverId}`) — MCP OAuth Bearer token, or a project API key (`x-api-key` or `Authorization: Bearer` / `Authorization: ApiKey`).
* **Server management** (`/api/v1/mcp_manager`) — project API key (or the dashboard session).

An unauthenticated runtime request returns **401** with `WWW-Authenticate` so the client can start OAuth. Do not send a dashboard JWT to the MCP JSON-RPC endpoint.

### Per-user connections with x-username

If your app has multiple end users (e.g. each customer has their own Slack or Google connection), you can keep **connections separate per user** by sending the **x-username** header on MCP requests. Use the same username (name) as in the [external users API](/guides/multi-tenancy#external-users-api). Flowra then resolves [connected accounts](/guides/connected-accounts) in that external user’s context — so when the AI runs a tool (e.g. “send Slack message”), it uses that user’s connected Slack workspace, not someone else’s. Without **x-username**, the MCP server uses the project’s default context (`project_default_user`). That is also the default after MCP OAuth unless you add **x-username**. One MCP server URL; identity is still the username.

## SDK

Register and inspect MCP servers from your backend:

```ts theme={null}
await flowra.mcp.list();
await flowra.mcp.create({ /* CreateMcpServerDto */ });
const config = await flowra.mcp.config(serverId);
```

```python theme={null}
flowra.mcp.list()
flowra.mcp.create({...})
config = flowra.mcp.config(server_id)
```

For Cursor install, prefer the dashboard **Install & Config** flow — [Use MCP in Cursor](/recipes/use-mcp-in-cursor).

## Related

* [Authentication](/authentication) — Project API keys for the public API and MCP API-key mode.
* [Tools](/guides/tools) — Execute tools; MCP servers expose tools you can run.
* [API reference: mcp, mcp\_manager](/api-reference) — Full request/response schemas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.