mcp¶
mcp serves the Proteus questions to an agent, or to a chatbot behind an MCP gateway, over the Model Context Protocol (MCP).
Synopsis¶
proteus mcp [flags]
proteus mcp --http [flags]
Tools¶
| Tool | Question | Command |
|---|---|---|
simulate_policy |
Does the estate allow this flow, and which rule decides on each hop? | simulate policy |
simulate_routing |
Which firewalls does this packet cross? | simulate routing |
simulate_nat |
Which NAT rule does this packet hit on one firewall, and how is it translated? | simulate nat |
search |
Where does this address, prefix, port or name appear? | search |
lookup |
What does this rule or object contain? | lookup |
snapshot_diff |
What changed on a device between two snapshots? | snapshot diff |
The server reads the snapshot store only, so simulate policy --file has no tool.
Each tool reads the latest snapshot of each device, or the newest snapshot at or
before at. A date in at means the end of that day.
| Tool | Inputs |
|---|---|
simulate_policy |
source, destination, protocol, port, source_port, url, application, user, device, router, at, detail |
simulate_routing |
source, destination, protocol, port, device, router, at, detail |
simulate_nat |
source, destination, protocol, port, device (required), router, at, detail |
search |
value, kind, device (list), label (list), vsys, at, detail, limit |
lookup |
name, kind, device (list), vsys, at, detail, limit |
snapshot_diff |
device, from, to, detail, limit |
| Input | Rule |
|---|---|
source, destination |
an address or a host name; the server resolves a host name with its own DNS and checks the first IPv4 address |
port, source_port |
a number from 1 to 65535 |
protocol |
tcp, udp, icmp or sctp; simulate_policy also takes an IP protocol number from 0 to 255, such as 89 for ospf; the form tcp/443 is refused |
protocol left out |
simulate_routing and simulate_nat use tcp; simulate_policy with application uses the protocol of the application's default |
protocol left out in simulate_policy without application |
no default; a rule that needs the protocol holds the answer back, and needs asks for it |
application |
a predefined or custom application, matched with the App-ID data of each hop's snapshot; see simulate policy |
application that a hop's data does not hold |
that hop stays undecided |
device |
an enum of the exported devices; the client sees the names in the input schema, and the server refuses any other name |
detail |
summary (the default) or full |
limit |
1 or more, with no default; it keeps the first N results over all devices together |
search and lookup find applications, filters and containers with the App-ID
data, as the command line does. The input schema of each tool describes what
Proteus evaluates for each input.
A result for limit is a finding for search, a card for lookup, and a single
change for snapshot_diff. In snapshot_diff, the scope where the limit falls
keeps its first changes, and the later scopes are left out. The summary's found
counts every result, and omitted counts the results left out. The answer line
then ends ; 5 of 812 shown, narrow by device, vsys or kind. Holes, unresolved
entries and notes are never cut. A model should pass limit for a broad search,
such as a large prefix or a common port, so that the answer fits its context.
Examples¶
Start the server for a local agent¶
proteus fetch --all # with export_inventory: true in the inventory
proteus mcp # stdio: for a local agent
The server reads its device list from <store>/.proteus/inventory.yaml, the
inventory export that
fetch writes. It never reads the inventory with credentials. A change of
devices needs a new fetch and a server restart.
Call a tool¶
A client sends a tools/call request over standard input:
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"snapshot_diff","arguments":{"device":"fw01"}}}
The text content of the answer reads:
1 with changes, 0 without, 0 holes
fw01/shared: 0 added, 0 removed, 0 changed
fw01/vsys:vsys1: 1 added, 1 removed, 2 changed
fw01/vsys:vsys2: 0 added, 0 removed, 0 changed
The structured content holds the same answer as the JSON envelope of
proteus snapshot diff --output json --detail summary. A call without detail
gets summary.
Serve HTTP behind a TLS proxy¶
$ proteus mcp --http --listen 127.0.0.1:18765 --token-file token --audit-log audit.jsonl --allowed-host localhost
proteus mcp: serving http://127.0.0.1:18765 (Host check on: localhost)
The server prints its start line on stderr. It listens on --listen (default
127.0.0.1:8765) and serves plain HTTP, so put a reverse proxy that terminates
TLS in front of it. Without allowed_hosts, the line ends (Host check off).
Warning
A token holder can forge the identity. The token proves that a request comes through the gateway, and Proteus does not verify the identity header. Proteus does no authorization, so the gateway must decide who can use the server.
Deploy with Docker¶
The sample in deploy/docker/ runs Proteus in two containers behind a TLS proxy:
flowchart LR
PK["Portkey or another MCP gateway"] -->|HTTPS| PX["caddy: TLS"]
PX -->|"plain HTTP, internal network"| S["proteus-mcp<br/>proteus mcp --http"]
F["proteus-fetch<br/>fetch --all on a schedule"] -->|writes| V[("store volume<br/>+ .proteus/inventory.yaml")]
V -->|read-only| S
F -->|XML API| FW["firewalls fw01, fw02"]
| Container | Role |
|---|---|
proteus-fetch |
holds the only inventory with credentials and the firewall password, both as secrets; runs proteus fetch --all every hour and writes the store and the export |
proteus-mcp |
runs proteus mcp --http; mounts the store read-only, holds the token as a secret, and sits on a network with no route out |
caddy |
terminates TLS, limits the request body to 1 MB and forwards to proteus-mcp; checks the server with /healthz; drops the X-User-Claims header from every log line, so only the audit holds identities |
Both Proteus containers run as UID 10001, read-only, with every capability
dropped. The server image has no shell. The comments in
deploy/docker/compose.yaml list the steps before the first start: the secrets,
their owner and their mode. Until the first fetch writes the export,
proteus-mcp exits 2 and restarts. The fetch container's script passes SIGTERM
to the running proteus fetch and exits 143 when it ends.
deploy/portkey.md registers the server in the Portkey MCP gateway. It covers
the URL, the static Authorization: Bearer <token> header, the identity
forwarding through X-User-Claims, and an address filter at the proxy.
Reading the output¶
Structured content¶
Each tool returns structured content of the form {envelope, error}:
| Key | Content |
|---|---|
envelope |
the JSON format 2 envelope of Output: format, command, detail, input, results, holes, unresolved and notes, plus summary for search, lookup and snapshot_diff; null when the call failed |
error |
null, or {code, text, options, needs} when the call failed |
The output schema of each tool holds the JSON schema of its output. The envelope
schemas are also in schemas/out/ and in the resources below.
| Detail | Content |
|---|---|
summary |
what a model needs to answer: the answer line, needs, the verdict, the fidelity and its reasons, the doubts, the zones and the deciding point; a path hop keeps its device, vsys, snapshot, zones, route, doubts and check verdicts; a diff counts its changes |
full |
the envelope that proteus … --output json --detail full prints: every candidate, stage and lookup |
Ask for full when a person wants the reasoning behind each stage. The summary is
much shorter and leaves more room in the model's context.
A client that passes only text to the model gets a text content too. It lists the
summary's answer line, then each result's answer line, fidelity: <level> and
each needs line. The hole:, unresolved: and note: lines follow. An error
gives <code>: <text>, its options and its needs.
Reason codes and needs¶
Every reason in an answer is a {code, text} object. The code comes from one
closed registry and reads <class>.<name>, such as doubt.service-no-port or
note.snapshot-stale. See Reason codes.
A result that the server holds back, such as an undecided verdict or a NAT rule in
doubt, carries needs: the inputs that can decide it. Each entry is
{code, input, text}:
| Code | Input | When |
|---|---|---|
input.protocol |
protocol |
a rule's service needs the protocol, and the call gave none |
input.port |
port |
a rule's service, a NAT rule or a PBF rule on the path needs the destination port |
input.url |
url |
a rule names a URL category that the configuration defines |
input.application |
application |
a rule names an application or uses application-default, the call gave no application, and the snapshot has App-ID data |
needs: [] means that no input can decide the result. Examples are a predefined
service that the snapshot does not hold, an application that the App-ID data does
not hold, an application without App-ID data, and a PAN-DB category. A snapshot
lacks a predefined service when it was stored before this release or the device
refused it. A decided result has no needs key.
Errors¶
A failed call returns error with one of the call.* codes and sets the MCP
isError flag. Holes, unresolved entries and undecided verdicts come back as a
normal answer with error null.
| Code | Cause | What to do |
|---|---|---|
call.usage |
the inputs are not a valid question | fix the input; text names the input field |
call.choice |
no single start device or router | pick one of options; needs names the input (device or router) |
call.busy |
the queue is full, the call waited max_wait, or the server is stopping |
call again later |
call.timeout |
the call ran longer than call_timeout, or the client cancelled it |
ask a narrower question, or call again later |
call.internal |
the server failed while it answered | report it; the server keeps running |
An input that breaks the input schema, such as a device name outside the enum,
gets the SDK's own error text and no structured content. The audit records it as
usage.
Over HTTP, some requests do not reach a tool:
| Condition | HTTP status |
|---|---|
allowed_hosts is set, and the Host header is not in it |
403 |
| no bearer token, or a wrong one | 401, with WWW-Authenticate: Bearer |
| a body above 1 MiB | 413 |
| a header block above 16 KiB | 431 |
/healthz needs no token and no allowed Host. It answers 200 with no body.
Resources and instructions¶
| URI | Content |
|---|---|
proteus://reasons |
every reason code: code, class, description |
proteus://schemas/<tool>/<detail> |
the JSON schema of a tool's envelope in one detail, for each of the six tools and both details |
proteus://limits |
a summary of Limits for a model |
The server gives the client these instructions:
Report each result's verdict together with its fidelity level. Never report an undecided result, or a fidelity of inferred or undermatch, as allowed or denied. Ask the user for each input a result's needs list names, and call again with it. When a note says a snapshot is stale, state the snapshot's age. On the error call.choice, ask the user to pick one of the options and call again with it.
Audit and run logs¶
The server appends one JSON line per call to audit_log, with mode 0600. Before
a line takes the file past audit_max_mb, the server renames the file to
<audit_log>.<UTC time>-<sequence> and starts a new one. It keeps the newest
audit_keep renamed files. With audit_log: - and --http, the lines go to
standard output, and the container platform collects and keeps them.
{"time":"2026-10-10T08:00:00Z","auth":"token","identity_source":"header","identity":{"sub":"alice"},"tool":"simulate_policy","input":{"source":"198.18.1.10","destination":"198.18.10.100","port":443},"verdict":["allowed"],"verdict_count":1,"codes":[],"snapshots":["fw01@2026-10-10T07-00-00Z","fw02@2026-10-10T07-00-00Z"],"duration_ms":120,"status":"ok"}
| Field | Content |
|---|---|
auth |
token over HTTP, stdio over stdio |
identity_source |
header, none (header missing or not a JSON object) or os (stdio) |
identity |
the audit_claims of the identity header, each cut to 256 bytes; the operating system user over stdio; unknown when none is found |
tool, input |
the tool and its inputs as the client sent them |
verdict |
the answer lines: the summary line and the first 20 result lines |
verdict_count |
the number of answer lines the client received; more than the lines in verdict when a broad answer was cut; with limit, the lines of the shortened answer |
codes |
the reason codes of the holes, unresolved entries and notes |
snapshots |
the snapshots that the answer read, as <member>@<snapshot id>: for an HA pair the member whose snapshot answered, for a single device the device |
duration_ms |
the time the call took |
status |
ok, usage, choice, busy, timeout or internal |
code |
the call.* code of a failed call |
The audit holds only the calls that reached the server. A refused HTTP request
(401 or 403) gets no audit line. While requests are refused, the server's run log
gets one warning per minute with the counts by status, such as
mcp: refused since the last report: 401 ×3, 403 ×1. A count shows a wrong token
or Host, and the logs of the gateway and the proxy show who sent the requests.
The audit lines hold identities and the addresses in the tools' inputs, so treat them as sensitive. The token never reaches the audit or a log.
A call that ends internal or timeout writes its own run log in log_dir,
named mcp-<tool>-<time>-<seq>.log:
| Content | Detail |
|---|---|
| the call | the input, the snapshot each device resolved to, what each stage kept, and at the end the status, the code and the duration |
| a panic | its stack |
| a call that timed out | its work goes on until it returns; the log stays open and also holds what the work logged late and the stack of a later panic |
On SIGTERM the server waits for timed-out work only until it stops: at most
call_timeout over stdio, and call_timeout + max_wait + 10 s over HTTP. What
the work logs after that is lost, and the lines written before stay.
Any other call keeps its log in memory and drops it, because its answer explains
itself in its reasons and codes. With --log-level debug (or log_level: debug),
every call writes its run log. The newest log_keep logs stay. A call that the
server refuses as busy gets an audit line and no run log.
The server process also writes one CLI run log in the CLI's log directory. It holds the start, the settings, the refusal counts and the exit.
Flags¶
Each setting comes from, in rising precedence: its default, the export's mcp:
section, a PROTEUS_MCP_* variable, and a flag. PROTEUS_MCP_TOKEN holds the
token itself, and no flag sets it. The mcp section
lists every key, its variable and its flag.
| Flag | Default | Description |
|---|---|---|
--http |
off | serve Streamable HTTP on --listen instead of stdio |
--listen |
127.0.0.1:8765 |
host:port for --http |
--token-file |
none | the file that holds the bearer token; see The token |
--allowed-host |
none | a Host header value that --http answers; repeatable; none accepts any Host; see Host check |
--audit-log |
none | the audit file, one JSON line per call, or - for standard output with --http; required with --http |
--audit-max-mb |
100 |
the audit file's size in MB before it rotates |
--audit-keep |
10 |
rotated audit files kept |
--max-concurrent |
4 |
calls answered at once |
--max-queue |
16 |
calls waiting for a slot, and loads waiting for --max-loads |
--max-wait |
10s |
how long a call waits for a slot |
--call-timeout |
60s |
how long a call runs before it gets call.timeout |
--max-loads |
2 |
snapshot loads and index builds at once |
--max-cache |
2048 |
the cache of loaded snapshots, in MB |
The server reads the user snapshot
that PROTEUS_USERS names once, at start. Every call answers from that copy, so a
changed file needs a server restart.
SIGTERM stops new calls and lets the running calls answer. An answer is written at
most call_timeout + max_wait + 10 s after its request. The whole stop ends
within that time, also when a call's work does not return or a client keeps its
request open. The server then closes what is left and exits 143. Set the
container's stop grace period to at least call_timeout + max_wait + 20 s: 90 s
with the defaults, as stop_grace_period in the sample. With a shorter grace, the
platform can kill the server while calls still answer.
Cache size¶
The cache keeps each loaded snapshot and its indexes. It counts these items:
| Item | Size it counts |
|---|---|
| a loaded configuration | 32 MB plus 13 times its file size |
| the schema digest | 10 MB, once |
| an App-ID content version | 12 MB; the devices with one content version share its item |
The cache frees an old content version as it frees an old snapshot. Size
--max-cache with that model and the number of devices. For example, 20 devices
with 8 MB configurations and two content versions need about
20 × (32 + 13 × 8) + 10 + 2 × 12 = 2,754 MB.
BenchmarkCacheRetention in internal/mcp measures the model on two generated
shapes at about 4 and 8 MB:
| Shape | Retained |
|---|---|
| one vsys with 2,000 nested address groups | 29.3 MB plus 12.8 bytes per file byte; the fixed part is the group tree |
| four vsys with nested groups and NAT and PBF rules | 0.35 MB plus 12.7 bytes per file byte |
| the schema digest | about 9 MB; the benchmark fails above 10 MB |
| one content version of 5,552 applications | about 9 MB; the benchmark fails above 12 MB |
The model takes the larger value of each part, rounded up, so it overstates most configurations: a small one by up to 32 MB.
Exit codes¶
The server checks its setup before it answers, and a failed check stops it:
| Code | Cause |
|---|---|
| 0 | over stdio, the client closed the stream |
| 1 | the export cannot be read, the store cannot be opened, the address cannot be listened on, or the audit file cannot be opened |
| 2 | the export is missing (run proteus fetch first) |
| 2 | the export holds a credential, cannot be parsed, or has no device |
| 2 | --http without a token, with a token shorter than 32 bytes, or without audit_log |
| 2 | audit_log: - over stdio, where standard output carries MCP |
| 2 | the PROTEUS_USERS file is missing, cannot be read, or is not a valid user snapshot |
| 130 | Ctrl-C |
| 143 | SIGTERM, after the running calls answer |
Limits¶
- The server answers with the same limits as the command line.
- Its data is as fresh as the last
proteus fetch. - Proteus does no authorization, and a token holder can forge the identity.
- A timeout cannot interrupt a snapshot load or an index build.
Limits of the MCP server lists them all.
Model check¶
The tests prove that the server gives the right JSON. They cannot prove that a model reads it right. The model check asks a model questions through the server and checks its replies against four rules. Run it with the model and the gateway that the chatbot uses, after each change of model or of the instructions.
Use the lab flows of the policy path probe, and one host name:
| # | Flow | Expected answer from Proteus |
|---|---|---|
| A | 198.18.1.10 -> 198.18.10.100 tcp/443 (fw02 to fw01) | allowed |
| B | 198.18.10.100 -> 198.18.1.10 tcp/22 (the reverse) | undecided on fw01: a rule with service application-default |
| C | 198.18.1.68 -> 198.18.10.100 udp/443 | denied by a rule |
| D | 198.18.1.10 -> 203.0.113.10 tcp/443 | undecided: the path leaves the estate |
| E | 198.18.1.10 -> 198.18.10.100 without a port | held back; needs asks for the port |
| F | 198.18.1.10 -> a host name that the server's DNS resolves to 198.18.10.100 | as A, with the DNS notes |
Adapt the addresses to the lab's current rules. Run each flow with
proteus simulate policy … --output json first, and write down the answer that
Proteus gives. The model check compares the model's reply with that answer.
Ask each question in a new conversation, in the user's words:
| # | Question | Flow |
|---|---|---|
| 1 | "Can 198.18.1.10 reach 198.18.10.100 on 443?" | A |
| 2 | "Is SSH from 198.18.10.100 to 198.18.1.10 allowed?" | B |
| 3 | "Why is it undecided?" | B, as a follow-up to question 2 |
| 4 | "Is QUIC from 198.18.1.68 to 198.18.10.100 blocked?" | C |
| 5 | "Can 198.18.1.10 reach 203.0.113.10 on 443?" | D |
| 6 | "Can 198.18.1.10 reach 198.18.10.100?" | E: the model must ask for the port |
| 7 | "Can 198.18.1.10 reach |
F |
| 8 | "Which firewalls does traffic from 198.18.1.10 to 198.18.10.100 cross?" | |
| 9 | "What NAT does fw01 apply to traffic from 198.18.1.10 to 198.18.10.100 on 443?" | |
| 10 | "Where is 198.18.10.100 used in the rules?" | |
| 11 | "What changed on fw01 since yesterday?" | |
| 12 | "Which route does traffic to 198.18.10.100 take?" | no source, so the start is a choice: the model must offer the options |
At least one question must reach a device whose snapshot is stale, so that you can check rule 3. In the lab, fw01 is often unreachable, and its snapshot is old.
The check passes when every reply follows all four rules:
- No undecided, inferred or undermatch answer is reported as allowed or denied.
- Every
needsinput is asked back to the user. - The snapshot age is stated when a note says that the snapshot is stale.
- A
call.choiceerror leads to a question that offers the options.
A reply that states a verdict Proteus did not give also fails.
Write the result in Limits under the date:
- the model and its version, the gateway, and the Proteus version
- for each question: the tool calls the model made, pass or fail, and for a fail the rule it broke and the reply in one line
- the total, such as "12 of 12 passed"
Keep each failed reply in the record. A fail shows where the instructions or a description need better words.