mcp

Pre-Alpha. This page describes behavior that may change.

The MCP server is the surface you use when an AI assistant should drive Ze. It speaks the Model Context Protocol, exposes typed tools with structured parameters, and gives any MCP-compatible client (Claude, GPT, custom agents) the same control surface a human gets at the CLI. The point of MCP, as opposed to "scrape the CLI output", is that the assistant gets typed inputs and structured outputs, so it does not have to parse text it might misread.

Starting the server

ze start --mcp 8080 config.conf

environment {
    mcp {
        enabled true;
        server main {
            ip   127.0.0.1;
            port 8080;
        }
    }
}

The default listener is 127.0.0.1:8080. That is deliberate: MCP is local-only unless you explicitly override it with ze.mcp.listen=ip:port. Bearer-token auth is available through --mcp-token, the ze.mcp.token environment variable, or the token leaf in the config.

The tools

Only ze_execute has a hand-written wrapper. The remaining tools (ze_announce, ze_withdraw, ze_peers, ze_peer_control, ze_commands) are auto-generated from the command registry at runtime, so any new YANG command or plugin command appears as a typed MCP tool with no code changes.

Tool	Description
ze_execute	Run any CLI command. The escape hatch. Hand-written wrapper.
ze_announce	Announce routes with typed parameters: origin, next-hop, communities, prefixes. Auto-generated.
ze_withdraw	Withdraw routes. Auto-generated.
ze_peers	Peer state, ASN, uptime. Returns structured JSON. Auto-generated.
ze_peer_control	Teardown, pause, resume, flush a peer. Auto-generated.
ze_commands	List all available daemon commands. Auto-generated.

ze_execute is the part that turns "structured tools for the common cases" into "full daemon control": anything you can do at ze cli or ze cli -c, the assistant can do here. Route management, RIB queries, peer lifecycle, configuration commits, cache operations, event subscription, schema discovery: all of it.

A typical flow

An assistant connected through MCP can do something like this without ever touching plain text.

1. Call ze_peers to get every peer's state as structured JSON.
2. Call ze_announce with origin=igp, next-hop=10.0.0.1, prefixes=[10.0.0.0/24].
3. Call ze_execute with rib routes sent peer1 ipv4/unicast to verify propagation.
4. Call ze_withdraw if it needs to roll back.

Each call returns structured data, not text the assistant has to scan.

Generating an AI command reference

The tool registry is auto-generated, but the command catalogue is too. ze help --ai produces a machine-readable command reference from the code, suitable for feeding to an assistant as context. Lists every command, parameter, description, and example.

ze help --ai > ze-commands.json

Drop the file into the assistant's context and the assistant can pick the right command without trial and error.

Testing and CI

ze-test mcp provides a functional test client with a wait-established synchroniser that is what you want in a CI pipeline if you want to test that MCP-driven changes apply correctly without racing the BGP FSM.

Task-augmented tools

Ze's MCP server implements the MCP 2025-11-25 task-augmented tools/call extension. When a tool call includes task context, Ze tracks the task lifecycle and reports progress through the MCP protocol. This allows AI assistants to run long-running operations (config commits, peer teardown sequences) with structured progress reporting.

Apps resources

The MCP server exposes an Apps resources capability (Phase 5), providing structured access to Ze's configuration tree, peer state, and plugin registry as MCP resources. Resources are read-only and follow the same YANG-modeled structure as the CLI and web UI.

See also

• Introspection for ze help --ai and the schema discovery surfaces.
• REST API if you would rather drive Ze with plain HTTP.
• CLI for the human-facing equivalent.

Adapted from main/docs/features/mcp-integration.md.