From 50b51c915a42c3c20b710c7491d04fe831fa703c Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Mon, 24 Aug 2026 11:05:46 +0200 Subject: [PATCH 01/12] docs: add a guide for connecting your own AI agent over MCP --- docs/user/expert/index.md | 9 + docs/user/expert/third-party-agents.md | 314 +++++++++++++++++++++++++ 2 files changed, 323 insertions(+) create mode 100644 docs/user/expert/third-party-agents.md diff --git a/docs/user/expert/index.md b/docs/user/expert/index.md index f3d1e9d166..d0f9b14446 100644 --- a/docs/user/expert/index.md +++ b/docs/user/expert/index.md @@ -42,6 +42,15 @@ AI features within the Node-RED editor include inline code completions, flow aut [Learn more about AI in Node-RED](/docs/user/expert/node-red-embedded-ai/) +## Using Your Own AI Agent Instead + +FlowFuse Expert is not the only AI that can work your platform. FlowFuse also acts as an MCP +server, so the AI agent your team already uses, such as Microsoft Copilot, ChatGPT or Claude, +can query your teams and instances and build Node-RED applications for you. This is useful +where company policy only permits an approved AI assistant. + +[Learn more about connecting your own agent](/docs/user/expert/third-party-agents/) + ## Data Privacy No data from FlowFuse is used by third-party AI service providers for training models. diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md new file mode 100644 index 0000000000..92740e613b --- /dev/null +++ b/docs/user/expert/third-party-agents.md @@ -0,0 +1,314 @@ +--- +navTitle: Connect Your Own Agent +--- + +# Connect Your Own Agent + +FlowFuse Expert is not the only AI that can work your platform. FlowFuse also acts as an +MCP server, so the AI agent your team already uses can query your teams and instances, +and build Node-RED applications for you. + +This page covers connecting that agent, deciding what to let it do, and getting flow +building working. If your company only permits an approved AI assistant, this is how that +assistant reaches FlowFuse. + +> **Note:** This is the opposite direction to +> [MCP server nodes](/node-red/flowfuse/mcp/), which let you build an MCP server *inside* +> a flow for an agent to call. Here, FlowFuse *is* the server and your agent is the client. + +## Before you start + +Connecting takes a minute. Getting the agent to build flows depends on the instance you +point it at, so it is worth checking these first. + +| What is needed | On FlowFuse Cloud | Self-hosted | +| --- | --- | --- | +| The platform MQTT broker and Team Broker | Already configured | You configure both | +| A current launcher on the instance, or Device Agent 4.x on a remote instance | Your instance | Your instance | +| A current version of the in-editor assistant on that instance | Your instance | Your instance | + +The first row is all you need to query the platform. **Building or editing flows needs all +three.** + +On self-hosted, see +[MQTT Broker configuration](/docs/install/configuration/#mqtt-broker-configuration). AI +features also require an Enterprise licence and `ai.enabled`. + +### Check the instance before you ask for a flow + +The in-editor assistant only updates when an instance restarts. A long-running instance can +be on an older version, which means your agent will connect and answer questions about the +platform but fail to build anything. This is the most common thing to get caught by. + +To check: open the Application, select the **Dependencies** tab, and search for +`nr-assistant`. If the version looks old, or you are unsure, restart the instance before +you start. A restart is enough; you do not need to recreate anything. + +## Connect the agent + +The steps are the same whichever agent you use. Only the location of the settings changes. + +1. **Copy the FlowFuse MCP address.** + + On FlowFuse Cloud: + + ``` + https://app.flowfuse.com/api/v1/mcp + ``` + + Self-hosted, substitute your own platform address: + + ``` + https://flowfuse.example.com/api/v1/mcp + ``` + +2. **Add it in your agent's connector settings.** See + [where to add it, per agent](#where-to-add-it-per-agent) below if you are not sure where + yours lives. + +3. **Sign in to FlowFuse.** Your agent opens a normal FlowFuse sign-in. There is no key to + generate and nothing to paste. + +4. **Choose what the agent may reach.** Signing in asks which teams the agent can act on, + and whether it may make changes or only read. See + [deciding what to grant](#deciding-what-to-grant). + +Your agent can now work the platform. To let it build flows as well, continue to +[open an editor session for it](#open-an-editor-session-for-it). + +## Deciding what to grant + +Two questions, asked when you sign in. + +**Which teams.** Grant the teams the agent has a reason to touch, not all of them. If you +have a production team and a development team, granting only development means a mistaken +instruction cannot reach production, whatever you ask for. + +**Read only, or changes as well.** Read-only is worth starting with if you mainly want to +ask questions about running instances, check logs, or query your FlowFuse Tables data. +FlowFuse refuses any change from a read-only grant before it reaches an instance, so this +holds even if the agent tries. + +Grant changes when you want the agent to create applications and instances, register remote +instances, take snapshots, or build flows. + +### Changing your mind later + +Re-connect the agent and sign in again with the scopes you want. There is no separate +screen for editing what an existing connection may do. + +### What a change can and cannot be + +Nothing an agent can do through FlowFuse deletes anything. There is no tool for deleting an +instance, an application, a snapshot or a team, so a granted agent cannot remove your work +no matter how it is instructed. + +Deploying is also yours. An agent can build and edit flows, and you deploy them. + +## Open an editor session for it + +Asking about the platform needs nothing open. Building or editing flows runs against a +Node-RED editor you have deliberately exposed, so you can watch the work happen on the +canvas. + +1. Open the instance you want the agent to work in. +2. In the page header, next to the FlowFuse Expert button, select the **MCP** toggle. +3. Ask your agent to build something. It targets that session. + +Select the toggle again to end the exposure. Closing the tab also ends it, and switching +team closes the session too. + +If you have several tabs exposed at once, your agent can list them and pin the one it should +work in, so you can tell it which instance you mean. + +## What your agent can do + +**On the platform**, an agent can read your teams and applications with their activity +history, your hosted and remote instances with live status and runtime logs, your snapshots, +and your FlowFuse Tables databases including table schemas and row data. It can also see +which instance types, templates and blueprints your team has available. + +With changes granted, it can create an application, create a hosted instance, register a +remote instance and assign it to an application, and take a snapshot of a hosted or remote +instance. FlowFuse Tables stays read-only: an agent can query your data and cannot write to +it. + +**In the Node-RED editor**, an agent creates and edits flows and nodes on the canvas, reads +debug output back, and corrects its own node configuration when Node-RED rejects it. The +tools carry Node-RED's type schemas and return its validation errors, so the agent can see +what it got wrong and fix it rather than guessing. + +Editor capability is read from the connected instance when your agent connects, so exactly +what is available depends on that instance rather than on your FlowFuse version. Ask your +agent what it can do in a given instance rather than working from a fixed list. + +## Where to add it, per agent + +### Microsoft Copilot + +In **Copilot Studio**, open your agent's **Tools** page, select **Add a tool**, then **New +tool**, then **Model Context Protocol**. Give the server a name and a description that says +what it is for, since the orchestrator uses that description to decide when to call it, and +enter the FlowFuse MCP address as the server URL. + +To make FlowFuse available across a Microsoft 365 tenant rather than in a single agent, a +tenant administrator registers it in the Microsoft 365 admin center. Once approved it +appears in Copilot Studio for everyone. + +Access through Copilot Studio runs over Power Platform connectors, so any Power Platform +data policy your organisation has also governs it. + +### ChatGPT + +Custom connectors live behind developer mode. A workspace administrator enables it under +**Workspace Settings**, then **Permissions & Roles**, before anyone can add one. Then add +FlowFuse as a connector with the MCP address and sign in. + +### Claude + +Open **Settings**, then **Customize**, then **Connectors**, add a custom connector, and +enter the FlowFuse MCP address. + +On Team and Enterprise plans an owner adds the connector for the organisation first, and +then each person connects and signs in individually. + +### Command-line and editor agents + +Claude Code, Cursor, Visual Studio Code and Gemini CLI all connect to the same address. +Where a client offers a sign-in flow, use it. Where a client only accepts a header, use +[an access token](#authenticating-with-an-access-token) instead. + +For Claude Code: + +```bash +claude mcp add --transport http flowfuse https://app.flowfuse.com/api/v1/mcp +``` + +### Local and self-hosted models + +Use any MCP-capable client, such as LM Studio, LibreChat or Open WebUI, pointed at your own +model, and add the FlowFuse address as a server in that client's configuration. Note that +Ollama is a model runtime rather than an agent, so it needs an MCP-capable client in front of +it. + +## Authenticating with an access token + +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 +[scope it](/docs/user/user-settings/#scoping-a-token) to the teams the agent should reach. +Set it read-only unless the agent needs to make changes, since tokens are read-write by +default. Then send it as a bearer token. + +In a `.mcp.json` or equivalent client configuration: + +```json +{ + "mcpServers": { + "flowfuse": { + "type": "http", + "url": "https://app.flowfuse.com/api/v1/mcp", + "headers": { "Authorization": "Bearer " } + } + } +} +``` + +For Visual Studio Code, prompt for the token rather than committing it to the repository: + +```json +{ + "servers": { + "flowfuse": { + "type": "http", + "url": "https://app.flowfuse.com/api/v1/mcp", + "headers": { "Authorization": "Bearer ${input:ff_token}" } + } + }, + "inputs": [ + { + "id": "ff_token", + "type": "promptString", + "password": true, + "description": "FlowFuse access token" + } + ] +} +``` + +### From a model provider API + +If you are calling a model API directly rather than using an agent application, pass +FlowFuse as a remote MCP server. The provider connects to FlowFuse itself, so the address +has to be reachable from the internet: a local development platform will not work. + +Anthropic Messages API: + +```python +client.beta.messages.create( + model="claude-opus-5", + max_tokens=4096, + betas=["mcp-client-2025-11-20"], + mcp_servers=[{ + "type": "url", + "name": "flowfuse", + "url": "https://app.flowfuse.com/api/v1/mcp", + "authorization_token": "", + }], + tools=[{"type": "mcp_toolset", "mcp_server_name": "flowfuse"}], + messages=[{"role": "user", "content": "List my FlowFuse instances"}], +) +``` + +Both `mcp_servers` and the matching `mcp_toolset` entry are required. + +OpenAI Responses API: + +```python +client.responses.create( + model="gpt-5", + tools=[{ + "type": "mcp", + "server_label": "flowfuse", + "server_url": "https://app.flowfuse.com/api/v1/mcp", + "authorization": "", + }], + input="List my FlowFuse instances", +) +``` + +## Approvals, and who is asking + +FlowFuse marks every tool it offers as either read-only or as making a change, so a +connected agent knows before it acts. What the agent does with that is the agent's own +behaviour: some ask you to confirm a change, some do not, and it varies between them. + +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 +read-only grant is refused whatever the agent decides to try. + +Actions an agent takes appear in the +[audit log](/docs/user/logs/#ai-agents-and-api-activity), attributed to your account. + +## Troubleshooting + +**The agent connected but cannot build a flow.** The instance is almost certainly on an +older in-editor assistant. Check the Application's **Dependencies** tab for `nr-assistant` +and restart the instance. See +[check the instance before you ask for a flow](#check-the-instance-before-you-ask-for-a-flow). + +**The agent cannot see the instance I mean.** Flow and editor work needs an exposed editor +session. Open the instance and select the **MCP** toggle in the page header. If several are +exposed, ask your agent to list the sessions and pin the right one. + +**A change was refused.** The grant is read-only. Re-connect the agent and sign in again, +granting changes. + +**The agent cannot reach a team.** That team was not included when you signed in. +Re-connect and include it. + +**Nothing works on self-hosted.** Check the platform MQTT broker and Team Broker are both +configured, and that the platform has an Enterprise licence with AI enabled. From b908aa9ccc360c90451329459b2e5205dd2ccaf8 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Mon, 24 Aug 2026 12:33:20 +0200 Subject: [PATCH 02/12] docs: rework the connect-your-own-agent guide from review 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. --- docs/user/expert/index.md | 6 +- docs/user/expert/third-party-agents.md | 282 ++++++++----------------- 2 files changed, 95 insertions(+), 193 deletions(-) diff --git a/docs/user/expert/index.md b/docs/user/expert/index.md index d0f9b14446..0d2b2c7f8e 100644 --- a/docs/user/expert/index.md +++ b/docs/user/expert/index.md @@ -46,8 +46,10 @@ AI features within the Node-RED editor include inline code completions, flow aut FlowFuse Expert is not the only AI that can work your platform. FlowFuse also acts as an MCP server, so the AI agent your team already uses, such as Microsoft Copilot, ChatGPT or Claude, -can query your teams and instances and build Node-RED applications for you. This is useful -where company policy only permits an approved AI assistant. +can operate FlowFuse for you and build and edit the flows inside your Node-RED instances. + +Because the agent is yours, so is the model behind it: which model or model provider it uses +is controlled by your agent rather than by FlowFuse. [Learn more about connecting your own agent](/docs/user/expert/third-party-agents/) diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md index 92740e613b..89624720fd 100644 --- a/docs/user/expert/third-party-agents.md +++ b/docs/user/expert/third-party-agents.md @@ -4,51 +4,24 @@ navTitle: Connect Your Own Agent # Connect Your Own Agent -FlowFuse Expert is not the only AI that can work your platform. FlowFuse also acts as an -MCP server, so the AI agent your team already uses can query your teams and instances, -and build Node-RED applications for you. +FlowFuse Expert is not the only AI that can work your platform. FlowFuse also acts as an MCP +server, so the AI agent your team already uses can operate FlowFuse for you: working your +teams, applications and instances, and building and editing the flows inside your Node-RED +instances. -This page covers connecting that agent, deciding what to let it do, and getting flow -building working. If your company only permits an approved AI assistant, this is how that -assistant reaches FlowFuse. +Because the agent is yours, so is the model behind it. Which model or model provider you use +is controlled by your agent, not by FlowFuse. -> **Note:** This is the opposite direction to -> [MCP server nodes](/node-red/flowfuse/mcp/), which let you build an MCP server *inside* -> a flow for an agent to call. Here, FlowFuse *is* the server and your agent is the client. +> **Note:** This is separate from [MCP server nodes](/node-red/flowfuse/mcp/). Those let you +> build MCP servers inside your flows, connected to anything you like, to give any AI a set +> of tools of your own design. This page is about operating FlowFuse itself through MCP, +> where FlowFuse is the server and your agent is the client. -## Before you start +## Connect your agent -Connecting takes a minute. Getting the agent to build flows depends on the instance you -point it at, so it is worth checking these first. - -| What is needed | On FlowFuse Cloud | Self-hosted | -| --- | --- | --- | -| The platform MQTT broker and Team Broker | Already configured | You configure both | -| A current launcher on the instance, or Device Agent 4.x on a remote instance | Your instance | Your instance | -| A current version of the in-editor assistant on that instance | Your instance | Your instance | - -The first row is all you need to query the platform. **Building or editing flows needs all -three.** - -On self-hosted, see -[MQTT Broker configuration](/docs/install/configuration/#mqtt-broker-configuration). AI -features also require an Enterprise licence and `ai.enabled`. - -### Check the instance before you ask for a flow - -The in-editor assistant only updates when an instance restarts. A long-running instance can -be on an older version, which means your agent will connect and answer questions about the -platform but fail to build anything. This is the most common thing to get caught by. - -To check: open the Application, select the **Dependencies** tab, and search for -`nr-assistant`. If the version looks old, or you are unsure, restart the instance before -you start. A restart is enough; you do not need to recreate anything. - -## Connect the agent - -The steps are the same whichever agent you use. Only the location of the settings changes. - -1. **Copy the FlowFuse MCP address.** +1. **Add the FlowFuse MCP address in your agent's connector settings.** See + [where to add it, per agent](#where-to-add-it-per-agent) if you are not sure where yours + lives. On FlowFuse Cloud: @@ -62,101 +35,68 @@ The steps are the same whichever agent you use. Only the location of the setting https://flowfuse.example.com/api/v1/mcp ``` -2. **Add it in your agent's connector settings.** See - [where to add it, per agent](#where-to-add-it-per-agent) below if you are not sure where - yours lives. - -3. **Sign in to FlowFuse.** Your agent opens a normal FlowFuse sign-in. There is no key to - generate and nothing to paste. - -4. **Choose what the agent may reach.** Signing in asks which teams the agent can act on, - and whether it may make changes or only read. See - [deciding what to grant](#deciding-what-to-grant). - -Your agent can now work the platform. To let it build flows as well, continue to -[open an editor session for it](#open-an-editor-session-for-it). - -## Deciding what to grant - -Two questions, asked when you sign in. +2. **Sign in.** FlowFuse uses OAuth, so your agent sends you to a FlowFuse login page to + authenticate, in the same way as any other application you sign in to. -**Which teams.** Grant the teams the agent has a reason to touch, not all of them. If you -have a production team and a development team, granting only development means a mistaken -instruction cannot reach production, whatever you ask for. +3. **Choose what the agent may do.** As part of signing in you decide which teams the agent + may act on, and whether it has editing rights or read access only. -**Read only, or changes as well.** Read-only is worth starting with if you mainly want to -ask questions about running instances, check logs, or query your FlowFuse Tables data. -FlowFuse refuses any change from a read-only grant before it reaches an instance, so this -holds even if the agent tries. +Your agent can now work your platform. -Grant changes when you want the agent to create applications and instances, register remote -instances, take snapshots, or build flows. +## What your agent can do, and what you grant -### Changing your mind later +This is the one place these are described. Ask your agent what it can do in a given team or +instance if you want the current picture, since its tools reflect the instance it is +connected to. -Re-connect the agent and sign in again with the scopes you want. There is no separate -screen for editing what an existing connection may do. +**With read access**, an agent can see your teams and applications with their activity +history, your hosted and remote instances with their live status and runtime logs, your +snapshots, and your FlowFuse Tables databases including table schemas and row data. It can +also see which instance types, templates and blueprints your team has available. -### What a change can and cannot be +**With editing rights**, it can additionally create applications and hosted instances, +register remote instances and assign them to applications, take snapshots, and build and edit +flows. -Nothing an agent can do through FlowFuse deletes anything. There is no tool for deleting an -instance, an application, a snapshot or a team, so a granted agent cannot remove your work -no matter how it is instructed. +An agent with read access has no ability to change anything. FlowFuse Tables is read-only for +agents either way, so an agent can query your data to answer a question but not write to it. -Deploying is also yours. An agent can build and edit flows, and you deploy them. +### Deleting, and deploying -## Open an editor session for it +Nothing an agent can do through FlowFuse deletes anything, for now. There is no tool for +deleting an instance, an application, a snapshot or a team. Deploying is also done by you, +for the same reason. -Asking about the platform needs nothing open. Building or editing flows runs against a -Node-RED editor you have deliberately exposed, so you can watch the work happen on the -canvas. +We are focused on delivering AI in a meaningful way that can act as required both in +production setups and in setups where experimentation is permitted, so expect this to develop. -1. Open the instance you want the agent to work in. -2. In the page header, next to the FlowFuse Expert button, select the **MCP** toggle. -3. Ask your agent to build something. It targets that session. +## Editing flows -Select the toggle again to end the exposure. Closing the tab also ends it, and switching -team closes the session too. +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. -If you have several tabs exposed at once, your agent can list them and pin the one it should -work in, so you can tell it which instance you mean. - -## What your agent can do - -**On the platform**, an agent can read your teams and applications with their activity -history, your hosted and remote instances with live status and runtime logs, your snapshots, -and your FlowFuse Tables databases including table schemas and row data. It can also see -which instance types, templates and blueprints your team has available. - -With changes granted, it can create an application, create a hosted instance, register a -remote instance and assign it to an application, and take a snapshot of a hosted or remote -instance. FlowFuse Tables stays read-only: an agent can query your data and cannot write to -it. - -**In the Node-RED editor**, an agent creates and edits flows and nodes on the canvas, reads -debug output back, and corrects its own node configuration when Node-RED rejects it. The -tools carry Node-RED's type schemas and return its validation errors, so the agent can see -what it got wrong and fix it rather than guessing. - -Editor capability is read from the connected instance when your agent connects, so exactly -what is available depends on that instance rather than on your FlowFuse version. Ask your -agent what it can do in a given instance rather than working from a fixed list. +When you ask for flow work, your agent will guide you to connect an editor session. In the +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. ## Where to add it, per agent ### Microsoft Copilot In **Copilot Studio**, open your agent's **Tools** page, select **Add a tool**, then **New -tool**, then **Model Context Protocol**. Give the server a name and a description that says -what it is for, since the orchestrator uses that description to decide when to call it, and -enter the FlowFuse MCP address as the server URL. +tool**, then **Model Context Protocol**. Give the server a name and a description saying what +it is for, since the orchestrator uses that description to decide when to call it, and enter +the FlowFuse MCP address as the server URL. To make FlowFuse available across a Microsoft 365 tenant rather than in a single agent, a -tenant administrator registers it in the Microsoft 365 admin center. Once approved it -appears in Copilot Studio for everyone. +tenant administrator registers it in the Microsoft 365 admin center. Once approved it appears +in Copilot Studio for everyone. -Access through Copilot Studio runs over Power Platform connectors, so any Power Platform -data policy your organisation has also governs it. +Access through Copilot Studio runs over Power Platform connectors, so any Power Platform data +policy your organisation has also governs it. ### ChatGPT @@ -166,16 +106,16 @@ FlowFuse as a connector with the MCP address and sign in. ### Claude -Open **Settings**, then **Customize**, then **Connectors**, add a custom connector, and -enter the FlowFuse MCP address. +Open **Settings**, then **Customize**, then **Connectors**, add a custom connector, and enter +the FlowFuse MCP address. -On Team and Enterprise plans an owner adds the connector for the organisation first, and -then each person connects and signs in individually. +On Team and Enterprise plans an owner adds the connector for the organisation first, and then +each person connects and signs in individually. ### Command-line and editor agents -Claude Code, Cursor, Visual Studio Code and Gemini CLI all connect to the same address. -Where a client offers a sign-in flow, use it. Where a client only accepts a header, use +Claude Code, Cursor, Visual Studio Code and Gemini CLI all connect to the same address. Where +a client offers a sign-in flow, use it. Where a client only accepts a header, use [an access token](#authenticating-with-an-access-token) instead. For Claude Code: @@ -193,15 +133,12 @@ it. ## Authenticating with an access token -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. +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 -[scope it](/docs/user/user-settings/#scoping-a-token) to the teams the agent should reach. -Set it read-only unless the agent needs to make changes, since tokens are read-write by -default. Then send it as a bearer token. - -In a `.mcp.json` or equivalent client configuration: +[scope it](/docs/user/user-settings/#scoping-a-token) the same way you would when signing in. +Then send it as a bearer token: ```json { @@ -237,78 +174,41 @@ For Visual Studio Code, prompt for the token rather than committing it to the re } ``` -### From a model provider API - -If you are calling a model API directly rather than using an agent application, pass -FlowFuse as a remote MCP server. The provider connects to FlowFuse itself, so the address -has to be reachable from the internet: a local development platform will not work. - -Anthropic Messages API: - -```python -client.beta.messages.create( - model="claude-opus-5", - max_tokens=4096, - betas=["mcp-client-2025-11-20"], - mcp_servers=[{ - "type": "url", - "name": "flowfuse", - "url": "https://app.flowfuse.com/api/v1/mcp", - "authorization_token": "", - }], - tools=[{"type": "mcp_toolset", "mcp_server_name": "flowfuse"}], - messages=[{"role": "user", "content": "List my FlowFuse instances"}], -) -``` - -Both `mcp_servers` and the matching `mcp_toolset` entry are required. - -OpenAI Responses API: - -```python -client.responses.create( - model="gpt-5", - tools=[{ - "type": "mcp", - "server_label": "flowfuse", - "server_url": "https://app.flowfuse.com/api/v1/mcp", - "authorization": "", - }], - input="List my FlowFuse instances", -) -``` - -## Approvals, and who is asking +## Approvals and audit -FlowFuse marks every tool it offers as either read-only or as making a change, so a -connected agent knows before it acts. What the agent does with that is the agent's own -behaviour: some ask you to confirm a change, some do not, and it varies between them. +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. -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 -read-only grant is refused whatever the agent decides to try. +What is always enforced by FlowFuse is what you granted, whether that came from signing in or +from the scope on an access token. Actions an agent takes appear in the [audit log](/docs/user/logs/#ai-agents-and-api-activity), attributed to your account. -## Troubleshooting +## If something is not working + +**A change was refused.** The agent has read access only. Re-connect it and grant editing +rights. + +**The agent cannot reach a team.** That team was not included when you signed in. Re-connect +and include it. -**The agent connected but cannot build a flow.** The instance is almost certainly on an -older in-editor assistant. Check the Application's **Dependencies** tab for `nr-assistant` -and restart the instance. See -[check the instance before you ask for a flow](#check-the-instance-before-you-ask-for-a-flow). +**The agent cannot see the instance you mean.** Flow and editor work runs in a connected +editor session. Ask your agent to list your sessions and connect to the right one. -**The agent cannot see the instance I mean.** Flow and editor work needs an exposed editor -session. Open the instance and select the **MCP** toggle in the page header. If several are -exposed, ask your agent to list the sessions and pin the right one. +## Getting the best out of it -**A change was refused.** The grant is read-only. Re-connect the agent and sign in again, -granting changes. +None of this is something to set up before you start. Your agent will tell you when +something is in the way, and can help resolve it. -**The agent cannot reach a team.** That team was not included when you signed in. -Re-connect and include it. +For the smoothest experience, an instance the agent works in should be on a current launcher +or Device Agent, with a current in-editor assistant. These update when an instance restarts, +so a long-running instance may be behind. If an agent cannot do something you expected in a +particular instance, this is usually why, and asking the agent about it is the quickest route. -**Nothing works on self-hosted.** Check the platform MQTT broker and Team Broker are both -configured, and that the platform has an Enterprise licence with AI enabled. +On self-hosted, platform messaging runs over the MQTT broker, so the Team Broker needs to be +available. Whether anything is needed from you depends on how your platform was installed; +see [MQTT Broker configuration](/docs/install/configuration/#mqtt-broker-configuration). AI +features also require an Enterprise licence with AI enabled. From 229828e85c29cf1fe21ceadd45f2d8a7564b0866 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Mon, 24 Aug 2026 13:00:15 +0200 Subject: [PATCH 03/12] docs: link the MCP nodes page by its full URL so the link checker resolves it --- docs/user/expert/third-party-agents.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md index 89624720fd..cfc861dc36 100644 --- a/docs/user/expert/third-party-agents.md +++ b/docs/user/expert/third-party-agents.md @@ -12,10 +12,11 @@ instances. Because the agent is yours, so is the model behind it. Which model or model provider you use is controlled by your agent, not by FlowFuse. -> **Note:** This is separate from [MCP server nodes](/node-red/flowfuse/mcp/). Those let you -> build MCP servers inside your flows, connected to anything you like, to give any AI a set -> of tools of your own design. This page is about operating FlowFuse itself through MCP, -> where FlowFuse is the server and your agent is the client. +> **Note:** This is separate from +> [MCP server nodes](https://flowfuse.com/node-red/flowfuse/mcp/). Those let you build MCP +> servers inside your flows, connected to anything you like, to give any AI a set of tools of +> your own design. This page is about operating FlowFuse itself through MCP, where FlowFuse +> is the server and your agent is the client. ## Connect your agent From 744e6231f5a8b7659bfc9978c9183b057e13cff8 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Mon, 24 Aug 2026 17:54:30 +0200 Subject: [PATCH 04/12] docs: point the MCP address at /mcp --- docs/user/expert/third-party-agents.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md index cfc861dc36..ed1f28a4c4 100644 --- a/docs/user/expert/third-party-agents.md +++ b/docs/user/expert/third-party-agents.md @@ -27,13 +27,13 @@ is controlled by your agent, not by FlowFuse. On FlowFuse Cloud: ``` - https://app.flowfuse.com/api/v1/mcp + https://app.flowfuse.com/mcp ``` Self-hosted, substitute your own platform address: ``` - https://flowfuse.example.com/api/v1/mcp + https://flowfuse.example.com/mcp ``` 2. **Sign in.** FlowFuse uses OAuth, so your agent sends you to a FlowFuse login page to @@ -122,7 +122,7 @@ a client offers a sign-in flow, use it. Where a client only accepts a header, us For Claude Code: ```bash -claude mcp add --transport http flowfuse https://app.flowfuse.com/api/v1/mcp +claude mcp add --transport http flowfuse https://app.flowfuse.com/mcp ``` ### Local and self-hosted models @@ -146,7 +146,7 @@ Then send it as a bearer token: "mcpServers": { "flowfuse": { "type": "http", - "url": "https://app.flowfuse.com/api/v1/mcp", + "url": "https://app.flowfuse.com/mcp", "headers": { "Authorization": "Bearer " } } } @@ -160,7 +160,7 @@ For Visual Studio Code, prompt for the token rather than committing it to the re "servers": { "flowfuse": { "type": "http", - "url": "https://app.flowfuse.com/api/v1/mcp", + "url": "https://app.flowfuse.com/mcp", "headers": { "Authorization": "Bearer ${input:ff_token}" } } }, From 8a3fe497fdb01abb13e618208e08e404a89016a0 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Wed, 26 Aug 2026 11:22:41 +0200 Subject: [PATCH 05/12] docs: keep the token route as the fallback, and answer the review OAuth is stated as the intended route and the token route is kept for the clients that cannot sign in, split into the two shapes that actually exist: a header, and a local command via mcp-remote for Claude Desktop. Also from review: HTTP MCP support is the real requirement rather than a named provider list, Tables is read-only through the platform tools for the time being but a flow with a Query Node still writes, the agent gets Node-RED validation back and self-corrects, clients supply their own confirmation prompt, and enforcement granularity is teams plus read or write rather than per-tool. --- docs/user/expert/third-party-agents.md | 99 ++++++++++++++++++++------ 1 file changed, 78 insertions(+), 21 deletions(-) diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md index ed1f28a4c4..07b1a5e489 100644 --- a/docs/user/expert/third-party-agents.md +++ b/docs/user/expert/third-party-agents.md @@ -20,6 +20,8 @@ is controlled by your agent, not by FlowFuse. ## Connect your agent +Any MCP client that speaks HTTP can connect. That is the only requirement. + 1. **Add the FlowFuse MCP address in your agent's connector settings.** See [where to add it, per agent](#where-to-add-it-per-agent) if you are not sure where yours lives. @@ -37,12 +39,15 @@ is controlled by your agent, not by FlowFuse. ``` 2. **Sign in.** FlowFuse uses OAuth, so your agent sends you to a FlowFuse login page to - authenticate, in the same way as any other application you sign in to. + authenticate, in the same way as any other application you sign in to. If your client asks + for an OAuth client ID or secret, leave them blank. FlowFuse registers your client for you. 3. **Choose what the agent may do.** As part of signing in you decide which teams the agent may act on, and whether it has editing rights or read access only. -Your agent can now work your platform. +Your agent can now work your platform. Signing in is the intended route. A few clients cannot +do it and take a token in a header instead, which is covered in +[connecting a client that cannot sign in](#connecting-a-client-that-cannot-sign-in). ## What your agent can do, and what you grant @@ -59,8 +64,13 @@ also see which instance types, templates and blueprints your team has available. 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 -agents either way, so an agent can query your data to answer a question but not write to it. +An agent with read access has no ability to change anything. + +FlowFuse Tables is read-only through the platform tools, for the time being, so an agent can +query your data to answer a question but not write to it directly. A flow is a different +route. An agent with editing rights can build a flow containing a +[Query Node](/docs/user/ff-tables/#query-nodes), and that flow writes to your tables like any +other flow you would have written yourself. ### Deleting, and deploying @@ -75,7 +85,9 @@ production setups and in setups where experimentation is permitted, so expect th 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. +result you have to go and check. Working in the running editor also means the agent gets +Node-RED's own validation back as it goes, so it catches and corrects its own mistakes rather +than handing you a flow that will not load. When you ask for flow work, your agent will guide you to connect an editor session. In the platform header there is a control for indicating which of your current browser sessions the @@ -85,6 +97,9 @@ ends it. ## Where to add it, per agent +The agents below are the common ones and where their settings live. Anything else that speaks +MCP over HTTP connects in the same way. + ### Microsoft Copilot In **Copilot Studio**, open your agent's **Tools** page, select **Add a tool**, then **New @@ -116,8 +131,8 @@ each person connects and signs in individually. ### Command-line and editor agents Claude Code, Cursor, Visual Studio Code and Gemini CLI all connect to the same address. Where -a client offers a sign-in flow, use it. Where a client only accepts a header, use -[an access token](#authenticating-with-an-access-token) instead. +a client offers a sign-in flow, use it. Where it does not, see +[connecting a client that cannot sign in](#connecting-a-client-that-cannot-sign-in). For Claude Code: @@ -127,19 +142,24 @@ claude mcp add --transport http flowfuse https://app.flowfuse.com/mcp ### Local and self-hosted models -Use any MCP-capable client, such as LM Studio, LibreChat or Open WebUI, pointed at your own -model, and add the FlowFuse address as a server in that client's configuration. Note that -Ollama is a model runtime rather than an agent, so it needs an MCP-capable client in front of -it. +Use any HTTP-capable MCP client, such as LM Studio, LibreChat or Open WebUI, pointed at your +own model, and add the FlowFuse address as a server in that client's configuration. Note that +Ollama is a model runtime rather than an agent, so it needs an MCP client in front of it. -## Authenticating with an access token +## Connecting a client that cannot sign in -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. +Signing in is the intended route, and the one to use wherever your client supports it. A few +clients do not: they take a token in a header instead, or their configuration file only +accepts a local command rather than an address. This is a property of the client, not of the +kind of agent, and both routes reach the same FlowFuse with the same enforcement. Create a [Personal Access Token](/docs/user/user-settings/#personal-access-tokens) and [scope it](/docs/user/user-settings/#scoping-a-token) the same way you would when signing in. -Then send it as a bearer token: +Scope it to the team you want the agent working in rather than to everything you can reach. + +### Clients that take a header + +Claude Code, Cursor and Visual Studio Code take the address and the header directly: ```json { @@ -175,18 +195,55 @@ For Visual Studio Code, prompt for the token rather than committing it to the re } ``` +### Clients whose configuration file takes a local command + +Claude Desktop is the common one. Its configuration file accepts a command to run rather than +an address to call, so the connection goes through `mcp-remote`, which talks to FlowFuse over +HTTP on the client's behalf. Add this alongside whatever the file already contains: + +```json +{ + "mcpServers": { + "flowfuse": { + "command": "npx", + "args": [ + "-y", + "mcp-remote", + "https://app.flowfuse.com/mcp", + "--header", + "Authorization:${AUTH_HEADER}" + ], + "env": { + "AUTH_HEADER": "Bearer " + } + } + } +} +``` + +The token sits in `env` and the header argument has no space in it on purpose. Some clients do +not escape spaces when they launch the command, which mangles the value if you write +`Bearer ` into `args` directly. + +The file lives at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, +and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. + ## Approvals and audit 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. +each one is for before it calls it. Most MCP clients then ask you to confirm before they run a +tool. That prompt belongs to the client rather than to FlowFuse, so how it looks, and whether +you can turn it off, 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 -from the scope on an access token. +What FlowFuse enforces on every call is what you granted: the teams, and read access or +editing rights. That is the granularity. It is a boundary around what an agent can reach +rather than a per-tool allow list, and it applies the same way whether the grant came from +signing in or from the scope on an access token. Actions an agent takes appear in the -[audit log](/docs/user/logs/#ai-agents-and-api-activity), attributed to your account. +[audit log](/docs/user/logs/#ai-agents-and-api-activity), attributed to your account and +marked as having come from a connected agent. ## If something is not working From 7a97136861b4e47ebd3033ac514c70fb485944f5 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Wed, 26 Aug 2026 11:22:43 +0200 Subject: [PATCH 06/12] docs: describe third-party agent activity in the audit log The page said the logs covered FlowFuse Expert and API actions only. A connected agent carries the same sparkle icon, distinguished by the hover label: via Expert for the first party, via MCP for your own agent. --- docs/user/logs.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user/logs.md b/docs/user/logs.md index 621aeac63e..cb7ddb900b 100644 --- a/docs/user/logs.md +++ b/docs/user/logs.md @@ -53,11 +53,11 @@ This log contains all events since the team was created. Tou can view older data ### AI Agents and API Activity -For actions performed through FlowFuse Expert or the FlowFuse platform API, both this log and the instance/application-level [Audit Log](#audit-log) show an icon indicating how the action was performed: +For actions performed by an AI agent or through the FlowFuse platform API, both this log and the instance/application-level [Audit Log](#audit-log) show an icon indicating how the action was performed: -- A sparkle icon means the action was performed by FlowFuse Expert on the user's behalf. Hovering over the icon shows the name of the tool that was called. +- A sparkle icon means an AI agent performed the action on the user's behalf. Hovering over the icon says which agent and names the tool that was called: "via Expert" for FlowFuse Expert, and "via MCP" for [your own connected agent](/docs/user/expert/third-party-agents/). - A terminal icon means the action was performed through the FlowFuse API using a [Personal Access Token](./user-settings.md#personal-access-tokens). Actions performed directly through the FlowFuse UI do not show an icon. -These logs provide visibility into supported FlowFuse Expert and API actions only. +These logs provide visibility into supported AI agent and API actions only. From 4963e03977a8dc10aad541db877eb4d29bae3dfd Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Wed, 26 Aug 2026 11:42:27 +0200 Subject: [PATCH 07/12] docs: lead the sign-in fallback with the desktop assistant, not editor tooling The fallback is for the reader whose approved assistant cannot sign in, so that shape goes first. The editor and command-line config, which is the technically simpler one, follows it rather than framing the section. --- docs/user/expert/third-party-agents.md | 68 +++++++++++++------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md index 07b1a5e489..57ba639e3b 100644 --- a/docs/user/expert/third-party-agents.md +++ b/docs/user/expert/third-party-agents.md @@ -157,9 +157,42 @@ Create a [Personal Access Token](/docs/user/user-settings/#personal-access-token [scope it](/docs/user/user-settings/#scoping-a-token) the same way you would when signing in. Scope it to the team you want the agent working in rather than to everything you can reach. +### Clients whose configuration file takes a local command + +Claude Desktop is the common one. Its configuration file accepts a command to run rather than +an address to call, so the connection goes through `mcp-remote`, which talks to FlowFuse over +HTTP on the client's behalf. Add this alongside whatever the file already contains: + +```json +{ + "mcpServers": { + "flowfuse": { + "command": "npx", + "args": [ + "-y", + "mcp-remote", + "https://app.flowfuse.com/mcp", + "--header", + "Authorization:${AUTH_HEADER}" + ], + "env": { + "AUTH_HEADER": "Bearer " + } + } + } +} +``` + +The token sits in `env` and the header argument has no space in it on purpose. Some clients do +not escape spaces when they launch the command, which mangles the value if you write +`Bearer ` into `args` directly. + +The file lives at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, +and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. + ### Clients that take a header -Claude Code, Cursor and Visual Studio Code take the address and the header directly: +Editor and command-line agents generally take the address and the header directly: ```json { @@ -195,39 +228,6 @@ For Visual Studio Code, prompt for the token rather than committing it to the re } ``` -### Clients whose configuration file takes a local command - -Claude Desktop is the common one. Its configuration file accepts a command to run rather than -an address to call, so the connection goes through `mcp-remote`, which talks to FlowFuse over -HTTP on the client's behalf. Add this alongside whatever the file already contains: - -```json -{ - "mcpServers": { - "flowfuse": { - "command": "npx", - "args": [ - "-y", - "mcp-remote", - "https://app.flowfuse.com/mcp", - "--header", - "Authorization:${AUTH_HEADER}" - ], - "env": { - "AUTH_HEADER": "Bearer " - } - } - } -} -``` - -The token sits in `env` and the header argument has no space in it on purpose. Some clients do -not escape spaces when they launch the command, which mangles the value if you write -`Bearer ` into `args` directly. - -The file lives at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, -and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. - ## Approvals and audit FlowFuse tools carry their recommended usage and permissions, so a connected agent knows what From f6180408bcdbacca27ceecb587609f3c23169a96 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Thu, 27 Aug 2026 14:47:19 +0200 Subject: [PATCH 08/12] Update docs/user/expert/third-party-agents.md Co-authored-by: Andrea Palmieri <76187074+andypalmi@users.noreply.github.com> --- docs/user/expert/third-party-agents.md | 33 -------------------------- 1 file changed, 33 deletions(-) diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md index 57ba639e3b..b49911a438 100644 --- a/docs/user/expert/third-party-agents.md +++ b/docs/user/expert/third-party-agents.md @@ -157,39 +157,6 @@ Create a [Personal Access Token](/docs/user/user-settings/#personal-access-token [scope it](/docs/user/user-settings/#scoping-a-token) the same way you would when signing in. Scope it to the team you want the agent working in rather than to everything you can reach. -### Clients whose configuration file takes a local command - -Claude Desktop is the common one. Its configuration file accepts a command to run rather than -an address to call, so the connection goes through `mcp-remote`, which talks to FlowFuse over -HTTP on the client's behalf. Add this alongside whatever the file already contains: - -```json -{ - "mcpServers": { - "flowfuse": { - "command": "npx", - "args": [ - "-y", - "mcp-remote", - "https://app.flowfuse.com/mcp", - "--header", - "Authorization:${AUTH_HEADER}" - ], - "env": { - "AUTH_HEADER": "Bearer " - } - } - } -} -``` - -The token sits in `env` and the header argument has no space in it on purpose. Some clients do -not escape spaces when they launch the command, which mangles the value if you write -`Bearer ` into `args` directly. - -The file lives at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, -and `%APPDATA%\Claude\claude_desktop_config.json` on Windows. - ### Clients that take a header Editor and command-line agents generally take the address and the header directly: From 092036188f3600c28ecd6710ec64af7366dd38db Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Thu, 27 Aug 2026 14:54:14 +0200 Subject: [PATCH 09/12] docs: cut the token route to a mention, and move the MCP nodes note below the steps --- docs/user/expert/third-party-agents.md | 80 ++++++++------------------ 1 file changed, 25 insertions(+), 55 deletions(-) diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md index b49911a438..a4a41bde39 100644 --- a/docs/user/expert/third-party-agents.md +++ b/docs/user/expert/third-party-agents.md @@ -12,12 +12,6 @@ instances. Because the agent is yours, so is the model behind it. Which model or model provider you use is controlled by your agent, not by FlowFuse. -> **Note:** This is separate from -> [MCP server nodes](https://flowfuse.com/node-red/flowfuse/mcp/). Those let you build MCP -> servers inside your flows, connected to anything you like, to give any AI a set of tools of -> your own design. This page is about operating FlowFuse itself through MCP, where FlowFuse -> is the server and your agent is the client. - ## Connect your agent Any MCP client that speaks HTTP can connect. That is the only requirement. @@ -45,9 +39,15 @@ Any MCP client that speaks HTTP can connect. That is the only requirement. 3. **Choose what the agent may do.** As part of signing in you decide which teams the agent may act on, and whether it has editing rights or read access only. -Your agent can now work your platform. Signing in is the intended route. A few clients cannot -do it and take a token in a header instead, which is covered in -[connecting a client that cannot sign in](#connecting-a-client-that-cannot-sign-in). +Your agent can now work your platform. Signing in is the intended route. A client that has no +sign-in flow takes a token instead, which is covered in +[clients without a sign-in flow](#clients-without-a-sign-in-flow). + +> **Note:** This is separate from +> [MCP server nodes](https://flowfuse.com/node-red/flowfuse/mcp/). Those let you build MCP +> servers inside your flows, connected to anything you like, to give any AI a set of tools of +> your own design. This page is about operating FlowFuse itself through MCP, where FlowFuse +> is the server and your agent is the client. ## What your agent can do, and what you grant @@ -132,7 +132,7 @@ each person connects and signs in individually. Claude Code, Cursor, Visual Studio Code and Gemini CLI all connect to the same address. Where a client offers a sign-in flow, use it. Where it does not, see -[connecting a client that cannot sign in](#connecting-a-client-that-cannot-sign-in). +[clients without a sign-in flow](#clients-without-a-sign-in-flow). For Claude Code: @@ -146,54 +146,24 @@ Use any HTTP-capable MCP client, such as LM Studio, LibreChat or Open WebUI, poi own model, and add the FlowFuse address as a server in that client's configuration. Note that Ollama is a model runtime rather than an agent, so it needs an MCP client in front of it. -## Connecting a client that cannot sign in +## Clients without a sign-in flow -Signing in is the intended route, and the one to use wherever your client supports it. A few -clients do not: they take a token in a header instead, or their configuration file only -accepts a local command rather than an address. This is a property of the client, not of the -kind of agent, and both routes reach the same FlowFuse with the same enforcement. +Signing in is the intended route, and the one to use wherever your client supports it. A client +that has no sign-in flow takes a token in its configuration file instead. Both routes reach the +same FlowFuse with the same enforcement. Create a [Personal Access Token](/docs/user/user-settings/#personal-access-tokens) and -[scope it](/docs/user/user-settings/#scoping-a-token) the same way you would when signing in. -Scope it to the team you want the agent working in rather than to everything you can reach. - -### Clients that take a header - -Editor and command-line agents generally take the address and the header directly: - -```json -{ - "mcpServers": { - "flowfuse": { - "type": "http", - "url": "https://app.flowfuse.com/mcp", - "headers": { "Authorization": "Bearer " } - } - } -} -``` - -For Visual Studio Code, prompt for the token rather than committing it to the repository: - -```json -{ - "servers": { - "flowfuse": { - "type": "http", - "url": "https://app.flowfuse.com/mcp", - "headers": { "Authorization": "Bearer ${input:ff_token}" } - } - }, - "inputs": [ - { - "id": "ff_token", - "type": "promptString", - "password": true, - "description": "FlowFuse access token" - } - ] -} -``` +[scope it](/docs/user/user-settings/#scoping-a-token) the same way you would when signing in, +to the team you want the agent working in rather than to everything you can reach. Then give +the client the FlowFuse address together with that token as a bearer token in an +`Authorization` header. + +How that is written down belongs to the client rather than to FlowFuse. Two JSON shapes are in +common use, one keyed on `servers` and one keyed on `mcpServers`, and clients also differ on +where the file lives and whether they accept headers at all, so follow your own client's +configuration reference. For the two shapes, see the +[`servers` reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) +and the [`mcpServers` reference](https://modelcontextprotocol.io/docs/develop/connect-local-servers). ## Approvals and audit From 4026476359ae7f1663e031d2d361a29b7d15a8eb Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Thu, 27 Aug 2026 15:30:56 +0200 Subject: [PATCH 10/12] docs: slim the Expert index section and take the HTTP transport wording --- docs/user/expert/index.md | 9 ++------- docs/user/expert/third-party-agents.md | 6 +++--- 2 files changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/user/expert/index.md b/docs/user/expert/index.md index 0d2b2c7f8e..3d4cbbb482 100644 --- a/docs/user/expert/index.md +++ b/docs/user/expert/index.md @@ -42,14 +42,9 @@ AI features within the Node-RED editor include inline code completions, flow aut [Learn more about AI in Node-RED](/docs/user/expert/node-red-embedded-ai/) -## Using Your Own AI Agent Instead +## Using Your Own AI Agent -FlowFuse Expert is not the only AI that can work your platform. FlowFuse also acts as an MCP -server, so the AI agent your team already uses, such as Microsoft Copilot, ChatGPT or Claude, -can operate FlowFuse for you and build and edit the flows inside your Node-RED instances. - -Because the agent is yours, so is the model behind it: which model or model provider it uses -is controlled by your agent rather than by FlowFuse. +Connect your own AI agent, such as Microsoft Copilot, ChatGPT or Claude, to manage your platform and build and edit flows in your Node-RED instances. [Learn more about connecting your own agent](/docs/user/expert/third-party-agents/) diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md index a4a41bde39..f4b023d885 100644 --- a/docs/user/expert/third-party-agents.md +++ b/docs/user/expert/third-party-agents.md @@ -14,7 +14,7 @@ is controlled by your agent, not by FlowFuse. ## Connect your agent -Any MCP client that speaks HTTP can connect. That is the only requirement. +Any MCP client that supports the HTTP transport can connect. That is the only requirement. 1. **Add the FlowFuse MCP address in your agent's connector settings.** See [where to add it, per agent](#where-to-add-it-per-agent) if you are not sure where yours @@ -97,8 +97,8 @@ ends it. ## Where to add it, per agent -The agents below are the common ones and where their settings live. Anything else that speaks -MCP over HTTP connects in the same way. +The agents below are the common ones and where their settings live. Every other AI Agent that +supports MCP over HTTP connects the same way. ### Microsoft Copilot From 04fd066e356a82b9957166bde72125933cfff3c1 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Thu, 27 Aug 2026 15:34:15 +0200 Subject: [PATCH 11/12] docs: take the review suggestions, and unwrap prose to one line per paragraph --- docs/user/expert/third-party-agents.md | 156 ++++++------------------- 1 file changed, 38 insertions(+), 118 deletions(-) diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md index f4b023d885..dce7bbfd10 100644 --- a/docs/user/expert/third-party-agents.md +++ b/docs/user/expert/third-party-agents.md @@ -4,21 +4,17 @@ navTitle: Connect Your Own Agent # Connect Your Own Agent -FlowFuse Expert is not the only AI that can work your platform. FlowFuse also acts as an MCP -server, so the AI agent your team already uses can operate FlowFuse for you: working your -teams, applications and instances, and building and editing the flows inside your Node-RED -instances. +**Introduced in FlowFuse 3.0** -Because the agent is yours, so is the model behind it. Which model or model provider you use -is controlled by your agent, not by FlowFuse. +You can connect your own AI agent to FlowFuse. The agent your team already uses can manage your platform and build and edit the flows inside your Node-RED instances. + +Because the agent is yours, so is the model it runs on. ## Connect your agent Any MCP client that supports the HTTP transport can connect. That is the only requirement. -1. **Add the FlowFuse MCP address in your agent's connector settings.** See - [where to add it, per agent](#where-to-add-it-per-agent) if you are not sure where yours - lives. +1. **Add the FlowFuse MCP address in your agent's connector settings.** See [where to add it, per agent](#where-to-add-it-per-agent) if you are not sure where yours lives. On FlowFuse Cloud: @@ -32,107 +28,63 @@ Any MCP client that supports the HTTP transport can connect. That is the only re https://flowfuse.example.com/mcp ``` -2. **Sign in.** FlowFuse uses OAuth, so your agent sends you to a FlowFuse login page to - authenticate, in the same way as any other application you sign in to. If your client asks - for an OAuth client ID or secret, leave them blank. FlowFuse registers your client for you. +2. **Sign in.** FlowFuse uses OAuth, so your agent sends you to a FlowFuse login page to authenticate, in the same way as any other application you sign in to. If your client asks for an OAuth client ID or secret, leave them blank. FlowFuse registers your client for you. -3. **Choose what the agent may do.** As part of signing in you decide which teams the agent - may act on, and whether it has editing rights or read access only. +3. **Choose what the agent may do.** As part of signing in you decide which teams the agent may act on, and whether it has editing rights or read access only. -Your agent can now work your platform. Signing in is the intended route. A client that has no -sign-in flow takes a token instead, which is covered in -[clients without a sign-in flow](#clients-without-a-sign-in-flow). +Your agent is now connected. OAuth lets you connect by signing in. If your MCP client does not support OAuth, use a token instead, covered in [clients without a sign-in flow](#clients-without-a-sign-in-flow). -> **Note:** This is separate from -> [MCP server nodes](https://flowfuse.com/node-red/flowfuse/mcp/). Those let you build MCP -> servers inside your flows, connected to anything you like, to give any AI a set of tools of -> your own design. This page is about operating FlowFuse itself through MCP, where FlowFuse -> is the server and your agent is the client. +> **Note:** This is separate from [MCP server nodes](https://flowfuse.com/node-red/flowfuse/mcp/). Those let you build MCP servers inside your flows, connected to anything you like, to give any AI a set of tools of your own design. This page is about operating FlowFuse itself through MCP, where FlowFuse is the server and your agent is the client. ## What your agent can do, and what you grant -This is the one place these are described. Ask your agent what it can do in a given team or -instance if you want the current picture, since its tools reflect the instance it is -connected to. +Ask your agent what it can do in a given team or instance if you want the current picture, since its tools reflect the instance it is connected to. -**With read access**, an agent can see your teams and applications with their activity -history, your hosted and remote instances with their live status and runtime logs, your -snapshots, and your FlowFuse Tables databases including table schemas and row data. It can -also see which instance types, templates and blueprints your team has available. +**With read access**, an agent can see your teams and applications with their activity history, your hosted and remote instances with their live status and runtime logs, your snapshots, and your FlowFuse Tables databases including table schemas and row data. It can also see which instance types, templates and blueprints your team has available. -**With editing rights**, it can additionally create applications and hosted instances, -register remote instances and assign them to applications, take snapshots, and build and edit -flows. +**With editing rights**, it can additionally create applications and hosted instances, 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 through the platform tools, for the time being, so an agent can -query your data to answer a question but not write to it directly. A flow is a different -route. An agent with editing rights can build a flow containing a -[Query Node](/docs/user/ff-tables/#query-nodes), and that flow writes to your tables like any -other flow you would have written yourself. +FlowFuse Tables is read-only through the platform tools, for the time being, so an agent can query your data to answer a question but not write to it directly. A flow is a different route. An agent with editing rights can build a flow containing a [Query Node](/docs/user/ff-tables/#query-nodes), and that flow writes to your tables like any other flow you would have written yourself. ### Deleting, and deploying -Nothing an agent can do through FlowFuse deletes anything, for now. There is no tool for -deleting an instance, an application, a snapshot or a team. Deploying is also done by you, -for the same reason. +Nothing an agent can do through FlowFuse deletes anything, for now. There is no tool for deleting an instance, an application, a snapshot or a team. Deploying is also done by you, for the same reason. -We are focused on delivering AI in a meaningful way that can act as required both in -production setups and in setups where experimentation is permitted, so expect this to develop. +We are focused on delivering AI in a meaningful way that can act as required both in production setups and in setups where experimentation is permitted, so expect this to develop. ## Editing flows -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. Working in the running editor also means the agent gets -Node-RED's own validation back as it goes, so it catches and corrects its own mistakes rather -than handing you a flow that will not load. +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. Working in the running editor also means the agent gets Node-RED's own validation back as it goes, so it catches and corrects its own mistakes rather than handing you a flow that will not load. -When you ask for flow work, your agent will guide you to connect an editor session. In the -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. +When you ask for flow work, your agent will guide you to connect an editor session. In the 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. ## Where to add it, per agent -The agents below are the common ones and where their settings live. Every other AI Agent that -supports MCP over HTTP connects the same way. +The agents below are the common ones and where their settings live. Every other AI Agent that supports MCP over HTTP connects the same way. ### Microsoft Copilot -In **Copilot Studio**, open your agent's **Tools** page, select **Add a tool**, then **New -tool**, then **Model Context Protocol**. Give the server a name and a description saying what -it is for, since the orchestrator uses that description to decide when to call it, and enter -the FlowFuse MCP address as the server URL. +In **Copilot Studio**, open your agent's **Tools** page, select **Add a tool**, then **New tool**, then **Model Context Protocol**. Give the server a name and a description saying what it is for, since the orchestrator uses that description to decide when to call it, and enter the FlowFuse MCP address as the server URL. -To make FlowFuse available across a Microsoft 365 tenant rather than in a single agent, a -tenant administrator registers it in the Microsoft 365 admin center. Once approved it appears -in Copilot Studio for everyone. +To make FlowFuse available across a Microsoft 365 tenant rather than in a single agent, a tenant administrator registers it in the Microsoft 365 admin center. Once approved it appears in Copilot Studio for everyone. -Access through Copilot Studio runs over Power Platform connectors, so any Power Platform data -policy your organisation has also governs it. +Access through Copilot Studio runs over Power Platform connectors, so any Power Platform data policy your organisation has also governs it. ### ChatGPT -Custom connectors live behind developer mode. A workspace administrator enables it under -**Workspace Settings**, then **Permissions & Roles**, before anyone can add one. Then add -FlowFuse as a connector with the MCP address and sign in. +Custom connectors live behind developer mode. A workspace administrator enables it under **Workspace Settings**, then **Permissions & Roles**, before anyone can add one. Then add FlowFuse as a connector with the MCP address and sign in. ### Claude -Open **Settings**, then **Customize**, then **Connectors**, add a custom connector, and enter -the FlowFuse MCP address. +Open **Settings**, then **Customize**, then **Connectors**, add a custom connector, and enter the FlowFuse MCP address. -On Team and Enterprise plans an owner adds the connector for the organisation first, and then -each person connects and signs in individually. +On Team and Enterprise plans an owner adds the connector for the organisation first, and then each person connects and signs in individually. ### Command-line and editor agents -Claude Code, Cursor, Visual Studio Code and Gemini CLI all connect to the same address. Where -a client offers a sign-in flow, use it. Where it does not, see -[clients without a sign-in flow](#clients-without-a-sign-in-flow). +Claude Code, Cursor, Visual Studio Code and Gemini CLI all connect to the same address. Where a client offers a sign-in flow, use it. Where it does not, see [clients without a sign-in flow](#clients-without-a-sign-in-flow). For Claude Code: @@ -142,68 +94,36 @@ claude mcp add --transport http flowfuse https://app.flowfuse.com/mcp ### Local and self-hosted models -Use any HTTP-capable MCP client, such as LM Studio, LibreChat or Open WebUI, pointed at your -own model, and add the FlowFuse address as a server in that client's configuration. Note that -Ollama is a model runtime rather than an agent, so it needs an MCP client in front of it. +Use any HTTP-capable MCP client, such as LM Studio, LibreChat or Open WebUI, pointed at your own model, and add the FlowFuse address as a server in that client's configuration. Note that Ollama is a model runtime rather than an agent, so it needs an MCP client in front of it. ## Clients without a sign-in flow -Signing in is the intended route, and the one to use wherever your client supports it. A client -that has no sign-in flow takes a token in its configuration file instead. Both routes reach the -same FlowFuse with the same enforcement. +Signing in is the intended route, and the one to use wherever your client supports it. A client that has no sign-in flow takes a token in its configuration file instead. Both routes reach the same FlowFuse with the same enforcement. -Create a [Personal Access Token](/docs/user/user-settings/#personal-access-tokens) and -[scope it](/docs/user/user-settings/#scoping-a-token) the same way you would when signing in, -to the team you want the agent working in rather than to everything you can reach. Then give -the client the FlowFuse address together with that token as a bearer token in an -`Authorization` header. +Create a [Personal Access Token](/docs/user/user-settings/#personal-access-tokens) and [scope it](/docs/user/user-settings/#scoping-a-token) the same way you would when signing in, to the team you want the agent working in rather than to everything you can reach. Then give the client the FlowFuse address together with that token as a bearer token in an `Authorization` header. -How that is written down belongs to the client rather than to FlowFuse. Two JSON shapes are in -common use, one keyed on `servers` and one keyed on `mcpServers`, and clients also differ on -where the file lives and whether they accept headers at all, so follow your own client's -configuration reference. For the two shapes, see the -[`servers` reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) -and the [`mcpServers` reference](https://modelcontextprotocol.io/docs/develop/connect-local-servers). +How that is written down belongs to the client rather than to FlowFuse. Two JSON shapes are in common use, one keyed on `servers` and one keyed on `mcpServers`, and clients also differ on where the file lives and whether they accept headers at all, so follow your own client's configuration reference. For the two shapes, see the [`servers` reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) and the [`mcpServers` reference](https://modelcontextprotocol.io/docs/develop/connect-local-servers). ## Approvals and audit -FlowFuse tools carry their recommended usage and permissions, so a connected agent knows what -each one is for before it calls it. Most MCP clients then ask you to confirm before they run a -tool. That prompt belongs to the client rather than to FlowFuse, so how it looks, and whether -you can turn it off, differs between them. FlowFuse Expert's own approval cards are a -first-party feature and do not apply here. +FlowFuse tools carry their recommended usage and permissions, so a connected agent knows what each one is for before it calls it. Most MCP clients then ask you to confirm before they run a tool. That prompt belongs to the client rather than to FlowFuse, so how it looks, and whether you can turn it off, differs between them. FlowFuse Expert's own approval cards are a first-party feature and do not apply here. -What FlowFuse enforces on every call is what you granted: the teams, and read access or -editing rights. That is the granularity. It is a boundary around what an agent can reach -rather than a per-tool allow list, and it applies the same way whether the grant came from -signing in or from the scope on an access token. +What FlowFuse enforces on every call is what you granted: the teams, and read access or editing rights. That is the granularity. It is a boundary around what an agent can reach rather than a per-tool allow list, and it applies the same way whether the grant came from signing in or from the scope on an access token. -Actions an agent takes appear in the -[audit log](/docs/user/logs/#ai-agents-and-api-activity), attributed to your account and -marked as having come from a connected agent. +Actions an agent takes appear in the [audit log](/docs/user/logs/#ai-agents-and-api-activity), attributed to your account and marked as having come from a connected agent. ## If something is not working -**A change was refused.** The agent has read access only. Re-connect it and grant editing -rights. +**A change was refused.** The agent has read access only. Re-connect it and grant editing rights. -**The agent cannot reach a team.** That team was not included when you signed in. Re-connect -and include it. +**The agent cannot reach a team.** That team was not included when you signed in. Re-connect and include it. -**The agent cannot see the instance you mean.** Flow and editor work runs in a connected -editor session. Ask your agent to list your sessions and connect to the right one. +**The agent cannot see the instance you mean.** Flow and editor work runs in a connected editor session. Ask your agent to list your sessions and connect to the right one. ## Getting the best out of it -None of this is something to set up before you start. Your agent will tell you when -something is in the way, and can help resolve it. +None of this is something to set up before you start. Your agent will tell you when something is in the way, and can help resolve it. -For the smoothest experience, an instance the agent works in should be on a current launcher -or Device Agent, with a current in-editor assistant. These update when an instance restarts, -so a long-running instance may be behind. If an agent cannot do something you expected in a -particular instance, this is usually why, and asking the agent about it is the quickest route. +For the smoothest experience, an instance the agent works in should be on a current launcher or Device Agent, with a current in-editor assistant. These update when an instance restarts, so a long-running instance may be behind. If an agent cannot do something you expected in a particular instance, this is usually why, and asking the agent about it is the quickest route. -On self-hosted, platform messaging runs over the MQTT broker, so the Team Broker needs to be -available. Whether anything is needed from you depends on how your platform was installed; -see [MQTT Broker configuration](/docs/install/configuration/#mqtt-broker-configuration). AI -features also require an Enterprise licence with AI enabled. +On self-hosted, platform messaging runs over the MQTT broker, so the Team Broker needs to be available. Whether anything is needed from you depends on how your platform was installed; see [MQTT Broker configuration](/docs/install/configuration/#mqtt-broker-configuration). AI features also require an Enterprise licence with AI enabled. From 8d303a8c08ebabdef0cc9c8249ce43fd6e69acef Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Thu, 27 Aug 2026 15:49:25 +0200 Subject: [PATCH 12/12] Apply suggestions from code review Co-authored-by: Andrea Palmieri <76187074+andypalmi@users.noreply.github.com> --- docs/user/expert/third-party-agents.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md index dce7bbfd10..fdcb1e881f 100644 --- a/docs/user/expert/third-party-agents.md +++ b/docs/user/expert/third-party-agents.md @@ -46,7 +46,7 @@ Ask your agent what it can do in a given team or instance if you want the curren An agent with read access has no ability to change anything. -FlowFuse Tables is read-only through the platform tools, for the time being, so an agent can query your data to answer a question but not write to it directly. A flow is a different route. An agent with editing rights can build a flow containing a [Query Node](/docs/user/ff-tables/#query-nodes), and that flow writes to your tables like any other flow you would have written yourself. +An agent can query your FlowFuse Tables data to answer questions. With editing rights it can go further and build a flow with a [Query Node](/docs/user/ff-tables/#query-nodes) that reads and writes your tables, exactly like a flow you would build yourself. ### Deleting, and deploying @@ -84,7 +84,7 @@ On Team and Enterprise plans an owner adds the connector for the organisation fi ### Command-line and editor agents -Claude Code, Cursor, Visual Studio Code and Gemini CLI all connect to the same address. Where a client offers a sign-in flow, use it. Where it does not, see [clients without a sign-in flow](#clients-without-a-sign-in-flow). +Claude Code, Cursor, Visual Studio Code and Gemini CLI all connect to the same address. Where a client supports OAuth, sign in; otherwise use a token, see [clients without a sign-in flow](#clients-without-a-sign-in-flow). For Claude Code: @@ -98,7 +98,7 @@ Use any HTTP-capable MCP client, such as LM Studio, LibreChat or Open WebUI, poi ## Clients without a sign-in flow -Signing in is the intended route, and the one to use wherever your client supports it. A client that has no sign-in flow takes a token in its configuration file instead. Both routes reach the same FlowFuse with the same enforcement. +Where your client does not support OAuth, give it a token in its configuration file instead. Both routes reach the same FlowFuse with the same enforcement. Create a [Personal Access Token](/docs/user/user-settings/#personal-access-tokens) and [scope it](/docs/user/user-settings/#scoping-a-token) the same way you would when signing in, to the team you want the agent working in rather than to everything you can reach. Then give the client the FlowFuse address together with that token as a bearer token in an `Authorization` header.