Skip to main content

MCP (Model Context Protocol)

Register the MCP servers your agents already use, govern every tool call passing through them, and authenticate agents with detection keys instead of bearer tokens you can't rotate.

Where to find it in the app​

Dashboard → Administration → AI Estate → DISCOVERY → Tool Integrations.

The Tool Integrations sub-tab is the customer-facing MCP gateway and tool registry. From this page:

  • Add gateway — registers a new MCP server (HTTP or stdio) and issues a detection key
  • Probe tools — runs an MCP tools/list call against a candidate server before you register it
  • Tools list — for each registered gateway, register specific tools to apply narrower detection coverage per tool
  • Rotate key — issue a new detection key (immediately revokes the old one)
  • Toggle — enable or disable a gateway without deleting it

The same Tool Integrations panel also surfaces ungoverned MCP servers discovered in your environment (see Discovery & Shadow AI) — you can promote a discovered MCP server into a governed gateway in one click.

The MCP invoke path (POST /api/v1/mcp/invoke) is what agent clients call at runtime. That's a developer concern — covered in the For developers section near the bottom.

How Rivaro fits into MCP​

Rivaro sits between your AI agents and your MCP servers as a governed proxy. Agents talk to Rivaro using their normal MCP transport (HTTP or stdio); Rivaro applies detection, policy enforcement, and audit logging on every tools/call, then forwards the request to the real MCP server.

You don't change your MCP server. You don't change the MCP protocol. You change one URL in your agent's MCP client configuration and add a detection key — that's it.

┌─────────┐     X-Detection-Key      ┌────────┐                 ┌─────────────┐
│  Agent  │ ─────────────────────────▶│ Rivaro │ ───────────────▶│ MCP server  │
└─────────┘  POST /api/v1/mcp/invoke/ └────────┘   upstreamEndpoint └─────────────┘
                     {tool}            │
                                       ▼
                              Detection + policy
                              Audit + session log

The configuration model​

Rivaro's MCP governance is built on three pieces of configuration, all set up from Tool Integrations.

1. Gateway​

A gateway is the registered identity of one MCP server you want Rivaro to govern. Fields on the gateway form:

FieldDescription
NameDisplay name for this gateway
TransportHTTP (default) or stdio
Upstream endpointThe real URL of your MCP server (for HTTP transport)
Stdio command / args / envFor stdio-launched MCP servers
Adapter typeMCP (default) or MCP-Stripe for Stripe's MCP adapter — see Stripe MCP
Enabled detectorsRisk categories Rivaro runs on every request through this gateway
Detection keyGenerated on creation, shown once in a modal — copy it before closing

2. Tools​

A tool is the registered identity of one capability exposed by a gateway. Tools you don't register aren't blocked — they fall through to the gateway's default detector set. But registering them lets you tune detection per tool (e.g. require credentials detection on query_database, allow web_search with only PII detection).

Tools are added from the gateway's detail page in Tool Integrations. Fields:

FieldDescription
Tool nameThe MCP tool name (must match what the server exposes, e.g. get_weather, query_database)
Bound gatewayThe gateway this tool belongs to (defaulted from context)
Enabled detectorsDetectors specific to this tool — usually narrower than the gateway's set

3. Detection key​

One detection key is issued per gateway when you create it. The plaintext is shown once in a "key created" modal. Rivaro stores only the hash. Agents present the key on every request via the X-Detection-Key header (or as a bearer token, depending on transport).

Rotating a key (via the Rotate key action on a gateway) immediately revokes access for any agent still using the old one.

End-to-end setup​

Step 1 — Probe a candidate MCP server​

In Tool Integrations, click Add gateway and use the Probe button on the form. Enter the candidate MCP server URL and (optional) shared secret. Rivaro calls tools/list and returns the schemas — useful to inspect what tools the server exposes before you commit to registering anything. The probe is read-only; nothing is persisted yet.

Step 2 — Register the gateway​

Fill in the gateway form fields: name, transport, upstream endpoint (HTTP) or stdio command/args/env, adapter type (usually MCP), enabled detectors. Save.

A modal appears with the detection key in plaintext. Copy it now — this is the only time it's visible. You'll need it in Step 4 to wire up the agent.

Step 3 — Register tools (optional but recommended)​

From the gateway's detail page, click Add tool for each tool you want to govern with specific detection coverage. Tool name must match what the server exposes. Tools without a specific registration inherit the gateway's detector set.

