MCP Proxy

MCP proxy that gates risky tool calls through NullSpend approval before forwarding to an upstream MCP server. Adds cost tracking and budget enforcement for every tool invocation.

Architecture

LLM Client ──► NullSpend MCP Proxy ──► Upstream MCP Server
                    │                         │
                    │  ◄── tool result ───────┘
                    │
                    ├──► NullSpend API (approval, cost events, budget checks)
                    │
                    ▼
              NullSpend Dashboard

The proxy sits between the LLM client and the upstream MCP server. It discovers upstream tools at startup, optionally gates tool calls through human approval, tracks cost per invocation, and enforces budgets.

Installation

Build from source (private package):

cd packages/mcp-proxy
npm install
npm run build

Configuration

Gating

Tool gating controls which upstream tools require human approval before execution.

How It Works

1. If a tool is in PASSTHROUGH_TOOLS, it is never gated (passthrough always wins)
2. If GATED_TOOLS is "*", all non-passthrough tools require approval
3. If GATED_TOOLS is a comma-separated list, only those tools require approval
4. If GATED_TOOLS is "" (empty), no tools require approval

Examples

Approval Flow

When a gated tool is called:

1. The proxy creates an action via POST /api/actions with the tool name, arguments, and a summary
2. It polls for a human decision (approved/rejected/expired)
3. On approval: forwards the call to the upstream server, then reports the result
4. On rejection: returns an error to the LLM client: Action "<tool>" was rejected by a human reviewer.
5. On timeout: returns an error: Approval for "<tool>" timed out after N seconds.

Cost Tracking

The proxy tracks cost for every tool invocation (gated or not) when NULLSPEND_COST_TRACKING is "true" (default).

Cost Estimation

Cost per tool call is estimated using a three-tier priority system:

Annotation Tiers (Suggested Costs)

Tools are unpriced ($0.00) by default until you configure a cost. The dashboard shows suggested costs based on MCP annotations to help you set appropriate prices:

These are suggestions only — they are not auto-applied. Accept or override them in the dashboard's Tool Costs page.

To set costs for specific tools via environment variable:

NULLSPEND_TOOL_COSTS='{"write_file": 50000, "run_query": 200000}'

Values are in microdollars (1,000,000 = $1.00).

Budget Enforcement

When NULLSPEND_BUDGET_ENFORCEMENT is "true" (default), the proxy checks the budget before each tool call:

1. Estimates the cost using the priority system above
2. Calls POST /v1/mcp/budget/check with the tool name, server name, and estimate
3. If the budget is exceeded, returns an error: Tool "<name>" blocked: budget exceeded.
4. If the check fails (network error, timeout), falls back to fail-open after 5 consecutive failures (circuit breaker with 30s cooldown)

Event Reporting

Cost events are batched and sent to POST /v1/mcp/events:

• Batch size: 20 events
• Flush interval: 5 seconds
• Max queue: 4,096 events (oldest dropped on overflow)
• Failed batches are re-queued once for retry

Tool Discovery

At startup, the proxy registers all upstream tools with the dashboard via POST /api/tool-costs/discover. This populates the tool catalog for per-tool cost configuration in the UI.

Claude Desktop Setup

Example claude_desktop_config.json with gating and passthrough:

{
  "mcpServers": {
    "gated-filesystem": {
      "command": "node",
      "args": ["path/to/packages/mcp-proxy/dist/index.js"],
      "env": {
        "NULLSPEND_URL": "https://nullspend.dev",
        "NULLSPEND_API_KEY": "ns_live_sk_your-key-here",
        "UPSTREAM_COMMAND": "npx",
        "UPSTREAM_ARGS": "[\"@modelcontextprotocol/server-filesystem\", \"/home/user/projects\"]",
        "GATED_TOOLS": "write_file,delete_file",
        "PASSTHROUGH_TOOLS": "read_file,list_dir",
        "NULLSPEND_SERVER_NAME": "filesystem"
      }
    }
  }
}

Gate-Everything Example

{
  "mcpServers": {
    "gated-everything": {
      "command": "node",
      "args": ["path/to/packages/mcp-proxy/dist/index.js"],
      "env": {
        "NULLSPEND_URL": "https://nullspend.dev",
        "NULLSPEND_API_KEY": "ns_live_sk_your-key-here",
        "UPSTREAM_COMMAND": "npx",
        "UPSTREAM_ARGS": "[\"some-mcp-server\"]",
        "NULLSPEND_TOOL_COSTS": "{\"expensive_tool\": 500000}"
      }
    }
  }
}

Error Messages

Graceful Shutdown

The proxy handles SIGINT, SIGTERM, and stdin close. On shutdown:

1. Aborts any in-flight approval polls
2. Flushes remaining cost events (no re-queue during shutdown)
3. Waits for in-flight HTTP requests to complete
4. Closes the upstream MCP client connection

Related

• MCP Server — standalone MCP server for approval tools (no upstream proxy)
• Human-in-the-Loop — approval workflow concepts
• Budgets — budget enforcement and spending limits
• Cost Tracking — how cost events are recorded
• JavaScript SDK — programmatic API client