Skip to main content

​
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 (with your API key) to list and call those tools.

​
Example use cases

  • Cursor / IDE — You register an MCP server (or use Flowra’s) and point Cursor at Flowra’s MCP URL. Cursor discovers your tools and lets the AI in the IDE call them (e.g. “run this workflow”, “search my knowledge base”).
  • Claude Desktop — Add Flowra as an MCP server in Claude Desktop; Claude can then use 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:
ModeWhat it doesWhen 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

  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 the server ID and your 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.
All endpoints require API key authentication (x-api-key header). Below: server management (list, create, get, update, delete, get config, load-from-URL) and runtime (SSE + JSON-RPC).

​
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. Use the x-api-key header for authentication.

​
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

All endpoints require API key authentication. Send your project API key in the x-api-key header.

​
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 (e.g. a single shared connection). So: one MCP server URL, one API key; pass x-username and each client (or each user in your app) gets their own connections.