Ryu MCP server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Ryu MCP server
An MCP server for the Ryu OpenFlow controller.
It lets an AI agent read an OpenFlow network — switches, links, hosts, flows, port counters — and request flow changes, while keeping every change behind a human approval gate. It was built as the client-access edge of a multi-domain setup, where Ryu maps enterprise VLAN traffic onto the uplinks that hand off to the packet core.
Paper: Operator-Controlled MCP: A Security Layer for AI Agent Operations on Networks (source in paper/).
The problem, and the approach in brief
An AI agent with write access to a network controller can do damage that cannot be taken back in one call: empty a flow table, make a switch drop all its traffic, or leave a circuit half built. A refusal after the fact does not undo any of that. This server puts a layer between the agent and Ryu so that the agent can read the network freely but can only ask for a change, and every change is checked, shown to a person and verified before and after it happens.
the risk | what stops it |
the agent writes on its own | write tools only queue a request; nothing reaches Ryu until an operator approves it. No tool argument skips this |
the agent does not see how risky a change is | every request is rated medium, high or critical from what it does to the switch, with the reasons |
a harmful change slips through approval | the user is asked through the client before a high or critical change is queued, and a critical one needs a typed code |
approval is given for one thing and another is applied | a fingerprint of the request is checked again at apply time, requests expire, and each is applied once |
Ryu says "ok" but the switch did not take the change | the flow table is read back; a flow the switch does not hold is reported failed and rolled back |
a change cannot be taken back | the flows it replaces are saved first, so an undo restores them exactly (and is itself a request that needs approval) |
nobody can tell what the agent did | every request, approval, refusal and failure goes to an audit log |
Details of each are below. The accompanying paper is in paper/.
Related MCP server: transportpce-mcp-server
Why the write tools do not write
The write tools validate a flow, put it on an approval queue on disk, and return
an approval_id. Nothing reaches Ryu until an operator approves it and the drain
step installs it:
python run_ryu_mcp.py --list-pending
python run_ryu_mcp.py --approve <id> # or --reject <id>
python run_ryu_mcp.py --drain # install approved flows
python run_ryu_mcp.py --undo <id> # queue the inverse of an applied write
python run_ryu_mcp.py --recover # settle a request whose process died mid-applyNo tool takes an argument that skips this. A flag the model can set is a flag
the model will set. The single bypass, RYU_MCP_WRITE_MODE=direct, is chosen by
whoever starts the server — for a host system that already puts a person in
front of every change and would otherwise ask twice.
Approval by a host system. A host that puts its own person in front of each
change (edgeLM confirms as root, for instance) can approve that one request over
MCP with ryu_approve_request(approval_id, approver_token). The token is set by
the operator in RYU_MCP_APPROVER_TOKEN on this server and held by the host;
it is not a model's argument to choose. Unset, the tool always refuses and
approval stays on the command line. Every use is in the audit log.
Confirming a strong change with the user, through the agent. Before a strong
write is even queued — a delete, an unmap, an undo, a wildcard flow, a bulk change
(anything assessed high or critical) — the server asks the person behind the
client, over MCP's elicitation. It is not an argument of any tool, so a model cannot
supply it; the question is written by the server from the request it validated, so
a model cannot soften what the person reads; and the answer comes back from the
client, not through the model. A no, a dismissed question, or no answer within
RYU_MCP_CONFIRM_TIMEOUT seconds queues nothing. A critical change also asks the
person to type a short code from the request's digest, which a click cannot supply.
Confirming is not approving: a confirmed request still waits for the operator.
| asks about |
| high and critical changes |
| every write |
| nothing |
A client that cannot ask its user (no elicitation) gets the operator's approval alone
and the reply says confirmation.state: unavailable; with RYU_MCP_CONFIRM_STRICT=1
such a write is refused instead. In direct mode a strong change is confirmed before
it is applied. The command line (--approve, --undo) has a person at it already
and is not asked.
What the person approving is shown. Each request comes back with a risk tier
(medium, high, critical) and the reasons for it, from what the change would
do to the switch rather than from how it is worded: a wildcard flow with no
forwarding action drops every packet on the switch, and deleting the priority-0
flow stops the switch asking the controller about anything new. A critical
change is queued even when the server is started in direct mode.
What keeps an approval honest.
A digest. Every request carries a fingerprint of what will be sent, checked again when it is applied; an entry edited after it was requested is refused. A host that shows its person the digest can pass it back as
expected_digest, so its approval holds only for the request that person saw.Expiry. A request stays approvable for
RYU_MCP_APPROVAL_TTLseconds (default 3600), so an approval is not applied to a network that has moved on.One application. An approved request is claimed under a lock shared by the server and the command line before anything is sent, so it cannot be applied twice.
Guessing. Five wrong approver tokens in a row pause approval over MCP for five minutes. The command line is unaffected.
Undoing, and not half-doing. Before a request is sent, the flows it would
replace or remove are read from the switch and kept. ryu_request_undo (or
run_ryu_mcp.py --undo <id>) then queues the exact inverse: it deletes what was
added, or puts back what was overwritten or removed. It is a request like any
other and waits for approval. It is refused if a later change touched the same
flows (undo that first), and no undo is offered if the earlier state could not be
read or has an action this server does not know — better none than a wrong one.
A request that fails partway (the second flow of a VLAN map) is rolled back from
the same record, so it never leaves a circuit that carries traffic out and none back.
Surviving a restart. Ryu holds no flows of its own; a switch that restarts
comes back empty. The server watches the connected switches (every 30 s,
--watch-interval or RYU_REPLAY_WATCH, 0 to turn off) and, when one connects,
re-installs every write that was approved and applied, oldest first, so a later
delete still follows the add it removed. --replay does the same once, by hand.
Nothing new is approved by this: it puts back the state approval was given for.
Tools
read tool | answers |
| is Ryu reachable, and are |
| switches with their ports, links between them, discovered hosts |
| connected datapaths |
| one switch's description and port states |
| installed flows with packet counters |
| per-port packet, error and drop counters |
| hop-count shortest path between two switches over discovered links; same switch is a zero-hop path |
write tool | queues |
| one flow ( |
| removal of one exact flow ( |
| a client port onto a VLAN on an uplink, both directions |
| removes a mapping: the exact inverse of |
| queues the exact inverse of an applied write; still needs approval |
| approves and applies one queued write — only with the operator's |
Every tool returns JSON with ok. A refusal or an unreachable Ryu comes back as
data, not as an exception.
Install
git clone https://github.com/maconair0/ryu-mcp-server.git
cd ryu-mcp-server
python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txtPython 3.10+. Ryu itself does not need to be installed alongside this server; it is reached over REST.
Configuration
variable | default | notes |
| — | e.g. |
|
| Ryu's |
|
| seconds |
|
|
|
|
| approval queue and audit log |
| — | lets a host approve over MCP; unset, approval is command-line only |
|
| seconds a request stays approvable; |
|
| which writes ask the user first: |
|
|
|
|
| seconds the user has to answer; silence is a no |
|
| this server's endpoint |
Running
python run_ryu_mcp.py --check # is Ryu there?
python run_ryu_mcp.py --ryu-url http://127.0.0.1:8080 # serve over SSE
python run_ryu_mcp.py --transport stdioRyu must run with the REST apps this server uses:
ryu-manager --observe-links ryu.app.ofctl_rest ryu.app.rest_topology--observe-links is what makes rest_topology report links; without it the
link list is always empty.
A lab to test against
lab/ builds one container with Ryu and Mininet. Ryu does not install on
Python 3.12, and Mininet needs root and Open vSwitch, so a container is the
clean way to run both:
docker build -t ryu-lab lab/
docker run -d --name ryu-lab --privileged --restart unless-stopped \
-p 8080:8080 -p 6653:6653 -v /lib/modules:/lib/modules:ro ryu-labIt starts two edge switches, each with two enterprise hosts and an uplink:
h1 (10.10.0.1) ─┐ ┌─ h3 (10.10.0.2)
s1 ── port 3 → core1 s2 ── port 3 → core2
h2 (10.20.0.1) ─┘ (0x101) (0x102) └─ h4 (10.20.0.2)OVSDB answers on port 6640 inside the container, for agents that read the
switches' port state and counters directly. It is not published on the host;
join the container to a network to reach it
(docker network connect --alias ryu-lab <net> ryu-lab).
The edge switches are not linked to each other: traffic between the sites has to
cross the core, which is another controller's domain. core1 and core2 stand
in for that handover. No forwarding app runs, so nothing passes until flows are
installed — which is what makes a provisioning request observable.
Mapping a site's client port onto the core uplink:
ryu_map_vlan(dpid="0000000000000101", client_port=1, uplink_port=3, vlan_id=10)Notes
A switch has two names.
rest_topologyreports dpids as 16-digit hex (0000000000000101);ofctl_resttakes them as decimal (257). Every tool accepts either.A VLAN match and the present bit. Under OpenFlow 1.3 a tagged VID is matched as
vid | 0x1000;ryu_map_vlansets it. Ryu 4.34 with Open vSwitch also reads a bare10as VLAN 10, so the two spellings meet on the same flow — and both are reported back asdl_vlan, which is why flows are compared under Ryu's names.Ryu ignores match fields it does not know. A typo like
in_prtis dropped and the flow matches more than intended, so match fields and action types are validated before anything is queued.Ryu answers 200 to flows the switch then refuses. A missing prerequisite (
ip_protowithouteth_type), a group that does not exist,DEC_NW_TTLwithout an IP match, an action type spelledoutput: Ryu accepts, Open vSwitch does not install, nothing reports it. Prerequisites and spelling are checked when the request is made; for the rest, after applying, the flow table is read back and a write is onlyappliedif the switch holds it (verified: true), otherwise it isfailedand rolled back.Ryu's own flows are hidden. The table-miss and LLDP punt flows it installs are not anybody's configuration;
include_controller_defaults=trueshows them.
Evidence
All of this is reproducible from this repository (see Tests below). Results from the runs behind the current version:
what was tried | result |
110 unit tests against a stateful fake of Ryu's REST API | all pass |
15 scripted attacks and a seeded fuzzer of 25,000 random tool calls with hostile and mistyped arguments | no write reached a switch without a decision, none fell outside what an operator approved, every approved request was applied, and the approver token appeared in no output or log |
mutation check: switch each of 29 guards off in turn | every one is caught by a failing test (the first run missed four, which now have tests) |
a real Ryu 4.34 with Open vSwitch (48 checks) | undo restores the flow tables exactly after a map, an overwrite and a delete. Flows that Ryu accepted with HTTP 200 but the switch refused are detected, and a half-applied request is rolled back |
stress run on a live Ryu holding 34 flows (26 checks) | 64 concurrent callers made 638 reads with no errors. A flood of 320 write requests queued exactly the hourly cap of 20. Twenty requests approved at once from two paths were each applied once. A process killed mid-apply was recovered, and undoing everything left the 34 flows exactly as they were |
user confirmation over a real MCP connection | a "no", a dismissed question or silence queued nothing; a "yes" queued the request marked as confirmed |
Testing found real defects in earlier versions, all fixed and covered by tests: a success report for flows the switch had refused, an undo that would have deleted a flow it should have restored, an apply interrupted by a crash that stayed "in progress" forever, an approval that could be applied twice by two processes, and several unchecked inputs.
Limitations
No language model tried to defeat the server directly. The attacks are scripted and the fuzzer is random. A model did drive it indirectly through a separate orchestrator for reads and for requests that must be refused, but not for a real write.
User confirmation was tested with test clients, not with a production agent host. A client without MCP elicitation falls back to the operator's approval alone, or the write is refused if
RYU_MCP_CONFIRM_STRICTis set.Approval is only as good as the person approving. The server shows a rating, the reasons and a fingerprint, but cannot make anyone read them.
Whoever can write the state directory is in effect the operator. The fingerprint catches an entry changed after it was requested, not one edited together with its fingerprint.
The host's approver token is a bearer secret. It is never returned or logged and guessing is rate limited, but it is not rotated or scoped.
Undo is exact only for what can be read back. If the earlier state cannot be read, or has an action this server does not know, no undo is offered rather than a wrong one.
Read-back shows the switch holds the flow, not that traffic does what the person intended.
Scope: OpenFlow 1.3 through the REST API of one version of Ryu (4.34) and Open vSwitch. Other controllers and versions are untested.
Tests
python -m unittest discover -s tests/unit -t . # no Ryu or network neededtests/ is split by what each part needs:
folder | holds |
| the unit tests, against a stateful fake of Ryu's REST API |
| that fake and the rig the tests share |
|
|
|
|
Licence
Apache 2.0. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Supervised API-write gateway for AI agents with policy, human approval and execution receipts.
Preventive human-approval write-gate for AI agents: writes commit only after a human approves.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Human-in-the-loop review and approval for AI agents. Audit trail, approval policies, native MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides read-only, multi-vendor network device interaction, configuration auditing against vendor-guide rules, and safe diffing of proposed changes for AI agents to inspect and analyze network infrastructure without any commit or write capability.1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to inspect an OpenDaylight TransportPCE optical network — topology, port mappings, node status, services, TAPI views and advisory path computation — through a single RESTCONF-backed interface. Provisioning calls such as service create/delete and device connect are validated and queued for out-of-band human approval instead of being executed, and responses come back as structured JSON so failures are distinguishable from successes.1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables an AI agent to read-only inspect Extreme Networks switches over SNMPv3 and optional SSH, retrieving health, interface, VLAN, routing, DHCP, ARP/MAC, logging and fabric-topology data for monitoring and troubleshooting. No write path exists, so agents can look at approved inventory switches without being able to change configuration.1Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables an LLM agent to defend a software-defined Cisco network through an OODA loop of tools: it summarizes traffic anomalies, detects configuration drift, dry-runs candidate flow rules for conflicts and lockouts, and pushes validated policy behind a device-native dead-man's switch that auto-rolls-back unless a health check confirms the commit. All safety checks are enforced server-side over RESTCONF/NETCONF (or a mock adapter), so the model can act without being able to break the network.Apache 2.0