MCP Proxy sits in front of any MCP backend and provides authentication, authorization, and enterprise features while preserving the underlying MCP protocol. It supports OAuth flows (RFC 8414 and RFC 9728 compliant), exposes well-known OAuth endpoints for resource access and authorization server configuration, and offers multiple JWT validation methods (local JWKS-based checks or delegated validation via external systems like Istio). The proxy also bridges transports, meaning it can forward StreamableHTTP or Stdio MCP requests to HTTP or stdio-based backends, enabling remote access to local MCP servers. You can tailor access logs by redacting or excluding fields to meet privacy and compliance needs. The project ships with production-ready conveniences such as a Dockerfile, Helm chart, and CI workflows, and it’s designed to be easily extended atop the mcp-go foundation used in the project.

To use MCP Proxy, run it in front of your existing MCP backend(s) and point clients to the proxy address. Configure JWT validation to match your security posture, and choose either local JWKS validation or delegation to external identity systems. You can also tune the transport bridging to ensure your MCP backends receive requests in the format they expect, whether you’re routing through HTTP or stdio MCP servers. If you want to customize deployment, leverage the provided Helm charts for Kubernetes, or run a local test by starting the proxy with a minimal YAML configuration that defines your backend and trust store, and then verify that authenticated clients can access your MCP services through the proxy.

Prerequisites:

• Go 1.24+ installed on your machine
• Docker (optional, for building/running in containers)
• kubectl and Helm (optional, for Kubernetes deployments)

1. Clone the repository: git clone https://github.com/achetronic/mcp-proxy.git cd mcp-proxy

2. Build from source: go build ./...

   or to run directly without a binary build step (for development):

   go run ./...

3. (Optional) Run with a local YAML configuration and the Go binary:

   • Create a config.yaml describing backends, OAuth endpoints, and logging preferences
   • Run the binary with environment variables as needed, for example: CONFIG_PATH=./config.yaml PORT=8080 ./mcp-proxy

4. Docker option:

   • Build the image: docker build -t achetronic/mcp-proxy:latest .
   • Run the container: docker run -p 8080:8080 achetronic/mcp-proxy:latest (Pass CONFIG_PATH or mount a config as needed)

5. Helm Chart (Kubernetes):

   • Install Helm if not present
   • Use the chart in chart/ to deploy MCP Proxy in your cluster: helm upgrade --install mcp-proxy chart/mcp-proxy --values chart/mcp-proxy/values.yaml

Prerequisites recap: ensure you have Go 1.24+ and, optionally, Docker/Kubernetes tooling if you plan to deploy via containers or Helm. Start with a minimal YAML config to define a backend and trust settings, then run the proxy and verify that clients can authenticate and access the MCP backend through the proxy.

Tips and notes:

• The proxy supports both local JWKS-based JWT validation and delegated validation; choose the method that matches your identity infrastructure.
• When enabling OAuth endpoints, ensure your authorization server and token introspection settings are correctly configured to avoid authorization failures.
• Transport bridging lets you connect to both HTTP-based and stdio-based MCP backends; ensure your backend type is correctly specified in the config.
• If you’re deploying to Kubernetes, leverage the provided Helm charts and Dockerfile to streamline deployment; keep an eye on the logs to tune access control and log redaction settings.
• Common issues: misconfigured OAuth endpoints, invalid JWKS URIs, or network ACLs blocking the proxy from reaching your identity provider or MCP backends. Use verbose logging to diagnose and verify that middleware is correctly parsing claims.
• Environment variables: PORT, CONFIG_PATH, and any identity provider specifics (e.g., JWKS URL, audience, issuer) are commonly used; keep sensitive values in a secure secret store when possible.