> ## Documentation Index
> Fetch the complete documentation index at: https://apie.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP proxy

> Instrument MCP tool calls with zero code changes — point your MCP host at the Ratri proxy.

Your agent uses MCP tools through Cursor or Claude Desktop. You want every tool call observed and optionally guarded — without rewriting your agent or adding SDK calls. The Ratri MCP proxy sits between your MCP host and the upstream server.

When you finish this page, your MCP host will route tool calls through Ratri for telemetry and guardrail evaluation.

## How it works

```mermaid theme={null}
sequenceDiagram
  participant Host as MCP Host
  participant Proxy as Ratri Proxy
  participant Upstream as Upstream MCP Server
  participant API as Ratri API

  Host->>Proxy: tools/call
  Proxy->>API: Evaluate guardrail
  API-->>Proxy: allow / block / require_approval
  Proxy->>Upstream: Forward call (if allowed)
  Upstream-->>Proxy: Result
  Proxy->>API: Emit telemetry events
  Proxy-->>Host: Result or error
```

## Install

<CodeGroup>
  ```bash TypeScript theme={null}
  npm install -g @ratri/cli
  # or use npx
  ```

  ```bash Python theme={null}
  pip install "ratri-sdk[mcp-proxy]"
  ```
</CodeGroup>

## Configure ratri.mcp.json

Create a config file in your project root:

```json ratri.mcp.json theme={null}
{
  "agentKey": "incident-remediation-agent",
  "serverName": "filesystem",
  "mode": "monitor",
  "environment": "development",
  "upstream": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  },
  "redactKeys": ["token", "password", "secret"]
}
```

| Field               | Description                                       |
| ------------------- | ------------------------------------------------- |
| `agentKey`          | Agent key registered with Ratri                   |
| `serverName`        | Namespace for tool names (`filesystem.read_file`) |
| `mode`              | `monitor` or `enforce`                            |
| `environment`       | Environment tag on events                         |
| `upstream`          | Command and args to start the upstream MCP server |
| `redactKeys`        | Keys to strip from event payloads                 |
| `approvalTimeoutMs` | Approval wait timeout in Enforce mode             |

### Multi-server config

Route multiple upstream servers through one proxy:

```json theme={null}
{
  "agentKey": "my-agent",
  "mode": "monitor",
  "servers": {
    "filesystem": {
      "upstream": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
    },
    "github": {
      "upstream": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
    }
  }
}
```

Select a server at runtime: `--server filesystem`

## Point your MCP host at the proxy

Replace the upstream command in your MCP host config with the Ratri proxy:

<CodeGroup>
  ```json Cursor / Claude Desktop theme={null}
  {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["@ratri/cli", "mcp", "proxy", "--config", "/path/to/ratri.mcp.json"]
      }
    }
  }
  ```

  ```bash Shell script theme={null}
  #!/bin/bash
  ratri mcp proxy --config ratri.mcp.json
  ```
</CodeGroup>

## Run the proxy

<CodeGroup>
  ```bash TypeScript theme={null}
  npx ratri mcp proxy --config ratri.mcp.json
  # SSE transport for HTTP clients:
  npx ratri mcp proxy --config ratri.mcp.json --transport sse --port 3100
  # Enforce mode override:
  npx ratri mcp proxy --config ratri.mcp.json --mode enforce
  ```

  ```bash Python theme={null}
  ratri mcp proxy --config ratri.mcp.json
  ratri mcp proxy --config ratri.mcp.json --transport sse --port 3100
  ratri mcp proxy --config ratri.mcp.json --mode enforce
  ```
</CodeGroup>

## Validate

<CodeGroup>
  ```bash TypeScript theme={null}
  npx ratri doctor --mcp --mcp-config ratri.mcp.json
  ```

  ```bash Python theme={null}
  ratri doctor --mcp --mcp-config ratri.mcp.json
  ```
</CodeGroup>

### What you'll see

MCP tool calls in the dashboard with inferred action and resource metadata. In Enforce mode, blocked calls return error `-32001` and approval-denied calls return `-32002`.

## Auto tool registration

When the proxy receives `tools/list` from upstream, it automatically defines each tool with Ratri. This populates your boundary map without manual declaration.

## Next steps

<CardGroup cols={2}>
  <Card title="MCP enforcement recipe" icon="shield" href="/recipes/mcp-enforcement">
    Enforce mode + approval routing.
  </Card>

  <Card title="Instrumented MCP client" icon="code" href="/mcp/instrumented-client">
    In-process MCP for custom agents.
  </Card>
</CardGroup>