MCPulse Proxy

MCPulse Proxy is a zero-code analytics solution for MCP servers. It acts as transparent middleware between MCP clients and servers, automatically collecting comprehensive metrics without requiring any code changes.

Why Use the Proxy?

✅ No Code Changes - Add analytics to any existing MCP server ✅ Language Agnostic - Works with Python, TypeScript, Go, Rust, any language ✅ Perfect for Claude Desktop - Drop-in replacement in your config ✅ Full MCP Support - All capabilities: tools, resources, prompts, sampling ✅ High Performance - Minimal overhead with async collection

Installation

Using Go Install (Recommended)

go install github.com/sirrobot01/mcpulse-proxy@latest

From Source

git clone https://github.com/sirrobot01/mcpulse-proxy.git
cd mcpulse-proxy
go build -o mcpulse-proxy .

Quick Start

Commands

mcpulse-proxy stdio [OPTIONS]   # Local stdio server
mcpulse-proxy sse [OPTIONS]     # Remote SSE server (legacy)
mcpulse-proxy http [OPTIONS]    # Remote HTTP server

Basic Examples

Local stdio server:

mcpulse-proxy stdio --server-id my-server --command "python server.py"

Remote HTTP server:

mcpulse-proxy http --server-id my-server \
  --remote-url https://api.example.com/mcp \
  --bearer-token your_token

Expose as HTTP (with auth mirroring):

mcpulse-proxy stdio --server-id my-server \
  --command "python server.py" \
  --bearer-token secret123 \
  --listen :8080

Claude Desktop Integration

The most common use case is adding MCPulse to your Claude Desktop MCP servers:

Before (without analytics):

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

After (with MCPulse analytics):

{
  "mcpServers": {
    "my-server": {
      "command": "mcpulse-proxy",
      "args": [
        "stdio",
        "--server-id", "my-server",
        "--command", "python server.py"
      ],
      "env": {
        "MCPULSE_URL": "localhost:50051",
        "MCPULSE_API_KEY": "your-api-key"
      }
    }
  }
}

That's it! Your MCP server now sends analytics to MCPulse.

Transport Modes

1. stdio Mode (Most Common)

For local MCP servers that communicate via stdin/stdout:

mcpulse-proxy stdio \
  --server-id my-server \
  --command "python server.py"

Use Cases:

• Claude Desktop servers
• Local development
• Any stdio-based MCP server

2. HTTP Mode (Recommended for Remote)

For servers using HTTP streaming (the new MCP standard):

mcpulse-proxy http \
  --server-id my-server \
  --remote-url https://api.example.com/mcp \
  --bearer-token your_token

Use Cases:

• Remote MCP servers
• HTTP-based MCP implementations
• Cloud-hosted servers

3. SSE Mode (Legacy)

For servers using Server-Sent Events (deprecated in MCP spec):

mcpulse-proxy sse \
  --server-id my-server \
  --remote-url https://api.example.com/sse \
  --bearer-token your_token

Configuration

Command-Line Flags

Server Configuration:

• --server-id - Unique server identifier (required)
• --mcpulse-url - MCPulse gRPC endpoint (default: localhost:50051)
• --mcpulse-api-key - MCPulse API key

Upstream Connection:

• --command - Command to execute upstream server (stdio mode)
• --remote-url - Remote server URL (sse/http mode)
• --bearer-token - Bearer token for upstream auth
• --auth-token - Alias for bearer-token
• --headers - Custom headers (format: "Key:Value,Key2:Value2")

Output Mode:

• --listen - Listen address for HTTP output (e.g., :8080)

Config File:

• --config - Path to mcp.json file
• --server - Server name from config file

Environment Variables

MCPulse Configuration (use directly):

export MCPULSE_URL=localhost:50051        # or MCPULSE_SERVER
export MCPULSE_API_KEY=your-api-key

Proxy Configuration (use MCPULSE_PROXY_ prefix):

export MCPULSE_PROXY_SERVER_ID=my-server
export MCPULSE_PROXY_COMMAND="python server.py"
export MCPULSE_PROXY_REMOTE_URL=https://api.example.com/mcp
export MCPULSE_PROXY_BEARER_TOKEN=your-token
export MCPULSE_PROXY_HEADERS="X-API-Key:abc123"
export MCPULSE_PROXY_LISTEN=:8080

Running with environment variables:

# Set environment variables
export MCPULSE_URL=localhost:50051
export MCPULSE_API_KEY=your-api-key
export MCPULSE_PROXY_SERVER_ID=my-server

# Run proxy
mcpulse-proxy stdio --command "python server.py"

Using Config Files

MCPulse Proxy can read from mcp.json config files:

mcp.json:

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["server.py"],
      "env": {
        "API_KEY": "server-key"
      }
    }
  }
}

Run with config:

mcpulse-proxy stdio --config mcp.json --server my-server

Examples

Example 1: Python Weather Server

{
  "mcpServers": {
    "weather": {
      "command": "mcpulse-proxy",
      "args": [
        "stdio",
        "--server-id", "weather-server",
        "--command", "uv run weather_server.py"
      ],
      "env": {
        "MCPULSE_URL": "localhost:50051",
        "MCPULSE_API_KEY": "your-mcpulse-key",
        "OPENWEATHER_API_KEY": "your-weather-key"
      }
    }
  }
}

