Skip to main content

Source: docs/manual/mcp.md

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

MCP Integration

Cruvero integrates with MCP servers through internal/mcp and internal/tools/mcp_bridge.go. It supports local/static MCP servers, dynamic discovery over the event bus, and scoped integration with cruvero-mcp-gateway.

Source: internal/mcp/*, internal/tools/mcp_bridge.go, internal/mcpgw/*

Runtime Architecture​

Cruvero's MCP stack has three runtime layers:

  1. Server configuration and client transport (internal/mcp/*)
  2. Tool bridge and registry integration (internal/tools/mcp_bridge.go)
  3. Gateway interop layer (NATS) (internal/mcpgw/*)

MCP tools are registered with mcp.<server>.<tool> names and are callable through the same tool manager path as built-in tools.

Discovery Modes​

CRUVERO_MCP_DISCOVERY controls how server availability is discovered:

  • static (default): use configured servers only.
  • nats: use event-bus discovery only.
  • both: combine static and event-bus discovery.

Gateway integration startup is independent of discovery mode. If CRUVERO_MCPGW_ENABLED=true and an event bus is available, gateway subscriber/publisher startup is attempted before the static/nats/both discovery branch is evaluated.

MCP Operational CLIs​

cmd/mcp-announce​

Publishes MCP server discovery lifecycle events (announce, periodic heartbeat, deregister) to NATS.

Flags:

  • --server MCP server name (required)
  • --nats-url NATS URL
  • --transport stdio|http|sse
  • --endpoint required for http|sse
  • --heartbeat heartbeat interval
  • --prefix subject prefix (default cruvero)

Examples:

  • go run ./cmd/mcp-announce --server weather --transport http --endpoint http://localhost:8089/mcp
  • go run ./cmd/mcp-announce --server local --transport stdio -- bash ./scripts/mcp-server.sh

cmd/mcp-code-exec​

Runs an MCP server exposing code execution tools (python_exec, bash_exec) via streamable HTTP. Configured by:

  • MCP_CODE_EXEC_PORT (default 8080)
  • MCP_CODE_EXEC_TIMEOUT (default 30s)
  • MCP_CODE_EXEC_MAX_OUTPUT (default 1048576)

Example:

  • MCP_CODE_EXEC_PORT=8088 go run ./cmd/mcp-code-exec

When CRUVERO_CODE_EXEC_MCP_REQUIRED=true, runtime tool execution fails closed if this MCP route is unavailable in http|gateway transport modes.

Event Bus Discovery Contract​

Cruvero MCP discovery messages are published on the following subjects (before optional custom prefix rewrite):

  • cruvero.mcp.announce
  • cruvero.mcp.heartbeat
  • cruvero.mcp.deregister
  • cruvero.mcp.gateway.health
  • cruvero.mcp.registry.sync

cmd/mcp-announce applies --prefix to the built-in subject names. If --prefix is acme, publish subjects become acme.mcp.announce, acme.mcp.heartbeat, and so on.

Discovery Event Types​

MCP announce payload envelopes use these event type values:

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

MCP Gateway Integration​

Cruvero integrates with cruvero-mcp-gateway via gateway-scoped NATS subjects.

Subject Contract​

  • Events published by gateway and consumed by Cruvero:
    • mcpgw.{gateway_id}.events.{event_type}
  • Config published by Cruvero and consumed by gateway:
    • mcpgw.{gateway_id}.config.{scope}
  • Reconnect snapshot request consumed by Cruvero publisher:
    • mcpgw.{gateway_id}.config.request

Cruvero resolves {gateway_id} from CRUVERO_MCPGW_GATEWAY_ID (default default).

Event Types​

Cruvero handles the following dotted event types:

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

Events are decoded from a shared envelope:

  • event_type
  • timestamp
  • gateway_id
  • payload

Config Scopes Published by Cruvero​

PublishAll() publishes all four scopes:

  • policy (mcpgw.{gateway_id}.config.policy)
  • servers (mcpgw.{gateway_id}.config.servers)
  • server_settings (mcpgw.{gateway_id}.config.server_settings)
  • auth (mcpgw.{gateway_id}.config.auth)

Cruvero publishes server metadata and settings using CRUVERO_MCPGW_TENANT_ID for store reads. Tenant defaults to default only when the env var is unset/blank.

Auth Configuration​

Gateway auth publication is driven by MCPGW env vars:

  • CRUVERO_MCPGW_AUTH_MODE defaults to jwt
  • Supported modes: jwt, oidc, apikey, none
  • none is rejected unless CRUVERO_MCPGW_AUTH_ALLOW_NONE=true

For oidc, issuer/audience/JWKS fields are sourced from:

  • CRUVERO_MCPGW_OIDC_ISSUER
  • CRUVERO_MCPGW_OIDC_AUDIENCE
  • CRUVERO_MCPGW_OIDC_JWKS_URL

Reconnect and Resync Behavior​

When a gateway reconnects, it can publish mcpgw.{gateway_id}.config.request. Cruvero's publisher debounces reconnect requests and republishes the full config set (all four scopes). If enabled, automatic registry refresh is controlled by:

  • CRUVERO_MCPGW_AUTO_REGISTRY_REFRESH_ENABLED
  • CRUVERO_MCPGW_AUTO_REGISTRY_REFRESH_DEBOUNCE
  • CRUVERO_MCPGW_AUTO_REGISTRY_REFRESH_INTERVAL (default 15m, set 0 to disable periodic refresh)
  • CRUVERO_MCPGW_AUTO_REGISTRY_REFRESH_REGISTRY_ID

UI and API Surface​

Cruvero exposes gateway operations in the React UI and runtime API:

  • UI route: /mcp/gateways (Gateway Fleet)
  • API endpoints:
    • GET /api/mcpgw/gateways
    • GET /api/mcpgw/gateways/{id}
    • POST /api/mcpgw/gateways/{id}/sync
    • GET /api/mcpgw/gateways/{id}/events
    • POST /api/mcpgw/sync
    • GET /api/mcpgw/events (SSE)
    • GET /api/mcpgw/registry-sync
    • POST /api/mcpgw/registry-refresh

Endpoint Security​

CRUVERO_MCP_STRICT_ENDPOINTS=true (default) enforces MCP endpoint allowlists:

  1. URL-like values are extracted from tool call arguments.
  2. Values are checked against server-specific allowlists.
  3. Calls are rejected if any URL is outside allowed targets.

Server allowlists are configured with CRUVERO_MCP_ENDPOINTS_<SERVER>.

Core MCP Environment Variables​

  • CRUVERO_MCP_SERVERS
  • CRUVERO_MCP_ENV_<NAME>
  • CRUVERO_MCP_ENDPOINTS_<NAME>
  • CRUVERO_MCP_STRICT_ENDPOINTS
  • CRUVERO_MCP_DISCOVERY
  • CRUVERO_MCP_HEARTBEAT_INTERVAL
  • CRUVERO_MCP_STALE_THRESHOLD

Gateway-specific environment variables are documented in Configuration and Environment.