Smart MCP Proxy is a powerful, secure, and configurable gateway that centralizes access to multiple Model Context Protocol (MCP) servers. It enables organizations to manage tokens centrally, unify MCP server configurations, and expose only the tools and resources they choose — all through a single, transparent HTTP interface with detailed logging.
- Introduction
- Value Proposition
- Features
- Architecture
- Configuration
- Operating Modes
- Usage
- Docker Usage
- Development
- Documentation
- License
Smart MCP Proxy acts as a secure gateway between clients and multiple MCP servers, exposing a curated subset of tools and resources. It simplifies client interactions by presenting a unified API while enforcing fine-grained access control and transparent logging.
- Centralized Token Management: Manage authentication tokens in one place, reducing complexity and improving security.
- Unified MCP Server Configuration: Configure multiple MCP servers in a single proxy configuration file.
- Fine-Grained Exposure: Selectively expose only approved tools and resources from each MCP server.
- Cost Savings Through Smaller Tool Footprint: By exposing only the necessary tools and resources, Smart MCP Proxy reduces token overhead and operational costs, enabling organizations to optimize resource usage and minimize expenses.
- Transparent Logging: Detailed logs of all requests and responses for auditing and troubleshooting.
- Configurable list of MCP servers (HTTP and stdio-based).
- Tool and resource allow-listing per MCP server.
- Automatic lifecycle management of stdio-based MCP servers.
- Implements all standard MCP HTTP endpoints.
- Transparent request and response logging.
- Supports environment variable and command-line configuration.
- Example configuration provided for quick start.
+-------------------+ +-------------------+ +-------------------+
| | | | | |
| Client(s) +-------->+ Smart MCP Proxy +-------->+ MCP Server(s) |
| | HTTP | (this project) | MCP | (downstream) |
+-------------------+ +-------------------+ +-------------------+
| | |
| | |
v v v
[Tool A] [Tool B] [Tool C]
- The proxy listens on HTTP port 8080.
- Routes client requests to allowed tools on configured MCP servers.
- Exposes only explicitly whitelisted tools and resources.
Smart MCP Proxy is configured primarily via a JSON file specifying MCP servers, allowed tools, and resources. The configuration file path can be set via the MCP_PROXY_CONFIG environment variable or the -config command-line argument.
See the detailed configuration documentation in docs/configuration.md and the example configuration at configs/example-config.json.
The proxy can operate in two modes:
- HTTP Mode (default): The proxy listens on an HTTP port (default 8080) and communicates with clients using the standard MCP HTTP protocol.
- Command/STDIO Mode: The proxy communicates with a single client via standard input (STDIN) and standard output (STDOUT), using the MCP command protocol. Logs are written to standard error (STDERR). This mode is useful for direct integration with tools or scripts.
You can select the mode using:
- The
-modecommand-line flag (e.g.,-mode command). - The
MCP_PROXY_MODEenvironment variable (e.g.,export MCP_PROXY_MODE=command).
If neither is specified, the proxy defaults to HTTP mode.
HTTP Mode (Default):
# Using command-line flag for config
./smart-mcp-proxy -config /path/to/config.json
# Using environment variable for config
export MCP_PROXY_CONFIG=/path/to/config.json
./smart-mcp-proxyCommand/STDIO Mode:
# Using command-line flags
./smart-mcp-proxy -config /path/to/config.json -mode command
# Using environment variables
export MCP_PROXY_CONFIG=/path/to/config.json
export MCP_PROXY_MODE=command
./smart-mcp-proxyFor stdio-based MCP servers defined in the configuration, the proxy manages the lifecycle of the server process, including starting and stopping it as needed.
See detailed usage instructions in docs/usage.md.
The official Docker image ghcr.io/timthesinner/smart-mcp-proxy:latest supports amd64 and arm64 architectures.
The Docker image defaults to running the proxy in Command/STDIO mode.
# Example: Run in default Command/STDIO mode, mounting a local config
docker run --rm -i \
-v ./configs/example-config.json:/app/config.json:ro \
-e MCP_PROXY_CONFIG=/app/config.json \
ghcr.io/timthesinner/smart-mcp-proxy:latestNote: -i is used to attach STDIN for command mode.
To run the container in HTTP mode, set the MCP_PROXY_MODE environment variable to http and expose the port (default 8080).
# Example: Run in HTTP mode, mounting a local config and exposing port 8080
docker run --rm -d \
-p 8080:8080 \
-v ./configs/example-config.json:/app/config.json:ro \
-e MCP_PROXY_CONFIG=/app/config.json \
-e MCP_PROXY_MODE=http \
ghcr.io/timthesinner/smart-mcp-proxy:latestFor scenarios requiring the proxy to interact with Docker (e.g., managing stdio servers running in containers), you might need to mount the host's Docker socket or use a DinD sidecar. See docs/usage.md for details and security considerations.
To run the pre-commit checks on your local machine, execute:
go fmt ./...
go test ./...Ensure your code is properly formatted and all tests pass before committing.
A VS Code launch configuration named "Launch Proxy (STDIO Mode)" is provided in .vscode/launch.json. This allows you to easily run and debug the proxy directly in Command/STDIO mode using the example configuration file. Access it via the "Run and Debug" panel in VS Code.