MCP Integration
Ze exposes daemon commands through an MCP (Model Context Protocol) server. Clients discover tools from the running daemon and invoke commands with the caller's permissions. Command availability depends on the registered surface; an interactive CLI view is not automatically a one-shot MCP operation.
Discoverable command tools
Generated groups use typed inputs where YANG RPC metadata supplies them.
Groups without typed inputs expose an arguments string.
| Tool | Description |
|---|---|
ze_execute |
Dispatch a supported daemon command string with the caller's permissions. |
ze_reference |
Reference assembled from this binary's registries and schemas; the same JSON data as ze help ai --json. |
| Generated groups | Discover current names and action/input schemas through tools/list; do not assume a route-specific tool name. |
ze_execute and ze_reference are the fixed tools. Generated tool groups read
the live command list at tools/list time. Groups with named actions expose an
action enum; selector parameters appear only where the command supports them.
A plugin command registered with Hidden true reaches no tool list. The flag
already removed the command from completion and from help, and buildCommandMeta
is the one source both the MCP tool list and the API command list read, so the
skip covers both surfaces.
ze_execute uses the daemon command grammar for the operations that command
registrations offer on MCP. Offline commands may have a different daemon path;
terminal-only views and streaming-only operations are not automatically
equivalent one-shot calls. Discover current commands rather than copying an old
route, configuration or cache example.
Notification metadata in ze_reference describes the schema. Its presence
does not itself provide an MCP event subscription.
Starting the MCP Server
ze start --mcp 8080 # start from stored (blob) config; run `ze init` first
ze --mcp 8080 config.conf # start from a config file
Or via config:
environment {
mcp {
enabled true
server main {
ip 127.0.0.1
port 8080
}
}
}
Environment variable overrides: ze.mcp.listen=ip:port, ze.mcp.enabled=true, ze.mcp.token=<secret>. Defaults to 127.0.0.1:8080 (security: local-only unless explicitly overridden via ze.mcp.listen). Bearer token auth available via --mcp-token flag, ze.mcp.token env var, or the config token leaf.
AI Command Reference
ze help ai # summary
ze help ai all # detailed listings and authored guidance
ze help ai --json # registry-derived JSON reference
ze help ai api # daemon RPCs, update syntax, families and plugins
The listings come from the binary's registrations and schemas. Recipes and
explanations are maintained text, not a guarantee that every example is current.
ze_reference returns the JSON reference inside MCP text content. The legacy
ze help --ai flag form is still accepted.
Example: AI-Driven Route Announcement
An AI assistant connected via MCP can:
- Read
tools/listand callze_referenceto discover this daemon's commands. - Call
ze_executewithshow bgp peer listto inspect configured peers. - Announce through
ze_executewithsend bgp * update text origin igp next-hop 10.0.0.1 nlri add 10.0.0.0/24. - Call
ze_executewithshow bgp rib sent peer peer1 family ipv4/unicastto inspect that peer's sent routes. - If withdrawal is needed, use the current
send bgpwithdrawal grammar throughze_execute, rather than assuming aze_withdrawtool exists.
Current results use MCP text-content envelopes. JSON references and rendered command data are carried in that text; the envelope is not a promise of a separate typed result object for every command.
Protocol (2026-07-28)
Ze speaks MCP protocol revision 2026-07-28 and no other. The profile is
stateless, and every message is its own HTTP POST to /mcp. Each POST carries
its own protocol version, client capabilities and credential. Three standard
headers and a _meta block inside params hold them. There is no initialize
handshake, no session, no Mcp-Session-Id, no GET stream, and no
server-initiated request.
Two consequences are worth stating plainly:
- Authentication runs on every request, so a revoked token stops working on the very next call rather than at session expiry, and there is no long-lived identifier that acts as a bearer credential in its own right.
- Elicitation is inverted, not gone. The revision forbids a server to send
an independent JSON-RPC request on any stream, so a server can no longer push
a prompt. The server RETURNS the prompt instead:
ze_executecalled without acommandanswersresultType: "input_required"with aninputRequestsmap, and that map carries anelicitation/createrequest. The client then retries the original call withinputResponses, which carries the value. Ze attaches norequestState, so it holds nothing between the two requests and authenticates each one on its own. A client that did not declare form-mode elicitation is never prompted, and it gets the missing-argument error instead. See MCP Elicitation for the full round trip.
Capability discovery is a single optional call: server/discover returns the
supported versions, the server's capabilities, and natural-language
instructions. Its capabilities.extensions names two extensions, each with an
empty settings object: io.modelcontextprotocol/ui, the MCP Apps extension, and
io.modelcontextprotocol/tasks, the Tasks extension. The second extension is
what makes the task result type interpretable, because a client can reject a
resultType that no advertised extension defines.
Client compatibility
A client connects only if it speaks revision 2026-07-28. One that opens with
the initialize handshake of an earlier revision gets error -32020, which
names the revision Ze speaks, and cannot connect. The owner-run
real-client lane records each
client tried. In its first round, on 2026-11-11, Claude Code 2.1.322 connected
and called ze_reference. Codex 0.167.1 opened with the 2025-06-18
initialize handshake and could not connect.
Cacheable results
server/discover, tools/list, resources/list and resources/read return
ttlMs and cacheScope, so a client can hold a result and does not re-fetch it
every turn. The tool inventory and the discovery result are fresh for 60
seconds. The embedded UI assets are fresh for one hour. Every one of them is
scoped private, so a shared gateway is not permitted to serve one caller's
response to another.
tools/call and the tasks/* methods return no hints. Their results are not
cacheable.
Ze has no push invalidation. That 60-second TTL is therefore also the window in which a client can still offer a command that a config reload has removed. A call to that command returns an error. The protocol names such an error as grounds for an early re-fetch, so the stale entry usually clears after one failed call.
MCP Apps
Tool descriptors for command groups carrying a ze:ui-resource YANG annotation
include _meta.ui, pointing at a ui:// asset the host renders in a sandboxed
panel. That metadata is emitted only when the request declared the
io.modelcontextprotocol/ui extension in a form compatible with the HTML
bundles Ze serves. A host without MCP Apps support gets the same tool list, the
same tools and the same behavior, minus the panel metadata. Ze rejects nothing.
Resources
resources/list and resources/read serve every conformant caller, with no
client-capability gate. resources is a member of ServerCapabilities, not of
ClientCapabilities, whose complete member set in this revision is
experimental, roots, sampling, elicitation and extensions. A conformant
client therefore never declares resources, and a gate on it refused every
conformant caller while server/discover advertised the capability and
tools/list published _meta.ui.resourceUri pointing at those same assets.
A ui:// URI is validated before any read: the scheme must match, the cleaned
path must equal the given path, and the depth is capped at 8 segments. A URI that
fails validation gets invalid uri, and one that resolves to nothing gets
resource not found.
Testing
le test mcp provides a functional test client with wait-established
synchronization for CI pipelines. It also provides a probe-* directive family,
which drives deliberately-malformed requests at the conformance surface (header
mismatch, unsupported version, malformed _meta, GET and DELETE).
Background execution is driven by task-call (an ordinary tools/call the
server must answer with a task handle), its twin call-sync (which requires a
synchronous answer and no taskId), then task-get, task-result,
task-update, task-cancel and task-wait. The --tasks flag declares the
io.modelcontextprotocol/tasks extension on every request. A run without the
flag is itself a test, because the server must still serve an undeclaring client
synchronously.
The tools-size directive measures the tools/list answer a running daemon
serves: tool count, total bytes, the largest tool, and each tool's input schema
size and depth. It prints one violation line for each tool that breaks a limit
strict clients enforce: an input schema above 13,312 bytes, nesting deeper
than 10 levels, an enum with no sibling type, or a oneOf, allOf or
anyOf. test/plugin/mcp-tools-list-structural-limits.ci refuses a catalog
that prints a violation.
See MCP Guide for details and MCP Remote Access for tunneling.