# Agents over MCP

Fluksio exposes flow tools over MCP. An agent can inspect, edit, publish,
and run flows with the permissions of the user who authorizes it.

## Connect an agent

Set `MCP_ENABLED=true` in the engine's environment and restart it, under
`environment` in `compose.yml` for the Docker container. It defaults to off.

Configure your MCP client with an HTTP endpoint:

- Docker container: `http://localhost:8080/mcp`
- Deployment: `https://<your-domain>/mcp`

The endpoint has to be the address in `FRONTEND_HOST`, which is also the
issuer of the client's tokens.

The client registers, opens browser authorization, and receives an OAuth
token after you approve access. The issuer and browser redirects use
`FRONTEND_HOST` and `ENVIRONMENT`, so configure those for the addresses your
client and browser can reach.

Manage registered clients under **Admin → Agents**. Revoking a client
invalidates its access. MCP uses a separate signing key at
`OAUTH_PRIVATE_KEY_FILE`; rotating that key invalidates all MCP tokens.

An instance connected to a [portal](../interface/portal.md) also answers
through it, at `https://hub.fluksio.com/i/<instance-id>/mcp` (the portal's
own `hub.` host for a custom one). The portal forwards the endpoint and its
OAuth, and the instance checks the agent's token as it does locally. The
consent page opens in the instance as the portal serves it, so open the
instance from the portal first if this browser has not recently.

## Available tools

| Task | Tools |
|---|---|
| Inspect flows | `list_flows`, `get_flow`, `get_node_source`, `list_node_types`, `get_graph`, `list_shared_nodes` |
| Inspect values | `get_flow_state`, `get_message_history` |
| Inspect the instance | `list_secrets` (names only), `get_modules`, `get_health`, `get_metrics`, `list_failures`, `list_runs` (live cascades) |
| Inspect devices | `list_devices`, `get_device` |
| Edit flows | `save_flow`, `save_node_source`, `validate_flow`, `publish_flow`, `discard_draft`, `delete_flow` |
| Operate flows | `run_flow`, `trigger_node`, `start_flow`, `stop_flow`, `pause_flow`, `resume_flow`, `cancel_node` |
| Install node packages | `apply_modules` |

Tools call the same API as the browser. Drafts, validation, version checks,
and superuser restrictions apply. Secrets cannot be read back.

A useful workflow: ask the agent to inspect the flow, save a draft, and
validate it. Review the draft before asking it to publish. The agent has
a publish tool, so make your intent explicit.

## The assistant

A superuser configures an OpenAI-compatible provider under
**Settings → Assistant**, with a base URL, API key, and model. This enables
the dashboard's Assistant entry for signed-in users.

The assistant uses the same tools with your own permissions. Draft edits
appear in the editor. Each answer streams in as the model writes it and
renders as markdown with a tool trace.
Conversations are stored per user on the instance; the bin button clears
yours.
`MCP_ENABLED` is only needed for external clients, so the built-in assistant
works without it.

## Control

A live [Wren](../reference/node-types.md#wren) or
[Assistant](../reference/node-types.md#assistant) node with its `prompt` and a
`reply` or `actions` wired adds a **Control** tab to the chat. Wren uses its
local model, the Assistant node the provider above.

Choose a conversation and type a command. It goes out on the node's prompt,
which is where a `stt` node writes what a device heard, so typed and spoken
commands are one conversation: the words heard so far, the command, each
reply, and the reported actions with their target message, value and whether
each was applied. A node whose prompt is another's `unhandled` answers in that
node's conversation. Wren's `apply` and `min_confidence` settings decide
whether it writes to devices. Control conversations stay in the browser and
clear on reload.