mcp-auth-proxy

mcp-auth-proxy acts as a drop-in OAuth 2.1/OIDC gateway and authentication proxy in front of an MCP server. It can wrap a local MCP server (via stdio) or proxy an existing backend over SSE/HTTP, adding authentication and optional password support. When using stdio, traffic is converted to the /mcp path for the MCP endpoint; for SSE/HTTP, the proxy passes through the backend’s original path, while enforcing authentication. To use it, start the proxy with your external URL (domain) and TLS handling preferences, then specify the MCP server implementation to run behind it (for example via npx with the server-filesystem provider). The README example shows launching the proxy with a local binary and then using npx to run the filesystem-based MCP server in front of it. The proxy supports Google, GitHub, or any OpenID Connect provider as IdP, and can enforce optional password protection as an additional authentication factor. Typical workflow: configure your external URL and IdP, start the proxy, and access your MCP endpoint at https://your-domain/mcp with authentication enforced.

Prerequisites:

• A domain name reachable from clients and external access to port 80/443 (for domain binding).
• TLS setup (either TLS cert files or accept-toS flow).
• A downloadable binary for the mcp-auth-proxy release, or Node.js environment if you prefer the npx approach.

Installation steps (binary release):

1. Download the mcp-auth-proxy binary from the releases page and make it executable:

   curl -L <release-url> -o mcp-auth-proxy chmod +x mcp-auth-proxy

2. Run with required options, pointing to an MCP backend via npx:

   ./mcp-auth-proxy
   --external-url https://{your-domain}
   --tls-accept-tos
   --password changeme
   -- npx -y @modelcontextprotocol/server-filesystem ./

3. If you already have certificates, you can supply them with TLS cert/key files instead of --tls-accept-tos.

Alternative (direct npx usage without binary):

• Ensure you have Node.js and npm installed.

• Run the MCP backend behind the proxy using:

  ./mcp-auth-proxy
  --external-url https://{your-domain}
  --password changeme
  -- npx -y @modelcontextprotocol/server-filesystem ./

Prerequisites recap:

• Domain and external reachability (80/443).
• TLS configuration or policy to accept TLS terms.
• IdP configuration (Google, GitHub, or any OIDC provider) and public client IDs/secrets as needed by your IdP.

Tips and common considerations:

• The mcp-auth-proxy acts as a gateway, so you can put it in front of a Gateway if you need central authentication across multiple MCPs.
• When using stdio, you’ll typically run a local filesystem-based MCP server behind the proxy; for SSE/HTTP, you can point the proxy at an existing backend URL.
• If you already have TLS certificates, pass --tls-cert-file and --tls-key-file instead of --tls-accept-tos.
• Environment variables to consider: EXTERNAL_URL (used to build redirect URIs), PASSWORD (optional password-based MFA), LOG_LEVEL (debug/info/warn/error).
• Ensure your IdP is configured with the proxy’s external URL and the required redirect URIs as specified by the IdP documentation.
• If you encounter issues with client compatibility, verify that the MCP endpoint is accessible at /mcp when using stdio.
• The proxy supports standard MCP transports; if you need to preserve the backend’s original paths (SSE/HTTP), confirm the backend URL is reachable and that CORS and TLS settings permit the proxy to forward requests properly.