Proxy MCP Server

Overview

MCP Proxy is a specialized server that aggregates multiple Model Context Protocol (MCP) resource servers and exposes them through a single HTTP endpoint. This allows AI assistants to access a wide range of tools from different sources without needing to connect to each one individually.

Installation Options

Using Docker (Recommended)

The Docker image comes with support for both npx and uvx MCP calling methods by default:

docker run -d -p 9090:9090 -v /path/to/config.json:/config/config.json ghcr.io/tbxark/mcp-proxy:latest

You can also specify a remote configuration:

docker run -d -p 9090:9090 ghcr.io/tbxark/mcp-proxy:latest --config https://example.com/path/to/config.json

Using Go Install

If you have Go installed, you can install MCP Proxy directly:

go install github.com/TBXark/mcp-proxy@latest

Building from Source

For those who prefer to build from source:

git clone https://github.com/TBXark/mcp-proxy.git
cd mcp-proxy
make build
./build/mcp-proxy --config path/to/config.json

Configuration

MCP Proxy uses a JSON configuration file to define its behavior and the MCP servers it connects to. Here's an example configuration:

{
  "mcpProxy": {
    "baseURL": "https://mcp.example.com",
    "addr": ":9090",
    "name": "MCP Proxy",
    "version": "1.0.0",
    "options": {
      "panicIfInvalid": false,
      "logEnabled": true,
      "authTokens": [
        "DefaultTokens"
      ]
    }
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      },
      "options": {
        "toolFilter": {
          "mode": "block",
          "list": [
            "create_or_update_file"
          ]
        }
      }
    },
    "fetch": {
      "command": "uvx",
      "args": [
        "mcp-server-fetch"
      ],
      "options": {
        "panicIfInvalid": true,
        "logEnabled": false,
        "authTokens": [
          "SpecificTokens"
        ]
      }
    },
    "amap": {
      "url": "https://mcp.amap.com/sse?key=<YOUR_TOKEN>"
    }
  }
}

Configuration Options

mcpProxy Section

• baseURL: The publicly accessible URL of the server
• addr: The address and port the server listens on
• name: The name of the proxy server
• version: The version of the proxy server
• options: Default options that apply to all MCP servers unless overridden

mcpServers Section

This section defines the MCP servers to connect to. Each server can be configured with:

• Command-based servers (using command and args)
• URL-based servers (using url)
• Environment variables (using env)
• Server-specific options (using options)

Tool Filtering

You can filter which tools are exposed from each server using the toolFilter option:

• mode: Either "allow" (whitelist) or "block" (blacklist)
• list: Array of tool names to allow or block

Authentication

Authentication can be configured at both the proxy level and for individual servers:

• authTokens: List of valid authentication tokens
• Server-specific tokens override the default proxy tokens

Usage with AI Assistants

To use your MCP Proxy with AI assistants like Claude or other MCP-compatible clients, you'll need to provide them with the proxy's URL. The proxy will handle connecting to all the configured MCP servers and present their tools as a unified set.

You can use the web interface at https://tbxark.github.io/mcp-proxy to convert your MCP Proxy configuration into a format that Claude and other AI assistants can use.

Advanced Features

• SSE Support: The proxy provides Server-Sent Events for real-time updates
• Flexible Client Types: Supports stdio, SSE, and streamable-HTTP client types
• Error Handling: Configure how the proxy handles invalid clients with the panicIfInvalid option
• Logging: Enable or disable logging for debugging with the logEnabled option