stroblmeandClaude Opus 5
a3cb9cc817
The icon variant lost its last caller when the responsive variant stopped
carrying a second cropped image. runOverviewQueryOptions now takes the
refetch interval, defaulting to the 30s the Runs screen and the dashboard
panel want; Home passes 10s so a short run does not linger on the tile.
agents.md spells the API host as api.${DOMAIN}, which is what the rest of
the docs use.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CL9zvnnvcp1mvA8o7impxk
112 lines
3.9 KiB
Markdown
112 lines
3.9 KiB
Markdown
# Agents over MCP
|
|
|
|
The engine exposes the flow API to agents over the
|
|
[Model Context Protocol](https://modelcontextprotocol.io). Point Claude Code,
|
|
Claude Desktop, Codex or anything else that speaks MCP at it, and it can read,
|
|
build, publish and run flows.
|
|
|
|
## Switching it on
|
|
|
|
```sh
|
|
MCP_ENABLED=true
|
|
```
|
|
|
|
It is off by default: switching it on opens client registration to whoever can
|
|
reach the host.
|
|
|
|
The endpoint is `https://api.${DOMAIN}/mcp`, or `http://api.localhost/mcp` on a
|
|
local stack.
|
|
|
|
## Connecting a client
|
|
|
|
```sh
|
|
claude mcp add --transport http fluksio https://api.${DOMAIN}/mcp
|
|
```
|
|
|
|
The OAuth flow does the rest: the client registers itself, you approve it in
|
|
the browser, and it exchanges the grant for a token. Nothing to paste.
|
|
|
|
## What an agent may do
|
|
|
|
An agent acts as **the person who approved it**, and only through the same REST
|
|
API the dashboard uses. It cannot do anything you could not do in the browser,
|
|
and it cannot do anything *you* cannot do. An agent approved by a non-superuser
|
|
is not one either.
|
|
|
|
Its tokens are signed with a keypair of their own, kept beside the flow store.
|
|
Deleting that file revokes every agent's access without logging anyone out of
|
|
the dashboard.
|
|
|
|
Registered clients are managed under **Admin**.
|
|
|
|
## The tools
|
|
|
|
Read-only:
|
|
|
|
| Tool | Returns |
|
|
|---|---|
|
|
| `list_flows` | every flow with its node count and state |
|
|
| `get_flow` | one flow's definition, node status and issues |
|
|
| `get_node_source` | a node's Python |
|
|
| `list_node_types` | every type and its parameter schema |
|
|
| `get_flow_state` | the current value of each of a flow's messages |
|
|
| `get_message_history` | one message's recent numeric values |
|
|
| `get_graph` | every flow as one graph |
|
|
| `list_shared_nodes` | the shared library and its usages |
|
|
| `list_secrets` | secret **names**, never values |
|
|
| `get_modules` | the packages node code can import |
|
|
| `get_health` | flows, nodes, queue and loop lag |
|
|
| `get_metrics` | executions, errors and timings per minute |
|
|
| `list_failures` | what went wrong recently |
|
|
| `list_runs` | recent cascades |
|
|
|
|
Editing:
|
|
|
|
| Tool | Does |
|
|
|---|---|
|
|
| `save_flow` | write a draft |
|
|
| `save_node_source` | write a node's code into the draft |
|
|
| `validate_flow` | the issues, without saving |
|
|
| `publish_flow` | put the draft live (takes the version it saw) |
|
|
| `discard_draft` | throw the draft away |
|
|
| `delete_flow` | delete it |
|
|
| `apply_modules` | replace the package manifest |
|
|
|
|
Operating:
|
|
|
|
| Tool | Does |
|
|
|---|---|
|
|
| `run_flow` | run every node once from the values given |
|
|
| `trigger_node` | feed one node and run what is downstream |
|
|
| `start_flow` / `stop_flow` | activate or tear down |
|
|
| `pause_flow` / `resume_flow` | hold messages, or let them through |
|
|
| `cancel_node` | kill a node's code while it runs |
|
|
|
|
## Why it is shaped this way
|
|
|
|
The tools do not reach into the engine. Each one calls the same REST endpoint
|
|
the dashboard calls, over an in-process transport.
|
|
|
|
That keeps exactly one description of what a flow is and how it may be changed:
|
|
the validation, the draft/publish split, and the version check that stops two
|
|
clients overwriting each other. An agent saving a flow through a private back
|
|
door could write one the canvas cannot open.
|
|
|
|
The caller's token rides along on every hop, so the API sees the agent's own
|
|
identity rather than a service account. The audit trail on Home names it.
|
|
|
|
## A note on working this way
|
|
|
|
The pattern that works is the same one that works with a person: let the agent
|
|
read the flow and its issues, let it write a **draft**, and publish yourself
|
|
once you have looked. `validate_flow` before `publish_flow` is cheap and tells
|
|
you what the canvas would have told you.
|
|
|
|
## Limits
|
|
|
|
- MCP is not currently reachable through a [portal](../interface/portal.md)
|
|
tunnel: the proxy forwards `/api/v1/` only. Connect an agent on the same
|
|
network as the instance.
|
|
- Secrets are never readable, by an agent or by anyone else. `list_secrets`
|
|
returns names.
|