docs: add a guide for connecting your own AI agent over MCP by dimitrieh · Pull Request #8241 · FlowFuse/flowfuse

dimitrieh · 2026-08-24T09:06:17Z

Adds docs/user/expert/third-party-agents.md for the 3.0 third-party agent feature, and an entry point to it from the Expert index. Written as a how-to, organised by what the reader is trying to do rather than by tool.

Two things to confirm before merge

1. The endpoint path. The guide documents /api/v1/mcp, matching #8192. On main after #8237, forge/ee/routes/index.js registers the mcp routes with no prefix and forge/ee/routes/mcp/index.js registers the server with prefix: '/mcp', which reads as the root path. The sibling registrations route still carries a full /api/v1/teams/:teamId/mcp prefix. If the intended public path is /mcp, this needs changing in three places in the guide.

2. OAuth. The guide leads with signing in and treats access tokens as the alternative for clients that only accept a header, per the 3.0 plan. That depends on #7423 landing. If it slips, the sign-in steps and the per-agent sections need reordering.

A gap this surfaced

docs/user/logs.md documents a sparkle icon for FlowFuse Expert actions and a terminal icon for API actions via a Personal Access Token, and says the logs cover "supported FlowFuse Expert and API actions only". It does not describe third-party agent activity. I have linked that section rather than describe a marker I could not verify, but the page likely needs updating for 3.0.

Notes

No definitive tool list is published. The guide describes what an agent can do in prose and says editor capability is read from the connected instance, so it varies.
The requirements section leads with checking nr-assistant via the Application's Dependencies tab and restarting, since a stale instance connects fine but cannot build flows.
Links and anchors verified locally, including in-page anchors. npm run test:docs strips anchors and only checks file existence, so anchors were checked separately.

dimitrieh · 2026-08-24T09:21:18Z

+
+| What is needed | On FlowFuse Cloud | Self-hosted |
+| --- | --- | --- |
+| The platform MQTT broker and Team Broker | Already configured | You configure both |


for SH this depends. and is likely going to be resolved with FlowFuse/helm#1010

Now reads "Whether anything is needed from you depends on how your platform was installed" and no longer presents it as a step. Moved to the closing section, per your comment below.

We might want to check this one still in follow up reviews

dimitrieh · 2026-08-24T10:10:08Z

+}
+```
+
+### From a model provider API


For the team to consider, do we want to document this?

dimitrieh · 2026-08-24T10:11:56Z

+This differs from FlowFuse Expert, which holds every write behind an approval card of its
+own. A connected third-party agent does not use those approval cards.
+
+What does not vary is the scope you granted. FlowFuse enforces it on every call, so a


scope of the PAT or what gets assigned during the authentication

Covered: "What is always enforced by FlowFuse is what you granted, whether that came from signing in or from the scope on an access token."

States capability and permissions once instead of repeating them, drops the prerequisites framing in favour of the agent resolving version issues, and reframes the editor session as agent-guided.

dimitrieh · 2026-08-24T10:34:02Z

Reworked from the review. The structural point drove most of it: capability and permissions were restated in four places, so they are now stated once and everything else refers to that.

Prerequisites removed. No "before you start", no version checklist. Versions moved to a closing "Getting the best out of it" section that opens by saying this is not something to set up in advance, because the agent tells you what is in the way and helps resolve it. Self-hosted broker is now "depends on how your platform was installed" rather than a setup step, per FlowFuse/helm#1010.

Wording. AI agent throughout, never assistant. FlowFuse applications, and flows inside your Node-RED instances. Editing rights rather than changes. Dropped "deliberately" and "exposure"; the editor session is agent-guided, with the header control for indicating which browser session it works in. Added the point that your own agent means your own model or provider, in both this guide and the Expert index.

Softened. No-delete and manual deploy both carry "for now" plus the intent about acting as required in production and in setups where experimentation is permitted. Read access now simply has no ability to change anything. Tool annotations are described as recommended usage and permissions.

Two things to note:

I removed the model-provider API section, since your comment there was a question for the team rather than a direction. Easy to restore if the answer is yes.
The endpoint path is unchanged and still open. Both your "to be confirmed" comments stand.

dimitrieh · 2026-08-24T10:58:15Z

Up for review

…olves it

cstns · 2026-08-24T15:46:39Z

+   On FlowFuse Cloud:
+
+   ```
+   https://app.flowfuse.com/api/v1/mcp


yes, this is the final endpoint we landed on, https://app.flowfuse.com/mcp

