@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

$3

``bash
npm install -g @agentdb/mcpproxy
`

$3

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

Usage

$3

`bash


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
`

$3

Add to your claude_desktop_config.json:

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

#### Using npx (No Installation Required)
`json
{
"mcpServers": {
"agentdb-remote": {
"command": "npx",
"args": [
"-y", "@agentdb/mcpproxy",
"--url", "https://your-agentdb-server.com/mcp",
"--token", "your-auth-token"
]
}
}
}
`

Configuration Examples

$3


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

$3

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

$3

`json
{
"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 (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

$3

If the binary fails to download during installation:

1. Check your internet connection
2. Manually download from GitHub Releases
3. Or build from source:
`bash
git clone https://github.com/sutterhill/agentdb.git
cd agentdb/mcpproxy
cargo build --release
`

$3


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

$3

- 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