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

Install

TypeScript

npm install -g @apie/cli
# or use npx

Configure apie.mcp.json

Create a config file in your project root:

apie.mcp.json

{
  "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:

{
  "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:

Cursor / Claude Desktop

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@apie/cli", "mcp", "proxy", "--config", "/path/to/apie.mcp.json"]
    }
  }
}

Run the proxy

TypeScript

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

Validate

TypeScript

npx apie doctor --mcp --mcp-config apie.mcp.json

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

MCP enforcement recipe

Enforce mode + approval routing.

Instrumented MCP client

In-process MCP for custom agents.