FlowFuse / FlowFuse/flowfuse

Backend API surface for agentic platform orchestration

Open
#7,232 0 comments 0 reactions 1 assignee Claimed by @cstns View on GitHub
task
Dominant language
JavaScript
Stars
400
Forks
89
Avg merge
1d 21h
Merged PRs (30d)
146

Description

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 |

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.