@agentdb/mcpproxy

MCP proxy server for remote HTTP endpoints supporting JSON and Server-Sent Events responses.

Overview

This package provides a proxy that bridges local MCP (Model Context Protocol) clients with remote MCP servers over HTTP. It's particularly useful for connecting Claude Desktop to remote AgentDB instances or other HTTP-based MCP servers.

Features

• Local MCP Interface: Standard stdin/stdout JSON-RPC interface for MCP clients
• Remote HTTP Proxy: Forwards requests to remote MCP servers via HTTP POST
• Multiple Response Formats: Supports both JSON and Server-Sent Events (text/event-stream)
• Authentication: Optional Bearer token authentication
• Cross-Platform: Works on macOS, Linux, and Windows
• Zero Configuration: Automatically downloads the appropriate binary for your platform

Installation

Global Installation (Recommended)

npm install -g @agentdb/mcpproxy

Use with npx (No Installation Required)

npx @agentdb/mcpproxy --url https://your-server.com/mcp

Usage

Command Line

# Basic usage
mcpproxy --url https://your-agentdb-server.com/mcp

# With authentication
mcpproxy --url https://your-server.com/mcp --token your-auth-token

# Help
mcpproxy --help

Claude Desktop Configuration

Add to your claude_desktop_config.json:

Using Global Installation

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

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"
      ]
    }
  }
}

Configuration Examples

AgentDB Production Server

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

Local Development Server

{
  "mcpServers": {
    "agentdb-dev": {
      "command": "mcpproxy",
      "args": [
        "--url", "http://localhost:3000/mcp"
      ],
      "env": {
        "RUST_LOG": "debug"
      }
    }
  }
}

Multiple Remote Servers

{
  "mcpServers": {
    "agentdb-prod": {
      "command": "mcpproxy",
      "args": ["--url", "https://prod.agentdb.com/mcp", "--token", "prod-token"]
    },
    "agentdb-staging": {
      "command": "mcpproxy", 
      "args": ["--url", "https://staging.agentdb.com/mcp", "--token", "staging-token"]
    }
  }
}

How It Works

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

Supported Remote Servers

• AgentDB: Full support for AgentDB MCP endpoints
• Any HTTP MCP Server: Supporting JSON-RPC 2.0 over HTTP
• Event Stream Servers: Supporting Server-Sent Events responses

Environment Variables

• RUST_LOG: Set logging level (error, warn, info, debug, trace)

Troubleshooting

Binary Download Issues

If the binary fails to download during installation:

1. Check your internet connection
2. Manually download from GitHub Releases
3. Or build from source:

   git clone https://github.com/sutterhill/agentdb.git
   cd agentdb/mcpproxy
   cargo build --release

Connection Issues

• Verify the remote server URL is correct
• Check authentication token if required
• Enable debug logging: RUST_LOG=debug mcpproxy --url ...

Claude Desktop Issues

• Ensure the configuration file syntax is valid JSON
• Restart Claude Desktop after configuration changes
• Check the MCP server indicator in the bottom-right of the input box

Related Packages

• @agentdb/sdk - JavaScript SDK for AgentDB

License

MIT

Repository

https://github.com/sutterhill/agentdb