diff --git a/docs/install/kubernetes/openshift.md b/docs/install/kubernetes/openshift.md index 4a9ca8d539..b3239ce259 100644 --- a/docs/install/kubernetes/openshift.md +++ b/docs/install/kubernetes/openshift.md @@ -86,7 +86,7 @@ By the end, you will have a fully functioning FlowFuse instance running on a Ope Before you begin, ensure you have the following: 1. **Domain Name & DNS:** A domain name that you own and can configure DNS settings for (explained in [DNS](#dns)) -2. **oc:** To manage a OpenShift cluster you will need a copy of the `oc` utility. Instructions on how to install `oc` can be found [here](https://docs.openshift.com/container-platform/4.17/cli_reference/openshift_cli/getting-started-cli.html) +2. **oc:** To manage a OpenShift cluster you will need a copy of the `oc` utility. Instructions on how to install `oc` can be found [here](https://docs.redhat.com/en/documentation/openshift_container_platform/4.17/html/cli_tools/openshift-cli-oc) 3. **Helm:** FlowFuse provides the Helm chart to manage platform deployment. Installation can be done through the instructions on [their website](https://helm.sh) 4. **OpenShift Cluster:** an OpenShift cluster instance with at least two worker nodes 5. **Ingress Controller:** [The Traefik](https://doc.traefik.io/traefik/) installed on the cluster. diff --git a/docs/user/expert/third-party-agents.md b/docs/user/expert/third-party-agents.md index 38531bd8db..e8ed147204 100644 --- a/docs/user/expert/third-party-agents.md +++ b/docs/user/expert/third-party-agents.md @@ -37,7 +37,7 @@ The same three steps, written out: 2. **Sign in.** FlowFuse uses OAuth, so your agent sends you to a FlowFuse login page. If your client asks for an OAuth client ID or secret, leave them blank; FlowFuse registers your client for you. -3. **Select teams and permissions.** Signing in takes you to a FlowFuse authorization page. There you choose which teams the agent can reach and the permissions it has in each, and set an expiration date for the grant. +3. **Select teams and permissions.** Signing in takes you to a FlowFuse authorization page. There you choose which teams the agent can reach, whether it can **Read**, **Write** or do **Destructive** things in Platform and Flow Building tools, per team if you want, and set an expiration date for the grant. See [Access and permissions](/docs/user/mcp/#access-and-permissions). Your agent is now connected. If your client does not support OAuth, use a token instead, see [clients without a sign-in flow](#clients-without-a-sign-in-flow). diff --git a/docs/user/mcp.md b/docs/user/mcp.md index f1a7241d85..14450c0b38 100644 --- a/docs/user/mcp.md +++ b/docs/user/mcp.md @@ -1,7 +1,7 @@ --- navTitle: FlowFuse MCP meta: - description: See what an AI agent can do through the FlowFuse MCP server, from platform actions to building flows, and how read-only or full access limits it. + description: See what an AI agent can do through the FlowFuse MCP server, from platform actions to building flows, and how the Read, Write and Destructive permissions limit it. --- # FlowFuse MCP Server @@ -13,29 +13,31 @@ Two clients use it: - **FlowFuse Expert**, the AI built into the platform and the Node-RED editor. - **Your own agent**, such as Microsoft Copilot, ChatGPT or Claude, connected over the [MCP endpoint](/docs/user/expert/third-party-agents/). -Both use the same capabilities. What an agent can do depends only on the access you grant. +Both use the same capabilities. What an agent can do depends only on the permissions you grant, see [Access and permissions](#access-and-permissions). > **Note:** This is not the same as [MCP server nodes](https://flowfuse.com/docs/flowfuse-nodes/mcp/), which build MCP servers inside your flows. This page is about operating FlowFuse itself, where FlowFuse is the server and your agent is the client. ## Platform Automations -Actions an agent can take on the platform, by resource and access level. - -| Resource | Read-only | Full access | -|---|---|---| -| Teams | Members and roles, invitations, audit log, resource counts, bill of materials | Create a team, update settings, change member roles, invite and re-invite members | -| Applications | Applications, audit log, device groups, bill of materials | Create and update applications | -| Hosted instances | Live status, resources, configuration, logs, files, history, HTTP tokens | Create, start, stop, restart, suspend; update settings, environment and config surfaces; import flows; edit files; manage HTTP tokens | -| Remote instances | Remote instances and live status | Register and assign to an application, restart, update settings and operating mode | -| Snapshots | Snapshots, including full flows | Create, export, import, update; set an instance's device target | -| Pipelines | Pipelines and stages | Create and update pipelines; add, update and deploy stages | -| Device groups | Team and application device groups | Create and update groups, change membership and settings | -| FlowFuse Tables | Databases, tables, schemas, row data | Table data is changed through flows, see [Flow Building](#flow-building) | -| Team broker | Brokers, clients, topics, schema | Start, stop, suspend the broker agent; create and update topics | -| Your account | Profile, notifications, invitations | Update profile, mark notifications read, respond to invitations | -| Blueprints and templates | Blueprints, templates, instance and team types | Starting points for creating instances and teams | - -Ask the agent what it can do in a given team or instance. Its tools reflect the access granted and the instance it is connected to. +Actions an agent can take on the platform, by resource and [permission](#access-and-permissions). + +| Resource | Read | Write | Destructive | +|---|---|---|---| +| Teams | Teams you belong to, members and roles, invitations, audit log, instance counts, npm packages, Git tokens, bill of materials | Create a team, update settings, invite and re-invite members | Change member roles, remove members, revoke invitations | +| Applications | Applications, audit log, snapshots, instance statuses, device groups, bill of materials | Create and update applications | Delete an application | +| Hosted instances | Instances and live status, resources, configuration, custom hostname, logs, files, history, audit log, HTTP tokens, name availability, dashboard instances, editor and overview links | Create an instance, create HTTP tokens | Start, stop, restart, suspend; update settings, environment and config surfaces; import flows; upload, edit and delete files; roll back; delete an instance; update and delete HTTP tokens | +| Remote instances | Remote instances and live status, provisioning tokens | Register an instance, assign it to an application, set the operating mode | Update settings | +| Snapshots | Snapshots, including full flows, and an instance's device target | Create, export, import, update | Delete a snapshot, set an instance's device target | +| Pipelines | Pipelines and stages | Create and update pipelines, add and update stages | Deploy a stage, delete a pipeline or stage | +| Device groups | Team and application device groups | Create a group | Update a group, change membership and settings, delete a group | +| FlowFuse Tables | Databases, tables, schemas, row data | Create a table. Row data is changed through flows, see [Flow Building](#flow-building) | None | +| Team broker | Brokers, clients, topics, schema | Create and update topics | Start, stop, suspend the broker agent; delete topics and clients | +| Search | Search team resources and instances | None | None | +| Editor sessions | List open editor sessions, see and set the active one | None | None | +| Your account | Profile, notifications, invitations | Update profile, mark notifications read | Delete notifications, accept or decline team invitations | +| Blueprints and templates | Blueprints, templates, instance and team types | None | None | + +Ask the agent what it can do in a given team or instance. Its tools reflect the permissions granted and the instance it is connected to. ## Flow Building @@ -43,16 +45,18 @@ An agent builds and edits flows inside a running Node-RED instance. Flow work runs in a live editor session, not as a file to import. Point the agent at an open editor session and it builds on the canvas. Node-RED validates as it goes, so the agent catches its own mistakes. -| Area | Read-only | Full access | -|---|---|---| -| Nodes | Read nodes with validation state | Add, update and remove nodes | -| Wiring | — | Wire nodes on a tab, link nodes across tabs | -| Tabs | List tabs | Add, rename, enable, disable and remove tabs | -| Subflows and subroutines | List subflows | Create and remove subflows, create subroutines | -| Groups | — | Create, update, move and delete groups, change their members | -| Palette | Read the installed palette, describe node type properties | Install FlowFuse and certified nodes directly, open the palette manager to install any other package, see [Node installs](#node-installs) | -| Canvas | Read the full flow, list config nodes, read debug output, search and select nodes | Navigate to a tab or subflow, align and distribute nodes | -| FlowFuse Tables | Query table data | Build a [Query Node](/docs/user/ff-tables/#query-nodes) flow that reads and writes tables | +| Area | Read | Write | Destructive | +|---|---|---|---| +| Nodes | Read nodes with validation state | Add and update nodes | Remove nodes | +| Wiring | None | Wire nodes on a tab, link nodes across tabs | None | +| Tabs | List tabs | Add, rename, enable and disable tabs | Remove tabs | +| Subflows and subroutines | List subflows | Create subflows and subroutines | Remove subflows | +| Groups | None | Create, update, move and delete groups, change their members | None | +| Config nodes | List config nodes | Create and update config nodes | Delete config nodes | +| Import | None | Import a flow onto the canvas | None | +| Palette | Read the installed palette, list node types, describe node type properties | Install FlowFuse and certified nodes directly, open the palette manager to install any other package, see [Node installs](#node-installs) | None | +| Canvas | Read the full flow, read debug output, search and select nodes, navigate to a tab or subflow | Align and distribute nodes, set the deploy mode | Deploy changes, see [Agent deploy](#agent-deploy) | +| FlowFuse Tables | Query table data | Build a [Query Node](/docs/user/ff-tables/#query-nodes) flow that reads and writes tables | None | By default nothing goes live until you deploy from Node-RED. A team owner can let agents deploy their own changes, see [Agent deploy](#agent-deploy). @@ -70,11 +74,25 @@ Available from FlowFuse 3.1 with `@flowfuse/nr-assistant` 0.20.0 or later. ## Access and permissions -Access comes at one of two levels: +Every tool needs one of three permissions, set separately for **Platform** tools and **Flow Building** tools: + +- **Read** sees everything and changes nothing. +- **Write** adds and updates things. It includes Read. +- **Destructive** covers tools that delete or overwrite data, or change what is running. It includes Write and Read. + +With **FlowFuse Expert**, an agent acts with the same access you have on the team you are working in. Expert's own approval cards are described in [Controlling what Expert can do](/docs/user/expert/chat/#controlling-what-expert-can-do). + +With **your own agent**, you choose the permissions when you connect. Signing in over OAuth takes you to a FlowFuse authorization page with these steps: + +1. Tick the permissions the agent gets by default, for Platform and Flow Building. +2. Choose **All teams** or **Specific teams**. +3. Optionally select **Edit** next to a team to give it its own permissions instead of the defaults. A team using its own permissions is marked **Custom**, and **Reset** returns it to the defaults. +4. Set an expiration date, up to a year. + +For example, an agent can have Destructive access to Platform tools in a staging team and only Read access everywhere else. -- **Read-only** sees everything and changes nothing. -- **Full access** adds every action in the full-access columns above. +The default permissions also apply to teams you join later when you chose **All teams**. A call that needs a permission the agent was not granted in that team is refused. -With **FlowFuse Expert**, an agent acts with the same access you have on the team you are working in. +A connection appears in your token list under **User Settings > Security** with a summary of its permissions. To change them, delete the token and connect the agent again. -With **your own agent**, you choose the access when you connect. Signing in over OAuth takes you to a FlowFuse page where you choose which teams the agent can reach and the permissions it has in each, and set an expiration date. A personal access token, for clients without a sign-in flow, carries the same choice of teams and permissions. +A personal access token, for clients without a sign-in flow, is scoped to teams and can be limited to **Read Only**, see [Scoping a Token](/docs/user/user-settings/#scoping-a-token).