@clampd/mcp-proxy

Standalone MCP proxy that wraps any MCP server with Clampd's 9-stage security pipeline. Connect Claude Desktop, Cursor, or any MCP client to this proxy instead of directly to an MCP server. Every tool call is classified through ag-gateway — dangerous calls are blocked before they reach the tool.

Quick Start

One connection string. The proxy self-enrolls an Ed25519 identity on first run (the gateway assigns the agent UUID) — no shared secret, no agent ID to provision.

# Install
cd sdk/typescript/mcp-proxy && npm install

# One config value (carries gateway host + org key)
export CLAMPD_DSN=clampd://[email protected]

# Run (wraps the filesystem MCP server)
npx tsx src/index.ts \
  --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp"

# Open the dashboard
open http://localhost:3003

Claude Desktop Configuration

Add to your Claude Desktop mcpServers config:

{
  "mcpServers": {
    "filesystem": {
      "url": "http://localhost:3003/sse"
    }
  }
}

Environment Variables

| Variable | Description | Default | |---|---|---| | CLAMPD_DSN | clampd://<org_key>@<host> — the single config value | (required) | | CLAMPD_AGENT_NAME | Logical agent name (gateway assigns the UUID) | mcp-proxy | | CLAMPD_ENROLL_TOKEN | Enrollment token (cet_…) for scaled fleets / CI | (none) | | CLAMPD_REBIND_TOKEN | Re-key token (crt_…) to recover a lost-key agent | (none) | | CLAMPD_SCAN_INPUT / CLAMPD_SCAN_OUTPUT / CLAMPD_CHECK_RESPONSE | Enable scanning layers (true/false) | false |

No shared secret: the proxy generates an Ed25519 keypair, enrolls the public key with the gateway, and signs requests locally with the private key (EdDSA).

CLI Options

--upstream, -u      Command to spawn the upstream MCP server (required)
--dsn, -d           clampd://<org_key>@<host>  (or set CLAMPD_DSN)
--gateway, -g       Clampd gateway URL (override; default from DSN)
--api-key, -k       Org API key (override; default from DSN)
--agent-name, -a    Logical agent name (default: mcp-proxy; UUID assigned at enrollment)
--port, -p          Port to listen on (default: 3003)
--dry-run           Classify but never forward to upstream
--scan-input        Scan tool arguments for prompt injection / PII / secrets
--scan-output       Scan tool responses for PII / secrets leakage
--check-response    Validate responses against the granted scope token
--fleet-config      Path to fleet config JSON (multi-agent mode)
--verbose, -v       Enable debug logging

Architecture

Claude Desktop / Cursor / Any MCP Client
    |
    | MCP protocol (SSE transport)
    v
Clampd MCP Proxy (:3003)
    |
    +---> GET /sse      -- MCP SSE endpoint (client connects here)
    +---> GET /          -- Live dashboard (blocked/allowed in real-time)
    +---> GET /health    -- Health check JSON
    +---> GET /events    -- Dashboard SSE stream (live updates)
    |
    | For each tool call:
    |   1. Extract tool_name + params from MCP call_tool request
    |   2. POST to ag-gateway /v1/proxy { tool, params, target_url }
    |   3. If gateway says BLOCK -> return MCP error to client
    |   4. If gateway says ALLOW -> forward to upstream MCP server
    |
    v
Upstream MCP Server (filesystem, database, github, shell, etc.)
    (spawned as child process, communicates via stdio)

Deployment

Docker

docker build -t clampd-mcp-proxy .
docker run -p 3003:3003 \
  -e CLAMPD_DSN="clampd://[email protected]" \
  clampd-mcp-proxy \
  --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp"

The image sets CLAMPD_HOME=/var/lib/clampd for the self-enrolled identity. To keep the same agent UUID across container restarts, mount a volume there: -v clampd-identity:/var/lib/clampd.

npm global install

npm install -g @clampd/mcp-proxy
export CLAMPD_DSN=clampd://[email protected]
clampd-mcp-proxy --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp"

npx (no install)

CLAMPD_DSN=clampd://[email protected] \
  npx @clampd/mcp-proxy --upstream "npx -y @modelcontextprotocol/server-filesystem /tmp"