cstns · 2026-08-24T15:48:59Z

+   Self-hosted, substitute your own platform address:
+
+   ```
+   https://flowfuse.example.com/api/v1/mcp


cstns · 2026-08-24T15:50:23Z

+register remote instances and assign them to applications, take snapshots, and build and edit
+flows.
+
+An agent with read access has no ability to change anything. FlowFuse Tables is read-only for


for the time being

cstns · 2026-08-24T15:52:18Z

+
+Asking about your platform needs nothing open. Editing flows happens in a live Node-RED
+editor, so that you can see the work as it happens on the canvas rather than receiving a
+result you have to go and check.


also because the agent is receiving the full effect of built in node-red validation and can error correct itself if it makes mistakes

cstns · 2026-08-24T15:54:13Z

+platform header there is a control for indicating which of your current browser sessions the
+agent should work in, so if you have several open you can point it at the right one. Ending
+the session, or closing the tab, ends the agent's access to your editor. Switching team also
+ends it.


this will happen automagically, we tested out instructing the agent to use/pin browser tabs via skills and worked perfectly; we just need to implement a skills tool so the agents can learn skills before they do stuff
cc @andypalmi

cstns · 2026-08-24T15:55:53Z

+
+### Command-line and editor agents
+
+Claude Code, Cursor, Visual Studio Code and Gemini CLI all connect to the same address. Where


I havent tested all of the providers yet, but the minimum requirement is for the client to have http support for mcp servers

cstns · 2026-08-24T15:57:16Z

+
+### Local and self-hosted models
+
+Use any MCP-capable client, such as LM Studio, LibreChat or Open WebUI, pointed at your own


http capable mcp-client

cstns · 2026-08-24T15:58:55Z

+Some clients authenticate with a token in a header rather than signing in. This is a property
+of the client, not of the kind of agent: both routes reach the same FlowFuse.
+
+Create a [Personal Access Token](/docs/user/user-settings/#personal-access-tokens) and


this is the intermediary step until we get oauth in, where users have to manualy create their PAT and add it in the config; once oauth kicks in users should only point their clients to the http mcp endpoint and the agent will do the rest;

I don't think we need to describe the intermediary step, the plan is to get mcp oauth in in 3.0 too

cstns · 2026-08-24T16:00:31Z

+FlowFuse tools carry their recommended usage and permissions, so a connected agent knows what
+each one is for before it calls it. Whether your agent then asks you to confirm is up to that
+agent, and it differs between them. FlowFuse Expert's own approval cards are a first-party
+feature and do not apply here.


3rd party clients should also include HITL from the get go, it was included in my video in which i recorded claude desktop asking for permission before tool execution

cstns · 2026-08-24T16:01:16Z

+agent, and it differs between them. FlowFuse Expert's own approval cards are a first-party
+feature and do not apply here.
+
+What is always enforced by FlowFuse is what you granted, whether that came from signing in or


PAT's only add an aditional layer of enforcement at team level / generic read-write

docs: add a guide for connecting your own AI agent over MCP

50b51c9

dimitrieh commented Aug 24, 2026

View reviewed changes

docs: rework the connect-your-own-agent guide from review

b908aa9

States capability and permissions once instead of repeating them, drops the prerequisites framing in favour of the agent resolving version issues, and reframes the editor session as agent-guided.

dimitrieh requested review from Steve-Mcl, andypalmi, cstns and sumitshinde-84 August 24, 2026 10:57

docs: link the MCP nodes page by its full URL so the link checker res…

229828e

…olves it

This was referenced Aug 24, 2026

/ai: one agent picker in the hero, Expert first FlowFuse/website#5670

Open

blog: connecting your own AI agent to FlowFuse FlowFuse/website#5671

Open

changelog: connect your own AI agent (3.0) FlowFuse/website#5672

Open

docs: point the MCP address at /mcp

744e623

cstns reviewed Aug 24, 2026

View reviewed changes


		### Command-line and editor agents

		Claude Code, Cursor, Visual Studio Code and Gemini CLI all connect to the same address. Where


		### Local and self-hosted models

		Use any MCP-capable client, such as LM Studio, LibreChat or Open WebUI, pointed at your own

Uh oh!

Conversation

dimitrieh commented Aug 24, 2026

Two things to confirm before merge

A gap this surfaced

Notes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dimitrieh commented Aug 24, 2026

Uh oh!

dimitrieh commented Aug 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants