Source: docs/manual/mcp-operations.md

This page is generated by site/scripts/sync-manual-docs.mjs.

MCP Operations Guide

This guide covers operational MCP workflows around discovery, heartbeat, code-exec tooling, and gateway fleet wiring.

Source: cmd/mcp-announce/*, cmd/mcp-code-exec/*, internal/tools/mcp_announce.go, internal/tools/mcp_bridge.go, internal/mcpgw/*

Operational Topology

Cruvero MCP operations typically involve three paths:

1. Server advertises itself (mcp-announce) over NATS.
2. Cruvero MCP bridge ingests discovery events and exposes tools as mcp.<server>.<tool>.
3. Optional gateway integration publishes/consumes mcpgw.<gateway>.{events|config}.* subjects.

mcp-announce CLI

cmd/mcp-announce discovers tools from an MCP endpoint and publishes lifecycle events.

Flags

Flag	Description
--server	MCP server name (required)
--nats-url	NATS URL for lifecycle events
--transport	`stdio
--endpoint	Required for http and sse transports
--heartbeat	Heartbeat interval (must be > 0)
--prefix	Subject prefix (default from CRUVERO_EVENTS_SUBJECT_PREFIX)

For stdio, pass command args after --.

Examples

HTTP transport:

go run ./cmd/mcp-announce \
  --server weather \
  --transport http \
  --endpoint http://localhost:8089/mcp \
  --heartbeat 30s

Stdio transport:

go run ./cmd/mcp-announce \
  --server local-tools \
  --transport stdio \
  --heartbeat 15s \
  -- ./bin/local-mcp-server --mode prod

mcp-code-exec service

cmd/mcp-code-exec hosts python_exec and bash_exec as MCP tools over streamable HTTP.

Environment variables

Variable	Default	Purpose
MCP_CODE_EXEC_PORT	8080	Listener port
MCP_CODE_EXEC_TIMEOUT	30s	Per-call execution timeout
MCP_CODE_EXEC_MAX_OUTPUT	1048576	Max output bytes returned to caller

Example

MCP_CODE_EXEC_PORT=8088 MCP_CODE_EXEC_TIMEOUT=20s go run ./cmd/mcp-code-exec

If you require MCP routing for code execution, set:

• CRUVERO_CODE_EXEC_MCP_REQUIRED=true

In that mode, runtime code-exec tools fail closed when MCP transport is unavailable.

Discovery and Lifecycle Subjects

mcp-announce publishes to these subjects (with optional custom prefix):

Event	Subject
Announce	<prefix>.mcp.announce
Heartbeat	<prefix>.mcp.heartbeat
Deregister	<prefix>.mcp.deregister

Payload event type values:

• mcp.announce
• mcp.heartbeat
• mcp.deregister

MCP Gateway Subjects

Gateway integration uses fixed mcpgw subjects (not prefixed by cruvero):

Direction	Subject Pattern
Gateway -> Cruvero events	mcpgw.<gateway_id>.events.<event_type>
Cruvero -> Gateway config	mcpgw.<gateway_id>.config.<scope>
Gateway reconnect request	mcpgw.<gateway_id>.config.request

Common event types handled by subscriber:

• server.registered
• server.deregistered
• server.health_changed
• policy.violated

Config scopes published by Cruvero:

• policy
• servers
• server_settings
• auth

Transport Modes

MCP transport selection

CRUVERO_MCP_TRANSPORT supports:

• stdio
• http
• gateway

mcp-announce itself supports discovery over stdio|http|sse; gateway transport is configured in Cruvero runtime MCP settings.

Monitoring and Troubleshooting

1. Check server lifecycle events:

go run ./cmd/event-bus subscribe 'cruvero.mcp.>'

2. Confirm gateway events are flowing:

go run ./cmd/event-bus subscribe 'mcpgw.>'

3. Validate MCP server visibility in UI (admin route):

• /mcp

4. Validate subject prefix consistency:

• CRUVERO_EVENTS_SUBJECT_PREFIX
• --prefix for mcp-announce

5. Validate NATS connectivity and streams:

go run ./cmd/event-bus status
go run ./cmd/event-bus streams

Operational Config Checklist

Variable	Purpose
CRUVERO_EVENTS_BACKEND	Must be nats for event-driven MCP discovery
CRUVERO_NATS_URL	NATS endpoint
CRUVERO_MCP_DISCOVERY	`static
CRUVERO_MCP_HEARTBEAT_INTERVAL	Heartbeat staleness cadence
CRUVERO_MCP_STALE_THRESHOLD	Server stale threshold
CRUVERO_MCPGW_ENABLED	Enable gateway integration path
CRUVERO_MCPGW_GATEWAY_ID	Gateway subject scope id
CRUVERO_MCPGW_TENANT_ID	Tenant context for server/settings publication

Related Docs

• MCP Integration
• Event Bus and NATS JetStream
• Web UI
• CLI Reference