MCP

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

{
  "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.

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 a fixed set of meta tools: discover tools, execute a tool, manage connections, etc. 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 built‑in meta tools (discover, execute, manage connections). 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 for the full schema.

How it works

Register an MCP server (POST with name, optional mode, selectedTools for Normal, externalMcpConfigs for external MCP). Flowra stores it and assigns a server ID.
List tools — Get the config (tools list, mode, external configs) for a server. Useful for building a tool picker or debugging.
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).

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 above), selectedTools (for NORMAL mode: array of tool slugs), externalMcpConfigs (optional: array of { name, url, headers?, tools } for 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).

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. Flowra then resolves 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

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

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.

Authentication — Project API keys for the public API and MCP API-key mode.
Tools — Execute tools; MCP servers expose tools you can run.
API reference: mcp, mcp_manager — Full request/response schemas.

Getting started

SDK reference

Core building blocks

Data and runtime

Integrate and scale

Recipes

Native tools

Contributing

What is MCP?

Hosted URL

Authenticate

Example use cases

Smart mode vs manual (Normal) mode

External MCP servers

How it works

API endpoints

List MCP servers

Create MCP server

Get, update, delete

Get server config (tools list)

Load tools from URL (without registering)

MCP runtime endpoints

SSE (Server-Sent Events)

JSON-RPC (POST)

Authentication

Per-user connections with x-username

SDK

​What is MCP?

​Hosted URL

​Authenticate

​Example use cases

​Smart mode vs manual (Normal) mode

​External MCP servers

​How it works

​API endpoints

​List MCP servers

​Create MCP server

​Get, update, delete

​Get server config (tools list)

​Load tools from URL (without registering)

​MCP runtime endpoints

​SSE (Server-Sent Events)

​JSON-RPC (POST)

​Authentication

​Per-user connections with x-username

​SDK

​Related

What is MCP?

Hosted URL

Authenticate

Example use cases

Smart mode vs manual (Normal) mode

External MCP servers

How it works

API endpoints

List MCP servers

Create MCP server

Get, update, delete

Get server config (tools list)

Load tools from URL (without registering)

MCP runtime endpoints

SSE (Server-Sent Events)

JSON-RPC (POST)

Authentication

Per-user connections with x-username

SDK

Related