From 50b51c915a42c3c20b710c7491d04fe831fa703c Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Mon, 24 Aug 2026 11:05:46 +0200 Subject: [PATCH 1/4] 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 2/4] 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 3/4] 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 4/4] 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}" } } },