Step 4 — Point your agent at Rivaro​

This step is in your agent's code, not the Rivaro UI. Replace your agent's existing MCP server URL with Rivaro's invoke path, and add the detection key:

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

RIVARO_BASE = "https://api.rivaro.ai/api/v1/mcp/invoke"

async with streamablehttp_client(
    f"{RIVARO_BASE}/Production%20MCP%20Gateway",
    headers={"X-Detection-Key": "detect_live_..."}
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool("query_database", {"sql": "SELECT 1"})

The path segment after /invoke/ can be the gateway name, a tool name, or the gateway's configuration ID — Rivaro resolves the right context using the detection key plus the path.

For stdio-launched gateways, agents launch them via Rivaro's local SDK or sidecar; the detection key is supplied via env var (RIVARO_DETECTION_KEY).

How requests are governed​

For every call into /api/v1/mcp/invoke/...:

  1. Authenticate — Rivaro looks up the gateway by detection key.
  2. Resolve tool — the path segment after invoke/ is matched against registered tools belonging to this gateway. If a match is found, that tool's detector set applies; otherwise the gateway's defaults apply.
  3. Detect — request body and headers are scanned against the resolved detector set. Detections become AGENT_TOOL_* events on the session timeline.
  4. Enforce — applicable policy rules decide ALLOW / BLOCK / RISK_ADAPTIVE / etc. See Enforcement & Policies.
  5. Forward — on ALLOW, Rivaro proxies the body unchanged to the upstream endpoint (or to the spawned stdio process), preserving MCP session headers (mcp-session-id).
  6. Detect on response — the upstream response is scanned and policy applied again before being returned to the agent.
  7. Audit — invocation, detections, decision, and final action are written to the session and governance history.

What gets detected on every tool call​

Every MCP invocation contributes to:

  • Detection events — AGENT_TOOL_* types appear in session history and the detections page.
  • Risk scoring — tool calls that touch sensitive data update the actor's risk score.
  • Cost tracking — outbound calls and their argument sizes are accounted in Budget.
  • Output checks — return values from tools can be validated against output check schemas.

Discovery: finding ungoverned MCP​

Rivaro's discovery channels also look for MCP servers running outside this registration flow. Any MCP server found via network scan, infrastructure scan, or process listing that isn't registered as a gateway shows up in Discovery with one of these detection types:

Detection typeWhat it catches
INFRASTRUCTURE_MCP_PUBLIC_ENDPOINTMCP server exposed to the internet without authentication
INFRASTRUCTURE_MCP_DANGEROUS_TOOLSMCP server exposing shell execution, database writes, or other high-risk capabilities
INFRASTRUCTURE_SHADOW_AI_AGENTMCP-connected agent running outside approved infrastructure

Promote a discovered MCP server straight into a governed gateway from the Discovered Assets list.

Stripe MCP (and other branded adapters)​

Stripe's MCP server uses a slightly different invocation shape than vanilla MCP. When registering it, set Adapter type to MCP-Stripe instead of MCP. Everything else — detection, policy, audit — works identically. See Stripe MCP Integration for the provider-specific setup.

Common patterns​

Locking a gateway to a single agent​

Create the gateway, then bind its AppContext to one agent identity from the Agent Registry (open the agent → Overview → set AppContext). Now only that agent's detection key has runtime access to this gateway.

Per-environment isolation​

Register one gateway per environment (Stripe Payments — staging, Stripe Payments — production) pointing at the corresponding upstream. Distribute the matching detection key only to agents in that environment.

Detection key rotation​

Open the gateway in Tool Integrations and click Rotate key. The new plaintext key is shown in a modal. Old key stops working immediately — make sure your agents are configured to pull from a secret store you can update atomically.

For developers — the invoke path​

If you're integrating an agent with Rivaro's MCP proxy, this is the path your MCP client points at:

POST /api/v1/mcp/invoke/{gateway-name-or-id-or-tool}
Header: X-Detection-Key: detect_live_...
Body:   {... MCP JSON-RPC payload ...}

For pre-flight validation (run detection and policy evaluation without invoking the upstream tool):

POST /api/v1/mcp/inspect/{toolName}
Header: X-Detection-Key: detect_live_...
Body:   {... MCP JSON-RPC payload ...}

These paths are stable external contracts and are versioned under /api/v1/. For full client integration guidance see the agent framework docs and the provider-specific docs in Providers.

Next steps​