MCP Proxy

A local stdin/stdout MCP (Model Context Protocol) server that proxies requests to a remote MCP server over HTTP.

Overview

This tool acts as a bridge between MCP clients that expect a local stdin/stdout interface and remote MCP servers that communicate over HTTP. It reads JSON-RPC requests from stdin, forwards them to the configured remote server, and writes the responses back to stdout.

Features

• Local MCP Interface: Provides standard stdin/stdout JSON-RPC interface expected by MCP clients
• Remote HTTP Proxy: Forwards all requests to a remote MCP server via HTTP POST
• Multiple Response Formats: Supports both JSON and Server-Sent Events (text/event-stream) responses
• Authentication Support: Optional Bearer token authentication for remote servers
• Error Handling: Proper JSON-RPC error responses for network failures and parsing errors
• Logging: Debug information written to stderr (doesn't interfere with JSON-RPC communication)

Installation

Option 1: npm Package (Recommended)

# Global installation
npm install -g @agentdb/mcpproxy

# Or use with npx (no installation required)
npx @agentdb/mcpproxy --url https://your-server.com/mcp

Option 2: Cargo Install

cargo install mcpproxy

Option 3: Build from Source

cargo build --release

Usage

Basic Usage

./target/release/mcpproxy --url https://your-remote-mcp-server.com/mcp

With Authentication

./target/release/mcpproxy --url https://your-remote-mcp-server.com/mcp --token your-auth-token

Command Line Options

• --url, -u: Remote MCP server URL to proxy to (required)
• --token, -t: Optional authentication token for the remote server

How It Works

1. Input: Reads JSON-RPC requests from stdin (one per line)
2. Forward: Sends each request to the remote server via HTTP POST with headers:
   • Content-Type: application/json
   • Accept: application/json, text/event-stream
   • Authorization: Bearer <token> (if token provided)
3. Response Handling:
   • JSON Response: Single JSON-RPC response written to stdout
   • Event Stream Response: Multiple JSON-RPC responses from Server-Sent Events, each written to stdout
4. Logging: Debug information goes to stderr

Response Format Support

JSON Responses

Standard single JSON-RPC response from the remote server.

Server-Sent Events (Event Stream)

When the remote server responds with Content-Type: text/event-stream, the proxy:

1. Parses the event stream format (data: ... lines)
2. Extracts JSON-RPC responses from each event
3. Outputs each response as a separate line to stdout
4. Handles multiple responses from a single request

JSON-RPC Protocol

The proxy handles standard JSON-RPC 2.0 messages:

Request Format

{
  "jsonrpc": "2.0",
  "method": "method_name",
  "params": {...},
  "id": 1
}

Response Format

{
  "jsonrpc": "2.0",
  "result": {...},
  "id": 1
}

Error Format

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "Additional error details"
  },
  "id": 1
}

Error Codes

• -32700: Parse error (invalid JSON)
• -32603: Internal error (network or server errors)
• HTTP status codes are passed through as error codes for remote server errors

Example Usage with MCP Client

# Using npm package
npx @agentdb/mcpproxy --url https://api.example.com/mcp --token abc123

# Or if globally installed
mcpproxy --url https://api.example.com/mcp --token abc123

# Test with a simple request
echo '{"jsonrpc":"2.0","method":"ping","id":1}' | npx @agentdb/mcpproxy --url https://api.example.com/mcp

Claude Desktop Configuration

Using npx (No Installation Required)

{
  "mcpServers": {
    "agentdb-remote": {
      "command": "npx",
      "args": [
        "-y", "@agentdb/mcpproxy",
        "--url", "https://your-agentdb-server.com/mcp",
        "--token", "your-auth-token"
      ]
    }
  }
}

Using Global Installation

{
  "mcpServers": {
    "agentdb-remote": {
      "command": "mcpproxy",
      "args": [
        "--url", "https://your-agentdb-server.com/mcp",
        "--token", "your-auth-token"
      ]
    }
  }
}

Development

Building

cargo build

Running Tests

cargo test

Running with Debug Logging

RUST_LOG=debug cargo run -- --url https://your-server.com/mcp

Dependencies

• tokio: Async runtime
• reqwest: HTTP client with streaming support
• serde/serde_json: JSON serialization
• clap: Command line argument parsing
• anyhow: Error handling
• futures-util: Stream processing for event streams
• tokio-util: Additional utilities for async I/O

License

This project is licensed under the MIT License.