Skip to main content

MCP integration

Netra ships a Model Context Protocol (MCP) server, netra-mcp, that exposes a running controller's HTTP API as MCP tools over stdio — so an AI agent such as Hermes Agent, or any other MCP client (Claude Desktop, etc.), can observe and, if enabled, act on a Netra deployment without hand-rolling HTTP calls.

Why this exists​

Hermes Agent (and MCP clients generally) connect to external capabilities exclusively through MCP servers — stdio child processes speaking JSON-RPC 2.0. Netra already has a rich, audited HTTP control plane (internal/api); netra-mcp is a thin, stdlib-only translation layer between that API and the MCP wire protocol. It adds no new capability of its own — every read and every mutation it exposes is something netractl could already do, with the same auth, the same lease/preflight safety machinery, and the same audit trail.

Architecture​

MCP client (Hermes Agent, Claude Desktop, ...)
│ JSON-RPC 2.0, one message per line, over stdin/stdout
▼
netra-mcp (cmd/netra-mcp)
│ internal/mcpserver: generic, Netra-agnostic protocol engine + tool registry
│ tools_read.go / tools_mutate.go: one MCP tool per controller endpoint
│ client.go: plain net/http, mirrors cmd/netractl's auth/env conventions
▼ HTTPS + Bearer token
Netra controller (cmd/netrad, internal/api)

netra-mcp is a single, long-lived stdio process per MCP client session. It holds no state of its own beyond the HTTP client configuration read from its environment at startup — every tool call is a fresh HTTP request to the controller, and every response is relayed back essentially verbatim (see Response shape). There is no caching, batching, or local policy evaluation in netra-mcp itself.

Build and run​

go build -o bin/netra-mcp ./cmd/netra-mcp

netra-mcp is a stdio process, not a daemon: an MCP client launches it, owns its lifecycle, and talks to it over its stdin/stdout. It never listens on a port, and it exits when its stdin is closed (the client disconnects).

To smoke-test it manually before wiring up a real MCP client, run it directly and paste JSON-RPC lines by hand:

NETRA_URL=https://127.0.0.1:30870 NETRA_API_KEY=... ./bin/netra-mcp
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"netra_status","arguments":{}}}

Each line you type after startup should produce one corresponding JSON-RPC response line (the notifications/initialized message, if you send it, produces none — see Response shape). Press Ctrl-D to close stdin and let the process exit.

Install from the MCP Registry (OCI)​

netra-mcp is listed in the MCP Registry as io.github.zyvorai/netra (live since v0.30.1) and ships as the multi-arch, cosign-signed image ghcr.io/zyvorai/netra-mcp. Registry entries are published from server.json by the publish-mcp job in .github/workflows/release.yml on every v* tag. The image carries the io.modelcontextprotocol.server.name label the registry uses to verify ownership.

Client configuration (any stdio MCP client):

{
"mcpServers": {
"netra": {
"command": "docker",
"args": ["run", "-i", "--rm",
"-e", "NETRA_URL", "-e", "NETRA_API_KEY",
"ghcr.io/zyvorai/netra-mcp:0.32.0"],
"env": { "NETRA_URL": "https://netra.example:30870", "NETRA_API_KEY": "..." }
}
}
}

Mutating tools stay disabled unless NETRA_MCP_ALLOW_MUTATIONS=true is also passed; policy apply remains plan-token and risk-confirm gated and enforcement stays leased.

Use it​

Needs a running Netra controller and an API key.

Claude Code:

claude mcp add netra \
-e NETRA_URL=https://<controller>:30870 -e NETRA_API_KEY=<key> \
-- docker run -i --rm -e NETRA_URL -e NETRA_API_KEY ghcr.io/zyvorai/netra-mcp:0.32.0

Claude Desktop and other stdio clients use the JSON above. Then ask in plain language ("Why are payments-api connections timing out?", "Which kernel function is dropping traffic from namespace prod?", "Draft a containment rule for this IP, but don't apply it."). Inside the container 127.0.0.1 is the container, so use the node address or --network host; set NETRA_TLS_INSECURE=true only for a self-signed lab controller.

Environment variables​

VarDefaultNotes
NETRA_URLhttps://127.0.0.1:30870Base URL of the Netra controller, same convention as netractl
NETRA_API_KEYunsetBearer token; must match the controller's NETRA_API_KEY. If the controller has no API key configured, leave this unset too
NETRA_TLS_INSECUREfalseSet true to skip TLS verification against a local/self-signed controller. Never set this against a controller reachable over an untrusted network
NETRA_MCP_ACTORmcp:hermesRecorded as X-Netra-Actor on every call, so mutations show up distinctly from human netractl use in netra_audit. Set a more specific value (e.g. mcp:hermes:oncall-bot) if you run several agent identities against the same controller
NETRA_MCP_ALLOW_MUTATIONSfalseWhen unset/false, only read tools and pure-generator tools are registered — the 60 mutating tool names do not exist in the running process at all. Set true (case-insensitive) to also register them

Example:

export NETRA_URL=https://netra.prod.internal:30870
export NETRA_API_KEY=$(cat /run/secrets/netra-api-key)
export NETRA_MCP_ACTOR=mcp:hermes:prod
export NETRA_MCP_ALLOW_MUTATIONS=false # explicit, even though it's the default

Hermes Agent configuration​

Add a server entry to Hermes's ~/.hermes/hermes-agent/config.yaml:

mcp_servers:
netra:
command: "/path/to/bin/netra-mcp"
args: []
env:
NETRA_URL: "https://127.0.0.1:30870"
NETRA_API_KEY: "..."

Then, from a Hermes session:

hermes mcp test netra

should report a successful handshake and list the 155 read tools. Run /reload-mcp inside a chat session after changing config.yaml to pick up changes without restarting Hermes entirely.

Mutations stay off by default even with this config — NETRA_MCP_ALLOW_MUTATIONS must be added explicitly on the netra-mcp process's own environment, not just in Hermes's config. A conservative read-only-by-convention setup, worth keeping even once mutations are enabled server-side, restricts which tools Hermes is allowed to call at all via tools.include:

mcp_servers:
netra:
command: "/path/to/bin/netra-mcp"
env:
NETRA_URL: "https://127.0.0.1:30870"
NETRA_API_KEY: "..."
tools:
include:
- netra_status
- netra_agents
- netra_pods
- netra_vms
- netra_flow_summary
- netra_flow_history
- netra_investigate_connection
- netra_drops_explain
- netra_ebpf_health
- netra_ebpf_path
- netra_ebpf_drops
- netra_ebpf_diagnose
- netra_insights_summary
- netra_insights_exposure
- netra_insights_recommendations
- netra_audit

NETRA_MCP_ALLOW_MUTATIONS is the real gate — mutating tool names don't exist in the process at all when it's unset, so a mismatched or missing tools.include can't accidentally expose one. tools.include is defense-in-depth on the Hermes side, worth setting regardless of the env var, since it also limits which read tools an agent persona can see (useful if an agent should only ever look at, say, one namespace's worth of concerns via netra_workload_detail and never touch cluster-wide policy listings).

Security considerations​

  • One API key, one privilege level. Netra's controller has a single NETRA_API_KEY bearer token with no scoping — netra-mcp inherits whatever that token can do. There is no way to hand an MCP client a token that can read but not mutate; the only mutation gate is NETRA_MCP_ALLOW_MUTATIONS on the netra-mcp process itself. Run a dedicated netra-mcp process (with mutations enabled) separately from any process serving human dashboards or other integrations, so a compromised or misbehaving agent's blast radius is limited to what this specific process was allowed to do.
  • Every mutation is attributed and audited. All 60 mutating tools flow through the controller's existing audit log (store.appendAuditLocked), tagged with the X-Netra-Actor value from NETRA_MCP_ACTOR (default mcp:hermes). Check netra_audit (or GET /api/v1/audit) regularly if you enable mutations for an autonomous agent — this is the primary way to notice an agent doing something unexpected.
  • Policy apply is the highest-consequence tool, and it's the most guarded. netra_policy_apply requires a fresh plan_token from netra_policy_plan (single-use, content-hash-bound, 5-minute expiry) and, for high/critical-risk changes, an explicit confirm_risk echo. An agent cannot apply a policy it hasn't just planned, and cannot silently escalate past a risk warning — the confirmation string must appear as a literal argument value, which means the calling model has to have "read" the risk level and intentionally repeated it back, not just retried blindly.
  • Enforce mode is time-bounded by design. netra_ebpf_mode can flip the whole fast path from observe to enforce, but every enforce period requires a lease (1m-24h, default 15m) and the controller auto-reverts to observe on expiry (store.SetMode's fail-open behavior) — an agent cannot leave the cluster in enforce mode indefinitely by mistake; the lease must be actively renewed.
  • Baseline/rate-baseline clears require a literal confirmation value, sent automatically by netra-mcp itself (X-Netra-Confirm-Baseline-Clear: clear) — this exists to stop an accidental clear via a generic scripted client, not to add friction for netra-mcp's own calls; treat netra_insights_baseline_clear/netra_insights_rate_baseline_clear as fully live once mutations are enabled.
  • No credential management in netra-mcp itself. It reads NETRA_API_KEY from its own process environment once at startup; it does not fetch, rotate, cache to disk, or log the key. Rotate the controller's API key the same way you would for any other client (update the env var, restart netra-mcp).
  • flows/stream and raw cluster secrets are out of reach. The tool set is a strict subset of the controller's HTTP API (see Not included); there is no path from any tool to raw Kubernetes Secret contents or arbitrary cluster API access — everything goes through Netra's own handlers, which only ever touch CiliumNetworkPolicies, its own eBPF fast-path config, and read-only workload/pod/VM listings.

Response shape​

Every tool call returns an MCP tools/call result of the form:

{"content": [{"type": "text", "text": "<JSON body>"}], "isError": false}

text is the controller's JSON response, pretty-printed. On a non-2xx HTTP status, isError is true and text contains {"status": <code>, "body": <parsed or raw body>}. On a transport failure (DNS, connection refused, TLS handshake failure, timeout), isError is also true and text is the Go error string (e.g. dial tcp ...: connect: connection refused). A tool call is never a JSON-RPC protocol-level error — only a genuinely malformed request (bad JSON, unknown method, unknown tool name) is; see internal/mcpserver's doc comments for the exact rationale.

Prompts​

netra-mcp advertises MCP prompts (prompts/list, prompts/get) in addition to tools. They are canned operator workflows — the client still has to call tools to do any work.

PromptArgumentsIntent
netra_triage—Start with netra_ai_brief, stay read-only
netra_explain_dropsnamespace, pod (optional)Combine netra_ai_ask with drop/diagnose tools
netra_draft_rulerequest (required)Turn a deny/rate sentence into a preview rule via netra_ai_draft; never applies
netra_oncall_digest—Produce the on-call card via netra_ai_digest; if the fingerprint changed, quote whyChanged/whyChangedProse rather than guessing at a cause
netra_congestion_triagewindow (optional)Kernel-network congestion via netra_ai_congestion_brief
netra_incident_timelinesince (optional)Narrate netra_incidents_timeline's entries in order; forbids inventing entries/causes/timestamps
netra_policy_reviewnamespace, workload (optional)Review drafts via netra_insights_policy_review; forbids apply / mode changes
netra_tls_triage—Rare JA3 + ECH-blind
netra_security_review—Optimizer + incidents + intel
netra_metrics_oncallwindow (optional)Alerts + anomalies + congestion
netra_netlink_churn—RTNL findings
netra_ai_destinations_review—GenAI/MCP catalog matches
netra_shadow_saas—Shadow SaaS + app categories
netra_capture_status—Capture status + summaries
netra_fleet_rollcall—Fleet + clusters + metrics fleet
netra_investigate_connectionnamespace, pod, peer, portFailed-connection timeline
netra_flow_observenamespace, podHistory + RED + traces
netra_ebpf_maps_review—Map inventory under /sys/fs/bpf/netra
netra_suggest_then_ask—Suggestions → agent

See docs/ai.md for the controller-side brief/ask engines those prompts lean on.

Resources​

netra-mcp also advertises MCP resources (resources/list, resources/read) — read-only, URI-addressed snapshots a client can fetch without a tool call. Each resource's Read callback calls the same controller endpoint a matching tool would.

URIEndpointNotes
netra://ai/briefGET /api/v1/ai/briefLive heuristic brief
netra://ai/digestGET /api/v1/ai/digestOn-call card + incident fingerprint
netra://ai/congestionGET /api/v1/ai/congestion-briefKernel-network congestion brief
netra://ai/suggestionsGET /api/v1/ai/suggestionsSnapshot-derived follow-up questions
netra://statusGET /api/v1/statusController status
netra://incidentsGET /api/v1/incidentsCross-signal incident clusters
netra://incidents/timelineGET /api/v1/incidents/timelineChronological audit + health-signature-transition merge
netra://ebpf/healthGET /api/v1/ebpf/healthTCP health anomalies
netra://ebpf/tls-riskGET /api/v1/ebpf/tls-fingerprints/riskRare JA3 / ECH
netra://ebpf/tls-fingerprintsGET /api/v1/ebpf/tls-fingerprintsJA3/JA4 samples
netra://ebpf/mapsGET /api/v1/ebpf/mapsDesired map inventory
netra://ebpf/ai-destinationsGET /api/v1/ebpf/ai-destinationsGenAI/MCP matches
netra://ebpf/app-categoriesGET /api/v1/ebpf/app-categoriesHeuristic categories
netra://insights/exposureGET /api/v1/insights/exposureExposure findings
netra://insights/redGET /api/v1/insights/redRED board
netra://insights/tracesGET /api/v1/insights/tracesInferred spans
netra://flows/historyGET /api/v1/flows/historyNative flow history
netra://security/incidentsGET /api/v1/security/incidentsSecurity correlation
netra://complianceGET /api/v1/complianceCompliance packs
netra://handoffGET /api/v1/handoff?format=jsonOn-call pack

Complete tool reference​

All tool names are prefixed netra_. Every tool maps 1:1 to one Netra controller endpoint (internal/api/server.go), so behavior, validation, and error responses are identical to calling that endpoint directly with netractl or curl. Parameters listed as (path) are required and substituted directly into the URL; everything else is optional unless marked required.

Status & inventory (always available)​

ToolEndpointParametersNotes
netra_ai_statusGET /api/v1/ai/status—Whether the optional LLM rewrite path is configured. Heuristic briefs always work
netra_ai_briefGET /api/v1/ai/brief—Deterministic cluster brief from live aggregates. Read-only, no payloads
netra_ai_askPOST /api/v1/ai/askquestion (required), namespace, preferLlmNatural-language question over the same snapshot. Optional LLM rewrite lives on the controller (NETRA_AI_API_KEY), not in netra-mcp. Always stateless here — the endpoint's optional conversationId multi-turn memory (see docs/ai.md#conversation-memory) is a web/ChatOps feature; an MCP-calling agent already has its own conversation as context
netra_ai_draftPOST /api/v1/ai/draftquestion (required)Parses a deny/rate sentence into a preview eBPF rule (body + netractl line). Never applies it
netra_ai_digestGET /api/v1/ai/digest—On-call card: severity, incident fingerprint, copy-paste text. Fingerprint is stable across counter chatter; when it changed, whyChanged (and optionally whyChangedProse) explains exactly what moved
netra_ai_suggestionsGET /api/v1/ai/suggestions—Live follow-up questions derived from the current snapshot
netra_ai_explainPOST /api/v1/ai/explainkind, subject, message, severity, page, question (all optional)Narrates one structured page finding against the live snapshot
netra_ai_agentPOST /api/v1/ai/agentquestion (required), namespace, preferLlm, conversationIdIn-process NL graph (classify → optional draft preview → synthesize). Read-only. conversationId is a web/ChatOps feature — leave empty from MCP
netra_statusGET /api/v1/status—Fast-path config, agent counts/staleness, baseline state, Hubble/HA/Cilium flags
netra_agentsGET /api/v1/agents—One entry per reporting node agent
netra_auditGET /api/v1/auditlimit (1-500, default 100)Every mutating action recorded by the controller, including this MCP server's own
netra_export_auditGET /api/v1/export/auditformat (json/jsonl/cef/syslog/otlp), limit (1-500, default 100)SIEM encodings of the same audit log. Observe-only. See docs/siem-export.md
netra_export_eventsGET /api/v1/export/eventsformat, include (anomaly,incident,audit), limitCurrent anomalies/incidents (optional audit) in the same encodings
netra_reportGET /api/v1/reportformat (markdown/json)Point-in-time operator briefing. Never applies policy or extends a lease
netra_playbooksGET /api/v1/playbooksformat (json/markdown)Review-only operator steps. autoApply is always false
netra_audit_summaryGET /api/v1/audit/summarylimit, since, untilActor/action/hour rollup of the audit log
netra_export_flowsGET /api/v1/export/flowsformat, limitDestination-flow counters as SIEM records. No payloads
netra_export_blocksGET /api/v1/export/blocksformat (adds otlp-trace), limitBlocked/dropped events as SIEM records; otlp-trace renders each as one OTLP span. No payloads
netra_talkersGET /api/v1/talkerslimit (1-200, default 20)Top destination IPs by packet count across current agent reports
netra_namespace_heatGET /api/v1/namespaces/heatlimit (1-200, default 30)Packets/bytes/blocked rolled up by Kubernetes namespace
netra_protocolsGET /api/v1/protocols—L4 protocol mix (TCP/UDP/…) across current destination stats
netra_ebpf_censusGET /api/v1/ebpf/census—Counts of deny/allow list entries. Never returns the entries themselves
netra_ebpf_mapsGET /api/v1/ebpf/maps—Read-only desired map inventory (deny/allow/rate/policy entries + limits). Not a raw bpftool dump. See docs/ebpf-maps.md
netra_baselinesGET /api/v1/baselines—Whether behavior and rate baselines exist and how old they are
netra_portsGET /api/v1/portslimit (1-200, default 30)Top destination ports by packet count
netra_dns_boardGET /api/v1/dns/boardlimit (1-200, default 30)DNS names ranked by failure count
netra_leaseGET /api/v1/lease—Enforce-mode lease clock: remaining seconds, expired, or none
netra_capture_statusGET /api/v1/capture/status—Every node with an active packet-capture session (includes backend and auto-capture requestor). Never returns captured packets
netra_export_statusGET /api/v1/export/status—Whether syslog push is configured
netra_ebpf_coverageGET /api/v1/ebpf/coverage—Per-node hook/program coverage matrix
netra_intel_previewPOST /api/v1/intel/previewtext (raw feed body)Parse JSON/CSV/bare IPs into deny-import entries. Applies nothing
netra_intel_feed_getGET /api/v1/intel/feed—Active threat-intel feed status/entries
netra_intel_hitsGET /api/v1/intel/hits—Match active feed against live agents (observe-only)
netra_ebpf_ai_destinationsGET /api/v1/ebpf/ai-destinations—Observe known GenAI/MCP SaaS via SNI/Host/DNS
netra_ebpf_auto_mitigateGET /api/v1/ebpf/auto-mitigate—Volumetric auto-mitigation status
netra_ebpf_auto_mitigate_previewGET /api/v1/ebpf/auto-mitigate/preview—Shadow candidates from scan/UDP rules; applies nothing
netra_ebpf_deny_previewPOST /api/v1/ebpf/deny/previewkind, value, optional direction/protocol/scopeObserved-counter blast radius for a proposed deny. Applies nothing
netra_ebpf_deny_preview_historyPOST /api/v1/ebpf/deny/preview-historysame as deny preview plus optional sinceHistorical blast radius over flowlog deltas via counterfactual. Applies nothing
netra_ebpf_dns_findingsGET /api/v1/ebpf/dns-findings—Metadata-only DNS anomaly findings (tunneling, DGA, beaconing, storms) from a continuously-running detector. Returns 409 if disabled
netra_ebpf_scan_findingsGET /api/v1/ebpf/scan-findings—Port-scan/fan-out/lateral-movement/SYN-flood findings from a continuously-running detector. Returns 409 if disabled
netra_netlinkGET /api/v1/netlinkview, node, kind, since, limitRead-only RTNL change recorder
netra_netlink_findingsGET /api/v1/netlink/findingswindow, nodeLevel-triggered netlink findings
netra_ebpf_attachmentsGET /api/v1/ebpf/attachmentsnodeBPF attachment inventory / hook drift; never reattaches
netra_listen_queuesGET /api/v1/listen-queuesnodeTCP listen queue depth
netra_ebpf_stack_histogramsGET /api/v1/ebpf/stack-histogramsnodeSoftirq/softnet + listen depth buckets
netra_capture_summariesGET /api/v1/capture/summarieslimitCapture session metadata; no PCAP bytes
netra_podsGET /api/v1/podsnamespaceLockdown status included per pod
netra_vmsGET /api/v1/vmsnamespaceResult's available field indicates whether KubeVirt is installed
netra_workload_detailGET /api/v1/workloads/{kind}/{namespace}/{name}kind (path, required, pod|vm), namespace (path, required), name (path, required)Phase, node, IP, labels, recommended selector, matching policies
netra_ebpf_configGET /api/v1/ebpf/confignodeLive fast-path config; passing node also includes that node's workload inventory
netra_ebpf_workloadsGET /api/v1/ebpf/workloadsnodeWorkload identity list (pod/cgroup/container attribution)
netra_ebpf_topologyGET /api/v1/ebpf/topologylimit (1-1000, default 100)Derived service/workload topology
netra_ebpf_capabilitiesGET /api/v1/ebpf/capabilities—Static manifest of hooks/observability/enforcement capabilities

Flows & drops (always available)​

ToolEndpointParametersNotes
netra_flow_summaryGET /api/v1/flows/summarynumber (1-5000, default 500), verdict (FORWARDED|DROPPED|ERROR|AUDIT|REDIRECTED|TRACED|TRANSLATED), namespace, pod, direction (EGRESS|INGRESS), protocol, destinationBounded point-in-time aggregate; the tool-shaped equivalent of the flows/stream SSE endpoint, which is not exposed (see Not included)
netra_flow_historyGET /api/v1/flows/historysince (duration or RFC3339, default 1h, max 168h), namespace, pod, peer, protocol, app, node, limit (1-2000, default 200)Flow deltas in a 7-day sidecar (or optional SQLite). No payloads. See docs/flow-log.md
netra_investigate_connectionPOST /api/v1/investigate/connectionnamespace, pod, peer, port, node, window, since, untilComposed failed-connection timeline + confidence. Observe-only. See docs/investigate-connection.md
netra_drops_explainGET /api/v1/drops/explainlimit (1-100, default 20), namespace, podPlain-English summary + remediation suggestions per dropped flow
netra_ebpf_summaryGET /api/v1/ebpf/summary—High-level rollup of fast-path activity across agents
netra_ebpf_healthGET /api/v1/ebpf/healthlimit (1-200, default 20)TCP health/retransmit/connect-latency anomalies
netra_ebpf_capdriftGET /api/v1/ebpf/capdriftlimit (1-200, default 50)Effective-capability gain/loss on tracked processes; agent-sourced from a periodic /proc scan, not a live kernel read; includes a capdrift-coverage-gap finding on recent agent restart
netra_ebpf_nsdriftGET /api/v1/ebpf/nsdriftlimit (1-200, default 50)Network-namespace changes on tracked processes (setns after start); same agent-sourced /proc-scan shape as capdrift, including an nsdrift-coverage-gap finding on recent agent restart
netra_ebpf_exehashGET /api/v1/ebpf/exehashlimit (1-200, default 50)Executable-content-hash changes on tracked processes (observe-only half of exe-hash leased deny); same agent-sourced /proc-scan shape as capdrift, including an exehash-coverage-gap finding on recent agent restart
netra_ebpf_pathGET /api/v1/ebpf/pathlimit (1-500, default 50)Per-hop/per-hook path diagnostics
netra_ebpf_dropsGET /api/v1/ebpf/dropslimit (1-500, default 50)Kernel skb drop-reason counters aggregated across agents
netra_ebpf_diagnoseGET /api/v1/ebpf/diagnoselimit (default 50)Drop-detective root-cause findings correlated with current fast-path config
netra_ebpf_l7GET /api/v1/ebpf/l7limit (1-1000, default 100)Best-effort TLS SNI / cleartext HTTP metadata
netra_ebpf_ipv6GET /api/v1/ebpf/ipv6limit (1-500, default 50)IPv6 extension-header/fragmentation counts and anomalies per node
netra_ebpf_sysctl_auditGET /api/v1/ebpf/sysctl-auditlimit (1-500, default 50)Baseline-checked network-hardening/tuning sysctl inventory (security posture, IPv6, TCP lifecycle, conntrack timeouts, ARP/bridge); most entries are informational by design — see docs/sysctl-audit.md
netra_node_resourcesGET /api/v1/node-resourceslimit (1-200, default 20)Per-node CPU/memory/load-average snapshot plus per-workload cgroup v2 CPU/memory usage, top-N by CPU — a "top"-like view attributed to workloads, not raw PIDs — see docs/node-resources.md
netra_ebpf_interfacesGET /api/v1/ebpf/interfaceslimit (1-200, default 10)Per-interface packets/bytes/blocked + top destinations, from TC/TCX-attached hooks only (not cgroup or XDP-early-deny traffic)
netra_ebpf_shieldGET /api/v1/ebpf/shieldlimit (1-500, default 50)XDP DDoS shield diagnostics: allowed/dropped/audited by class (SYN/UDP/ICMP/other) per node, plus top offending sources, with anomaly detection
netra_ebpf_rules_listGET /api/v1/ebpf/rules—Every eBPF fast-path deny rule with its stable ID, for use with netra_ebpf_rules_patch/_delete/_history instead of the legacy value-keyed add/delete tools
netra_ebpf_rules_getGET /api/v1/ebpf/rules/{id}id (path, required)One rule by its stable ID
netra_ebpf_rules_historyGET /api/v1/ebpf/rules/{id}/historyid (path, required), limit (1-200, default 50)Before/after revision history for one rule's edits via netra_ebpf_rules_patch. Creation/deletion remain visible via netra_audit instead

Insights (always available)​

ToolEndpointParametersNotes
netra_insights_summaryGET /api/v1/insights/summary—Rollup counts across all insight categories
netra_insights_dependenciesGET /api/v1/insights/dependencieslimit (1-5000, default 500)Inferred service dependency graph, including external destinations
netra_insights_baseline_getGET /api/v1/insights/baseline—Currently captured behavior baseline, if any
netra_insights_driftGET /api/v1/insights/drift—How current traffic differs from the captured baseline
netra_insights_recommendationsGET /api/v1/insights/recommendationslimit (1-200, default 50), namespace, workloadSuggested policy changes; result always carries applyRequiresReview: true
netra_insights_ratesGET /api/v1/insights/rateswindow (duration string, 30s-2h, default 5m)Current traffic-rate window
netra_insights_rate_baseline_getGET /api/v1/insights/rate-baseline—Currently captured rate baseline, if any
netra_insights_rate_driftGET /api/v1/insights/rate-driftwindowHow current rates differ from the rate baseline
netra_insights_exposureGET /api/v1/insights/exposurewindowDependency graph combined with behavior + rate drift
netra_insights_blast_radiusGET /api/v1/insights/blast-radiusroot (required), hops (1-6, default 3)Multi-hop observed traffic reachability from one node — never a policy allow/deny determination
netra_insights_health_trendGET /api/v1/insights/health-trendthreshold (0-99, default 50)Linear time-to-breach projection from recent health-score history; confidence is always low/medium, never high
netra_insights_policy_reviewGET /api/v1/insights/policy-reviewrecommendationId (required)Governing-policy resolution + semantic diff + traffic-aware blast radius + revision history for one recommendation; read-only
netra_insights_new_since_startGET /api/v1/insights/new-since-startmaxRestarts (0-disables, default 5)Drift findings whose owning pod/workload started after the captured baseline; baseline-relative, not a precise timing claim
netra_insights_protocol_downgradesGET /api/v1/insights/protocol-downgrades—Workload/host pairs with baseline TLS history now showing cleartext HTTP; coexistence-tolerant correlation, never a verdict; check l7Degraded before reading empty as "clean"
netra_incidentsGET /api/v1/incidentsauditLimit (1-1000, default 200)Cross-signal clusters joining health/drift/rate-drift/exposure/detective/audit findings by shared source; only surfaced with ≥2 contributing signal kinds
netra_incidents_timelineGET /api/v1/incidents/timelinesince (RFC3339, optional)Chronological, human-readable merge of the audit log and cluster-health-signature transitions
netra_insights_remediationsGET /api/v1/insights/remediationslimit (1-200, default 50), windowProposed remediations; result always carries reviewRequired: true, autoApply: false
netra_insights_redGET /api/v1/insights/redwindow (duration, default 5m, max 168h)Per-workload rate, drop/retransmit errors, and TCP SRTT. Not HTTP status. See docs/flow-log.md
netra_insights_tracesGET /api/v1/insights/tracessince (duration, default 15m, max 168h), namespace, podInferred spans from flow edges and pod IPs. No propagated traceparent
netra_insights_profilesGET /api/v1/insights/profiles—Kernel stacks and wchan for the hottest host comms. No argv. Not a user-space flame graph
netra_insights_workload_eventsGET /api/v1/insights/workload-eventsnamespace, podKubernetes Warning events for pods. Not the application journal
netra_insights_kernel_notesGET /api/v1/insights/kernel-notes—Scrubbed kernel lines about netdev, TCP, UDP, conntrack, and OOM
netra_insights_zero_trustGET /api/v1/insights/zero-trustlimitObserve-only Zero Trust drafts
netra_insights_microsegGET /api/v1/insights/microseglimitMicroseg lease drafts (never auto-apply)
netra_insights_shadow_saasGET /api/v1/insights/shadow-saaslimitUnsanctioned SaaS hostname findings
netra_insights_experienceGET /api/v1/insights/experiencelimitPer-workload experience scores (workloads list)
netra_insights_destination_riskGET /api/v1/insights/destination-risklimitDestination risk board (destinations list)
netra_insights_exfilGET /api/v1/insights/exfillimitExfil heuristics (observe-only)
netra_insights_lateralGET /api/v1/insights/laterallimitLateral-movement playbooks
netra_insights_category_denyGET /api/v1/insights/category-denylimitCategory-deny draft CLIs
netra_insights_ech_blindGET /api/v1/insights/ech-blindlimitECH / missing-SNI findings
netra_insights_policy_packsGET /api/v1/insights/policy-packslimitPolicy pack suggestions
netra_insights_identity_draftsGET /api/v1/insights/identity-draftslimitIdentity-based draft rules
netra_ebpf_tls_fingerprintsGET /api/v1/ebpf/tls-fingerprintslimitJA3/JA4 ClientHello samples
netra_ebpf_tls_fingerprint_riskGET /api/v1/ebpf/tls-fingerprints/risklimitRare JA3 / ECH risk rows
netra_ebpf_encrypted_dnsGET /api/v1/ebpf/encrypted-dnslimitDoT/DoH hostname hits
netra_ebpf_app_categoriesGET /api/v1/ebpf/app-categorieslimitHeuristic app/category labels
netra_ebpf_ai_destinationsGET /api/v1/ebpf/ai-destinationslimitGenAI/MCP catalog matches
netra_complianceGET /api/v1/compliance—Compliance packs → controls
netra_report_preventionGET /api/v1/report/prevention—Prevention coverage scorecard

Policies — read & generate (always available)​

None of these mutate the cluster or Netra's store, and none record an audit event.

ToolEndpointParametersNotes
netra_policies_listGET /api/v1/policiesnamespace (default default)Raw CiliumNetworkPolicy list; requires Cilium integration enabled on the controller
netra_policies_historyGET /api/v1/policies/historynamespace, name, limit (1-200, default 50)Recorded revisions: checkpoints, applies, rollbacks, deletes
netra_policies_history_exportGET /api/v1/policies/history/export—Full revision archive as JSON, for backup or netra_policy_history_import on another controller
netra_policy_gitops_statusGET /api/v1/policies/gitops/status—GitOps reconciler status for every manifest under NETRA_GITOPS_DIR; 409 if GitOps is not enabled
netra_policy_buildPOST /api/v1/policies/buildbody: name (required), namespace (required), selector (object), kind, to (array of CIDR/FQDN/entity strings), port, protocol, includeDns (bool)Generates a manifest only — feed the result to netra_policy_plan
netra_policy_lockdownPOST /api/v1/policies/lockdownbody: name (required), namespace (default default), kind (pod|vm, default pod), selector (auto-detected if omitted)Generates a deny-all manifest only — feed the result to netra_policy_plan, or use netra_policy_unlock to remove an already-applied one
netra_policy_simulatePOST /api/v1/policies/simulatebody: manifest (required, raw CNP JSON/YAML)Evaluates candidate egress rules against observed traffic; toFQDNs destinations are always "unverified", never a false "denied"
netra_ebpf_scope_previewPOST /api/v1/ebpf/scope/previewbody: scopes (required, array of objects)Dry match against live pods; does not change the active scope

Policies — mutating (NETRA_MCP_ALLOW_MUTATIONS=true)​

ToolEndpointParametersNotes
netra_policy_planPOST /api/v1/policies/planmanifest (required)Server-side dry-run + risk assessment; returns receipt.token (single-use, 5-minute expiry)
netra_policy_applyPOST /api/v1/policies/applymanifest (required), plan_token (required), confirm_risk (required only if the plan's risk was high/critical)See The plan → apply flow below
netra_policy_rollbackPOST /api/v1/policies/{namespace}/{name}/rollback/{revision}namespace (path), name (path), revision (path), dryRun (bool), confirmRisk (required if risk is high/critical)Pass dryRun: true first to preview; repeat with confirmRisk matching the previewed risk to actually apply
netra_policy_deleteDELETE /api/v1/policies/{namespace}/{name}namespace (path), name (path)Records a checkpoint of the deleted manifest before deleting
netra_policy_unlockDELETE /api/v1/policies/lockdown/{namespace}/{name}namespace (path), name (path, workload name)Deletes the lockdown policy for a workload, restoring normal access
netra_policy_history_importPOST /api/v1/policies/history/importarchive (required, object from netra_policies_history_export), mode (merge|replace, default merge), confirm_replace (bool, required when mode=replace)Discards existing history first when mode=replace
netra_policy_gitops_resyncPOST /api/v1/policies/gitops/resyncmanifest (required), confirm_risk (required only if risk is high/critical)Human override for a manifest the GitOps reconciler declined to auto-apply (drift or risk too high); 409 if GitOps is not enabled

eBPF fast path — mutating (NETRA_MCP_ALLOW_MUTATIONS=true)​

ToolEndpointParametersNotes
netra_ebpf_modePUT /api/v1/ebpf/modemode (required, observe|enforce), lease (duration, 1m-24h, default 15m)Self-limiting: enforce auto-reverts to observe when the lease expires
netra_ebpf_scope_setPUT /api/v1/ebpf/scopemode (required, all|selected), scopes (array, required when mode=selected)Preview matches first with netra_ebpf_scope_preview
netra_ebpf_deny_add / netra_ebpf_deny_deletePOST /api/v1/ebpf/deny / DELETE .../deny/{ip}ip (required), direction (egress|ingress|both, default egress, add only)Exact IPv4 or IPv6 address
netra_ebpf_allow_add / netra_ebpf_allow_deletePOST /api/v1/ebpf/allow / DELETE .../allow/{ip}ip (required)Exact IPv4 or IPv6 allow-exception; evaluated before deny/CIDR/port/rate
netra_ebpf_allow_cidr_add / netra_ebpf_allow_cidr_deletePOST /api/v1/ebpf/allow-cidr / POST .../allow-cidr/deletecidr (required), direction (egress|ingress|both, default egress)CIDR-shaped allow-exception; evaluated before deny/CIDR/port/rate, mirrors netra_ebpf_cidr_add's deny-side shape
netra_ebpf_cidr_add / netra_ebpf_cidr_deletePOST /api/v1/ebpf/cidr / POST .../cidr/deletecidr (required), direction (egress|ingress|both, default egress)
netra_ebpf_syn_drop_add / netra_ebpf_syn_drop_deletePOST /api/v1/ebpf/syn-drop / POST .../syn-drop/deleteaddress (required, exact IPv4 or IPv6), direction (required, egress|ingress — no both, unlike CIDR)Flags an existing exact-IP deny entry so only new TCP SYNs are dropped, not every packet; has no effect without a matching deny entry for the same address+direction
netra_ebpf_port_add / netra_ebpf_port_deletePOST /api/v1/ebpf/port / POST .../port/deleteport (required, 1-65535), protocol (TCP|UDP|ANY, default ANY), direction (default egress)
netra_ebpf_allow_port_add / netra_ebpf_allow_port_deletePOST /api/v1/ebpf/allow-port / POST .../allow-port/deleteport (required, 1-65535), protocol (TCP|UDP|ANY, default ANY), direction (default egress)L4 port allow-exception; evaluated before deny/CIDR/port/rate, mirrors netra_ebpf_port_add's deny-side shape
netra_ebpf_uid_add / netra_ebpf_uid_deletePOST /api/v1/ebpf/uid / DELETE .../uid/{uid}uid (required)Linux UID
netra_ebpf_allow_uid_add / netra_ebpf_allow_uid_deletePOST /api/v1/ebpf/allow-uid / DELETE .../allow-uid/{uid}uid (required)Linux UID exception; evaluated before UID/comm deny at the socket hook, mirrors netra_ebpf_uid_add's deny-side shape
netra_ebpf_dns_add / netra_ebpf_dns_deletePOST /api/v1/ebpf/dns / POST .../dns/deletename (required)Exact plain-DNS query name over UDP/53; no wildcards
netra_ebpf_process_add / netra_ebpf_process_deletePOST /api/v1/ebpf/process / POST .../process/deletename (required)Linux comm, up to 15 bytes
netra_ebpf_allow_process_add / netra_ebpf_allow_process_deletePOST /api/v1/ebpf/allow-process / POST .../allow-process/deletename (required)Linux comm exception, up to 15 bytes; evaluated before UID/comm deny at the socket hook, mirrors netra_ebpf_process_add's deny-side shape
netra_ebpf_capability_add / netra_ebpf_capability_deletePOST /api/v1/ebpf/capability / POST .../capability/deletename (required, CAP_NET_RAW|CAP_NET_ADMIN only)Denies new socket() attempts for any process with this capability effective at the agent's last periodic /proc scan — agent-sourced and TOCTOU-caveated, not a live kernel credential read
netra_ebpf_sni_add / netra_ebpf_sni_deletePOST /api/v1/ebpf/sni / POST .../sni/deletename (required)Exact TLS SNI, best-effort (requires ClientHello parsing); no wildcards
netra_ebpf_rate_set / netra_ebpf_rate_deletePUT /api/v1/ebpf/rate / DELETE .../rate/{ip}destination (required, exact IPv4 or IPv6), pps (1-10000000, set only), bps (bytes/sec, set only) — at least one of pps/bps required, independent of each other
netra_ebpf_shield_setPUT /api/v1/ebpf/shieldmode (off|audit|enforce), protectAll (bool), protectedIpv4/protectedIpv6 (arrays, ignored if protectAll), synPps/udpPps/icmpPps/otherPps (0-10000000, 0 disables that class), burstSecondsXDP DDoS shield: per-source-class PPS token-bucket limiter, independent of the fast-path deny-list. Use audit before enforce to preview what would be dropped
netra_ebpf_netpol_config_setPUT /api/v1/ebpf/netpol/configenabled (required, bool)Enable/disable the legacy per-workload NetPol-emulation deny engine (independent of the fast-path deny-list and the v2 engine below)
netra_ebpf_netpol_v2_config_setPUT /api/v1/ebpf/netpol/v2/configenabled (required, bool)Enable/disable the v2 per-workload allow-list/default-deny engine. An explicit allow rule (netra_ebpf_netpol_rule_add) can override even the flat fast-path deny-list for that workload+peer — deliberate, not a bug
netra_ebpf_netpol_rule_addPOST /api/v1/ebpf/netpol/rulesselector (required, object: namespace/pod/workloadKind/workloadName/labels/cgroupId, at least one field), peerIpv4 (required, exact), port, protocol (default ANY), direction (default egress), action (required, allow|deny)Returns the updated fast-path config with the new rule's assigned id
netra_ebpf_netpol_rule_deleteDELETE /api/v1/ebpf/netpol/rules/{id}id (path, required)From the fast-path config's netPolRules, or the rule_add response
netra_ebpf_netpol_default_deny_planPOST /api/v1/ebpf/netpol/default-deny/planselector (required, object), enabled (required, bool), lease (default 5m, 1m-60m), allowNoRules (bool)Mandatory first step for v2 default-deny: assesses risk (zero covering allow rules ⇒ critical, refused unless allowNoRules) and issues a single-use, 5-minute receipt.token. Deactivating is always low risk. Mutates nothing else
netra_ebpf_netpol_default_deny_set(PUT, path not separately listed)selector/enabled/lease (must exactly match the prior plan call), plan_token (required), confirm_risk (required if the plan's risk was medium+)The single highest-blast-radius mutation in the firewall feature — a workload in default-deny posture only accepts traffic an explicit allow rule permits. Requires a fresh netra_ebpf_netpol_default_deny_plan token
netra_ebpf_conn_rate_limit_addPOST /api/v1/ebpf/conn-rate-limitselector (required, object, at least one field), perSecond (required, >0)Caps new TCP connection attempts per second for matching workloads; checked on connect() only, not UDP. The strictest (lowest) perSecond wins when multiple rules match one workload. Returns the updated fast-path config with the new rule's assigned id
netra_ebpf_conn_rate_limit_deleteDELETE /api/v1/ebpf/conn-rate-limit/{id}id (path, required)From the fast-path config's connRateLimits, or the add response
netra_intel_feed_putPUT /api/v1/intel/feedtext (required)Replace active threat-intel feed; does not apply denies
netra_intel_applyPOST /api/v1/intel/applyconfirm_risk (required, high), matched_only (bool)Requires enforce lease; imports feed (or live hits only) into deny maps
netra_ebpf_ai_destinations_denyPOST /api/v1/ebpf/ai-destinations/denyconfirm_risk (required, high)Lease-deny observed GenAI/MCP SaaS SNI hosts
netra_ebpf_rules_patchPATCH /api/v1/ebpf/rules/{id}id (path, required), plus the fields matching the rule's type (ip for ip4/ip6; cidr+direction for cidr; protocol+port+direction for port; uid for uid; name for dns/sni/process; destination+pps for rate)Edits one rule in place by its stable ID, preserving the ID and recording a before/after revision (see netra_ebpf_rules_history). Same validation as the corresponding add tool
netra_ebpf_rules_deleteDELETE /api/v1/ebpf/rules/{id}id (path, required)Stable-ID equivalent of the legacy value-keyed delete tools
netra_ebpf_rules_rollbackPOST /api/v1/ebpf/rules/{id}/rollback/{revision}id (path, required), revision (path, required)Undoes one specific edit, restoring its pre-edit value — recorded as a new revision rather than rewriting history

Every eBPF mutating tool returns the full updated EBPFFastPathConfig on success.

Packet capture — mutating (NETRA_MCP_ALLOW_MUTATIONS=true)​

ToolEndpointParametersNotes
netra_capture_startPUT /api/v1/vms/{node}/capturenode (required), at least one of protocol/host/port (required — no unfiltered captures), backend (ebpf|afpacket, default ebpf), snapLen, maxPps, durationSeconds (1-300, default 60)Captures full packet bytes by default, which can include cleartext application secrets — prefer a narrow filter. Auto-expires; live packets stream to the Capture dashboard page, not through this tool. Controller-side opt-in auto-capture on critical drops is separate (NETRA_AUTO_CAPTURE, see docs/capture.md) and is not started via this tool
netra_capture_stopDELETE /api/v1/vms/{node}/capturenode (required)Stops an active session before its duration expires

Insights — mutating (NETRA_MCP_ALLOW_MUTATIONS=true)​

ToolEndpointParametersNotes
netra_insights_baseline_capturePOST /api/v1/insights/baseline—Replaces any existing behavior baseline with a fresh snapshot
netra_insights_baseline_clearDELETE /api/v1/insights/baseline—netra-mcp sends the required confirmation header automatically
netra_insights_rate_baseline_capturePOST /api/v1/insights/rate-baselinewindow (duration, 30s-2h, default 5m)Replaces any existing rate baseline
netra_insights_rate_baseline_clearDELETE /api/v1/insights/rate-baseline—netra-mcp sends the required confirmation header automatically

The plan → apply flow​

netra_policy_apply never accepts a manifest on its own — it requires proof that the exact same manifest was just dry-run planned. This is the one place where the calling agent has to carry state between two tool calls:

  1. Call netra_policy_plan with manifest. The result includes plan.risk (low/medium/high/critical) and receipt.token.
  2. If plan.risk is low or medium, call netra_policy_apply with the same manifest and plan_token set to receipt.token.
  3. If plan.risk is high or critical, call netra_policy_apply with the same manifest, plan_token, and confirm_risk set to that exact risk string. Omitting it, or getting the string wrong, is rejected with a 409 (surfaced as an isError: true tool result, not a crash).
  4. The token is single-use and expires after 5 minutes — a stale or reused token, or a manifest that doesn't byte-for-byte match what was planned, is rejected with a 412/428 (also surfaced as isError: true).

netra_policy_rollback has the same two-step shape folded into one tool via dryRun/confirmRisk query parameters instead of a separate token, since a rollback target is already an exact, previously-recorded manifest rather than new arbitrary input.

Troubleshooting​

SymptomLikely causeFix
Every tool call returns isError: true with dial tcp ...: connect: connection refusedNETRA_URL doesn't point at a reachable controllerVerify the controller is running and the URL/port are correct
isError: true, body {"error":"invalid API token"}, status 401NETRA_API_KEY missing or wrongMatch it to the controller's own NETRA_API_KEY
TLS handshake errors against a local controllerSelf-signed certificateSet NETRA_TLS_INSECURE=true (local/dev only)
netra_policy_apply returns status 428 "a fresh preflight receipt is required"Called apply without planning first, or the token expiredCall netra_policy_plan again immediately before applying
netra_policy_apply returns status 409 "preflight risk is high; ... apply with X-Netra-Confirm-Risk: high"Risk is high/critical and confirm_risk was omitted or didn't matchPass confirm_risk equal to the risk string from the plan result
netra_policy_apply / netra_policy_rollback return status 412 "preflight receipt is expired, already used, or does not match this exact policy body"Token reused, expired, or the manifest changed since planningRe-plan the exact manifest you intend to apply
A mutating tool name doesn't appear in tools/list at allNETRA_MCP_ALLOW_MUTATIONS isn't true on the netra-mcp processSet it and restart netra-mcp (Hermes will relaunch the child process)
Any write returns status 507 "could not persist ..."Controller's durable state backend is failing to writeCheck the controller's own logs/storage; this is not specific to MCP
hermes mcp test netra fails outrightBinary path wrong, not executable, or crashes on startupRun netra-mcp manually per Build and run and check stderr

Not included​

  • No flows/stream tool. GET /api/v1/flows/stream is a Server-Sent-Events stream; it doesn't fit a request/response MCP tools/call. netra_flow_summary is the live aggregate. netra_flow_history is the flow sidecar or optional SQLite backend (docs/flow-log.md), not a stream and not a shared warehouse.
  • No netra_ai_forget tool. Conversation memory clear stays on POST /api/v1/ai/forget for the web/CLI (netractl ai forget ID) so agents cannot wipe another client's thread by accident.
  • No arbitrary cluster API or Secret access. Prompts and resources exist (prompts/list, resources/list) but are still a strict subset of Netra's own read APIs — same observe-only boundaries as tools.
  • No additional rate limiting. netra-mcp adds no throttling of its own beyond whatever the controller's own API already enforces.
  • No per-tool credential scoping. See Security considerations — one API key covers everything netra-mcp is allowed to do; the mutation gate is process-wide, not per-tool.
  • No credential management. netra-mcp reads NETRA_API_KEY from its own process environment; it does not fetch, rotate, or store credentials itself.
  • No batching or transactions. Each tool call is one independent HTTP request; there is no way to apply several eBPF rule changes atomically.

Verification in CI​

scripts/ci-mcp-live.sh (job mcp-live) runs the real netra-mcp over stdio JSON-RPC against a real netrad. Read-only by default: the read tools, prompts and resources are listed, a read tool returns the controller's real answer, none of the mutating tools (names read from cmd/netra-mcp/tools_mutate.go) is listed and calling one is refused as unknown, a wrong API key is a tool error not a crash, and malformed input gets a parse error while the server keeps serving. With NETRA_MCP_ALLOW_MUTATIONS=true exactly the source-defined mutating set is added, a deny rule added through MCP reaches the controller and the audit log names the MCP actor (NETRA_MCP_ACTOR), and bad arguments change nothing.

Security review tools​

ToolEndpointBehavior
netra_security_optimizerGET /api/v1/security/optimizerReview flat deny predicates and sampled matching events; no apply
netra_security_incidentsGET /api/v1/security/incidentsExact-workload temporal correlation; no attack verdict
netra_intel_historyGET /api/v1/intel/historyRead retained feed snapshots and expiry; no rollback

See Security intelligence and review. These three tools remain available with mutations disabled.