# 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. The Python
package defaults to off; the Docker template enables it.

Configure your MCP client with an HTTP endpoint:

- Local Docker stack: `http://api.localhost/mcp`
- Deployment: `https://api.<your-domain>/mcp`

The client registers, opens browser authorization, and receives an OAuth
token after you approve access. The issuer and browser redirects use
`DOMAIN`, `ENVIRONMENT`, and `FRONTEND_HOST`, 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.

MCP is not forwarded by the [portal tunnel](../interface/portal.md).
Connect directly to the instance's API host.

## 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) |
| 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, and each answer includes 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 node](../reference/node-types.md#wren) with both `prompt` and
`actions` wired adds a **Control** tab to the chat. It uses the node's local
model and needs no assistant provider.

Choose a node, type a command, and inspect the reported actions: target
message, value, confidence, and whether each action was applied.
The node's `apply` and `min_confidence` settings decide whether it writes
to devices. Control conversations stay in the browser and clear on reload.