MCP Proxy

You configure and run an MCP proxy server that connects your AI agents to multiple MCP endpoints, discovers tools efficiently, and enforces secure isolation and management. This server accelerates tool access, reduces token usage, and protects you from malicious MCP servers while working across different environments and clients.

How to use

Install and run the proxy, then connect your MCP client or IDE to the local proxy endpoint. The proxy aggregates tools from configured MCP servers, exposes a unified interface to your AI agent, and returns curated results that help your agent perform actions faster with fewer tokens. You can manage servers, secrets, and security policies from the system tray, CLI, or REST/MC protocol.

How to install

# Prerequisite: Go (for building or installing the proxy go binary)
go version

auto-install or manual:

# Install the MCP proxy compiler binary (Go-based) from the official source
# This example uses the Go install flow shown in the source

# Install latest binary for your platform
go install github.com/smart-mcp-proxy/mcpproxy-go/cmd/mcpproxy@latest

# Verify installation
mcpproxy version

# Run the proxy (listen on localhost:8080 and show tray)
mcpproxy serve

Additional sections

The proxy accepts a minimal configuration file that defines how it should start and which MCP servers to connect to. You can run servers locally (stdio) or point to remote MCP endpoints (http). The recommended approach is to keep the proxy behind localhost for security and use HTTPS when exposing it in production.

Configuration and usage notes

Key configuration options control what the proxy exposes, how many tools are returned, and how responses are managed. You can enable a system tray UI, limit the number of tools, set maximum response sizes, and configure TLS for encrypted connections. You can also enable Docker-based isolation for stdio servers and set up OAuth for servers that require user authorization.

{
  "listen": "127.0.0.1:8080",
  "data_dir": "~/.mcpproxy",
  "enable_tray": true,

  "top_k": 5,
  "tools_limit": 15,
  "tool_response_limit": 20000,

  "tls": {
    "enabled": false,
    "require_client_cert": false,
    "hsts": true
  },

  "mcpServers": [
    { "name": "local_python", "command": "python", "args": ["-m", "my_server"], "protocol": "stdio", "enabled": true },
    { "name": "remote_http", "url": "http://localhost:3001", "protocol": "http", "enabled": true }
  ]
}

Secrets management and placeholders

MCPProxy stores sensitive information in your operating system’s native keyring. You can set, list, retrieve, and delete secrets from the CLI, and reference them in your configuration with placeholders like ${keyring:secret_name}. This keeps credentials out of config files while still making them available to your MCP servers at runtime.

mcpproxy secrets set github_token
mcpproxy secrets list
mcpproxy secrets get github_token
mcpproxy secrets delete github_token

Docker isolation and recovery (advanced)

For stdio MCP servers you can enable Docker-based isolation to run each server in its own container. This strengthens security by isolating processes, file systems, and networks. The proxy also includes automatic Docker recovery to handle engine outages, with health checks and automatic reconnection when Docker becomes available again.

OAuth authentication support

Some MCP servers require user authorization. The proxy supports OAuth 2.1 with PKCE, dynamic port allocation, auto browser launch, and automatic token management. You can configure OAuth for specific MCP servers to customize scopes and client credentials.

Notes for Claude Desktop and other integrations

Integrations with Claude Desktop, VS Code, Cursor, and other tools use the proxy URL. You can enable HTTPS and trust the local certificate to ensure secure connections. When using Claude Desktop, you can point it to the local proxy endpoint or to an HTTPS endpoint once you have TLS configured.

Available tools

serve

Start the proxy, enable the system tray, and listen for HTTP connections on the configured address.

tools list

Query and display available tools from configured MCP servers for debugging and scripting.

trust-cert

Install the TLS certificate as trusted in your OS to enable HTTPS connections.

upstream list

List all configured MCP servers with their current status.

upstream restart

Restart a specific MCP server to apply changes or recover from errors.

doctor

Run health diagnostics to verify proxy operation and server readiness.

secrets set

Store a secret in the OS keyring.

secrets list

List stored secrets in the OS keyring.

secrets get

Retrieve a secret from the OS keyring.

secrets delete

Remove a secret from the OS keyring.

oauth

Configure and manage OAuth-enabled MCP servers for user authorization.