Expose FlowFuse Forge as an MCP server so that external AI agents (Claude Desktop, Cursor, Claude Code) and the built-in expert can manage the platform and build flows through a single endpoint. One endpoint, three tool categories, phased delivery.
What we're building
A single MCP endpoint (POST /api/v1/mcp) that serves three categories of tools:
Platform tools (phase 1): Backend only. Create instances, manage teams, list resources. Tools call existing HTTP routes via app.inject(), inheriting the full auth and validation stack. No browser involvement.
Flow tools and frontend tools (phase 2): Browser-dependent. These are proxied through the first-party agent (FF Expert), which already has the MQTT infrastructure to reach the browser and NR instances. The MCP endpoint aggregates the agent's tool list with platform tools and routes tool calls accordingly.
How auth works
No MCP-specific auth layer. Users authenticate with scoped PATs (#7411, handled separately). The PAT carries the user's identity, and every action runs with that user's existing permissions. PAT scopes let users self-restrict what the agent can do (read-only, read-write, team-scoped). The MCP server is a passthrough.
OAuth2 PKCE adds automated token acquisition later, building on the existing OAuth scaffolding. This evolves naturally from "paste a PAT" to "paste your URL and authenticate" to "pre-built Claude plugin."
Key architectural decisions
EE plugin, not microservice. Direct access to app, no deployment overhead. Acceptable coupling because tools use app.inject(), not direct controller calls.
Stateless per-request. Each HTTP request gets a fresh McpServer. No sessions, no affinity. Load balancer treats it like regular REST.
app.inject() for platform tools. Tools call existing routes internally. All middleware, validation, and audit run normally. Routes stay untouched.
Expert agent as gateway for flow/UI tools. The MCP endpoint proxies to the first-party agent (FF Expert) for all browser-dependent tools. The agent already has the MQTT inflight infrastructure, NR instance abstractions, and browser communication. The MCP endpoint is a pure aggregator/proxy with no direct MQTT connection.
Fail descriptively. Every error returns structured, actionable information that an LLM agent can relay to the user (editor not open, multiple sessions, stale connection, etc.).
Phasing
| Phase |
Scope |
Auth |
| 1 |
Platform tools (backend only) |
Scoped PATs (#7411) |
| 2 |
Flow tools + UI tools (browser-dependent) |
Scoped PATs + OAuth2 PKCE |
| 3 |
Claude plugin / connector directory |
OAuth2 with Anthropic callback URLs |
Expose FlowFuse Forge as an MCP server so that external AI agents (Claude Desktop, Cursor, Claude Code) and the built-in expert can manage the platform and build flows through a single endpoint. One endpoint, three tool categories, phased delivery.
What we're building
A single MCP endpoint (
POST /api/v1/mcp) that serves three categories of tools:Platform tools (phase 1): Backend only. Create instances, manage teams, list resources. Tools call existing HTTP routes via
app.inject(), inheriting the full auth and validation stack. No browser involvement.Flow tools and frontend tools (phase 2): Browser-dependent. These are proxied through the first-party agent (FF Expert), which already has the MQTT infrastructure to reach the browser and NR instances. The MCP endpoint aggregates the agent's tool list with platform tools and routes tool calls accordingly.
How auth works
No MCP-specific auth layer. Users authenticate with scoped PATs (#7411, handled separately). The PAT carries the user's identity, and every action runs with that user's existing permissions. PAT scopes let users self-restrict what the agent can do (read-only, read-write, team-scoped). The MCP server is a passthrough.
OAuth2 PKCE adds automated token acquisition later, building on the existing OAuth scaffolding. This evolves naturally from "paste a PAT" to "paste your URL and authenticate" to "pre-built Claude plugin."
Key architectural decisions
EE plugin, not microservice. Direct access to
app, no deployment overhead. Acceptable coupling because tools useapp.inject(), not direct controller calls.Stateless per-request. Each HTTP request gets a fresh McpServer. No sessions, no affinity. Load balancer treats it like regular REST.
app.inject()for platform tools. Tools call existing routes internally. All middleware, validation, and audit run normally. Routes stay untouched.Expert agent as gateway for flow/UI tools. The MCP endpoint proxies to the first-party agent (FF Expert) for all browser-dependent tools. The agent already has the MQTT inflight infrastructure, NR instance abstractions, and browser communication. The MCP endpoint is a pure aggregator/proxy with no direct MQTT connection.
Fail descriptively. Every error returns structured, actionable information that an LLM agent can relay to the user (editor not open, multiple sessions, stale connection, etc.).
Phasing