Example 2: TypeScript Database Server

{
  "mcpServers": {
    "database": {
      "command": "mcpulse-proxy",
      "args": [
        "stdio",
        "--server-id", "database-server",
        "--command", "npx tsx database_server.ts"
      ],
      "env": {
        "MCPULSE_URL": "localhost:50051",
        "MCPULSE_API_KEY": "your-mcpulse-key",
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}

Example 3: Remote HTTP Server

# Start proxy pointing to remote server
mcpulse-proxy http \
  --server-id production-api \
  --mcpulse-url analytics.example.com:443 \
  --remote-url https://api.example.com/mcp \
  --bearer-token sk_prod_token

# Your MCP client connects and proxy forwards with metrics

Example 4: Multiple Servers

{
  "mcpServers": {
    "prod-api": {
      "command": "mcpulse-proxy",
      "args": [
        "stdio",
        "--server-id", "prod-api",
        "--command", "python prod_server.py"
      ],
      "env": {
        "MCPULSE_URL": "localhost:50051",
        "MCPULSE_API_KEY": "prod-key",
        "ENVIRONMENT": "production"
      }
    },
    "staging-api": {
      "command": "mcpulse-proxy",
      "args": [
        "stdio",
        "--server-id", "staging-api",
        "--command", "python staging_server.py"
      ],
      "env": {
        "MCPULSE_URL": "localhost:50051",
        "MCPULSE_API_KEY": "staging-key",
        "ENVIRONMENT": "staging"
      }
    }
  }
}

Example 5: Expose stdio as HTTP

# Run stdio server but expose it as HTTP endpoint
mcpulse-proxy stdio \
  --server-id my-server \
  --command "python server.py" \
  --bearer-token secret123 \
  --listen :8080

# Now accessible via HTTP with auth:
# curl -H "Authorization: Bearer secret123" http://localhost:8080/mcp

Auth Mirroring

When --listen is set with --bearer-token, the proxy HTTP endpoint requires the same token. This mirrors upstream auth to the output:

# Upstream and output both use same token
mcpulse-proxy http \
  --server-id my-server \
  --remote-url https://api.example.com/mcp \
  --bearer-token secret123 \
  --listen :8080

Clients connecting to localhost:8080 must provide:

Authorization: Bearer secret123

Advanced Usage

Custom Headers

Add custom headers to upstream requests:

mcpulse-proxy http \
  --server-id my-server \
  --remote-url https://api.example.com/mcp \
  --headers "X-API-Key:abc123,X-Client-ID:myapp"

Or via environment:

export MCPULSE_PROXY_HEADERS="X-API-Key:abc123,X-Client-ID:myapp"
mcpulse-proxy http --server-id my-server --remote-url https://api.example.com/mcp

Combining Config File and Flags

# Use config file for server command, override with flags
mcpulse-proxy stdio \
  --config mcp.json \
  --server my-server \
  --mcpulse-url production.example.com:443

Troubleshooting

Proxy Not Starting

Check logs:

mcpulse-proxy stdio --server-id my-server --command "python server.py" 2>&1 | tee proxy.log

Common issues:

• Missing --server-id flag
• Incorrect --command path
• MCPulse server not running

Metrics Not Appearing

1. Verify MCPulse is running:

   curl http://localhost:8080/health

2. Check API key:

   # Verify your API key is valid in MCPulse dashboard

3. Check connectivity:

   # Test gRPC endpoint
   grpcurl -plaintext localhost:50051 list

Upstream Server Not Working

Test without proxy first:

# Remove proxy temporarily
python server.py  # Test directly

# If working, add proxy back
mcpulse-proxy stdio --server-id test --command "python server.py"

Environment Variables Not Working

Check precedence:

1. Command-line flags override environment variables
2. MCPULSE_PROXY_* variables are for proxy config
3. MCPULSE_* variables (without PROXY) are passed through

Performance

MCPulse Proxy is designed for minimal overhead:

• Async metric collection - Non-blocking operation
• Buffered ingestion - Batches metrics for efficiency
• Zero serialization overhead - Passthrough protocol handling
• ~1-2ms added latency - Negligible impact on tool calls

Benchmarks

Tool call without proxy: 45ms
Tool call with proxy:    47ms (+2ms overhead)

Throughput: 10,000+ tool calls/min
Memory usage: <50MB

Comparison with SDKs

Feature	Proxy	Python SDK	Go SDK
Code Changes	❌ None	✅ Required	✅ Required
Language Support	✅ Any	Python only	Go only
Setup Time	⚡ 1 minute	5-10 minutes	5-10 minutes
Customization	Limited	Full control	Full control
Performance	Excellent	Excellent	Excellent

When to use Proxy:

• You don't control the server code
• Quick setup needed
• Using TypeScript/Rust/other languages
• Multiple servers to monitor
• Claude Desktop integration

When to use SDK:

• You control the code
• Need custom metrics
• Want fine-grained control
• Building new server from scratch

Next Steps

1. Get an API Key from MCPulse dashboard
2. Add proxy to your Claude Desktop config
3. Restart Claude Desktop
4. View metrics at http://localhost:8080

Resources

• GitHub: https://github.com/sirrobot01/mcpulse-proxy
• Issues: https://github.com/sirrobot01/mcpulse/issues
• Documentation: https://docs.mcpulse.io