> ## 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 Apie 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 Apie MCP proxy sits between your MCP host and the upstream server.

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

## How it works

```mermaid theme={null}
sequenceDiagram
  participant Host as MCP Host
  participant Proxy as Apie Proxy
  participant Upstream as Upstream MCP Server
  participant API as Apie 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 @apie/cli
  # or use npx
  ```

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

## Configure apie.mcp.json

Create a config file in your project root:

```json apie.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 Apie                    |
| `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 Apie proxy:

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

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

## Run the proxy

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

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

## Validate

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

  ```bash Python theme={null}
  apie doctor --mcp --mcp-config apie.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 Apie. 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>