MCPulse Proxy

Analytics proxy for Model Context Protocol servers. Transparent middleware that collects metrics without code changes.

Installation

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

Or build from source:

go build -o mcpulse-proxy .

Usage

Commands

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

Quick 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

Using config file:

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

Configuration

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 config (use directly):

• MCPULSE_URL or MCPULSE_SERVER - MCPulse endpoint
• MCPULSE_API_KEY - API key

Proxy config (use MCPULSE_PROXY_ prefix):

• MCPULSE_PROXY_SERVER_ID - Server ID
• MCPULSE_PROXY_COMMAND - Command to run
• MCPULSE_PROXY_REMOTE_URL - Remote URL
• MCPULSE_PROXY_BEARER_TOKEN - Bearer token
• MCPULSE_PROXY_HEADERS - Custom headers
• MCPULSE_PROXY_LISTEN - Listen address

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "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",
        "API_KEY": "your-server-api-key"
      }
    }
  }
}

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

License

Same as MCPulse project

Support

• GitHub: https://github.com/sirrobot01/mcpulse/issues
• Docs: https://docs.mcpulse.io