From 97aba57f64212ed0e4eb47d1e76591b5f6b252d0 Mon Sep 17 00:00:00 2001 From: Takanori Hirano Date: Wed, 20 Aug 2025 17:53:28 +0000 Subject: [PATCH 1/2] docs: improve README overview and organization - Restructure opening with clearer value proposition - Move key features to overview section for better discoverability - Reorganize sections with client verification table prominently displayed - Improve quickstart flow and simplify initial setup - Enhance provider setup instructions with better organization --- README.md | 177 +++++++++++++++--------------------------------------- 1 file changed, 50 insertions(+), 127 deletions(-) diff --git a/README.md b/README.md index 9c65aea..9d15a6a 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,19 @@ ![Secure your MCP server with OAuth 2.1 — in a minute](./mcp-auth-proxy.svg) -If this project saves you time, please give it a star — it really helps visibility. +> If you found value here, please consider starring. + +## Overview + +- **Drop-in OAuth 2.1/OIDC gateway for MCP servers — put it in front, no code changes.** +- **Your IdP, your choice**: Google, GitHub, or any OIDC provider — e.g. Okta, Auth0, Azure AD, Keycloak — plus optional password with allow-list. +- **Publish local stdio MCP servers safely**: bridge to a public streamable HTTP endpoint (/mcp) with automatic TLS (ACME/Let’s Encrypt). +- **Verified across major MCP clients**: Claude, Claude Code, ChatGPT, GitHub Copilot, Cursor, etc. — the proxy smooths client-specific quirks for consistent auth. ## Quickstart > Domain binding & 80/443 must be accessible from outside. -### Binary - Download binary from [release](https://github.com/sigbit/mcp-auth-proxy/releases) page. If you use stdio transport @@ -22,132 +27,24 @@ If you use stdio transport -- npx -y @modelcontextprotocol/server-filesystem / ``` -If you use sse/http transport - -```sh -./mcp-auth-proxy \ - --external-url https://{your-domain} \ - --tls-accept-tos \ - --password changeme \ - http://localhost:8080 -``` - -This will automatically obtain and manage Let's Encrypt TLS certificates for your domain. - -```json -{ - "mcpServers": { - "mcp": { - "type": "http", - "url": "https://{your-domain}/mcp" - } - } -} -``` - -### Docker - - -If you use stdio transport - -``` -docker run --rm -p 80:80 -p 443:443 \ - -e EXTERNAL_URL=https://{your-domain} \ - -e TLS_ACCEPT_TOS=1 \ - -e PASSWORD=changeme \ - -v ./data:/data \ - ghcr.io/sigbit/mcp-auth-proxy:latest \ - -- npx -y @modelcontextprotocol/server-filesystem / -``` - -If you use sse/http transport +That's it! Your streamable HTTP endpoint is now available at `https://{your-domain}/mcp`. +To proxy SSE/streamable HTTP transport, specify a URL; to use the stdio transport, specify a command. -``` -docker run --rm --net=host \ - -e EXTERNAL_URL=https://{your-domain} \ - -e TLS_ACCEPT_TOS=1 \ - -e PASSWORD=changeme \ - -v ./data:/data \ - ghcr.io/sigbit/mcp-auth-proxy:latest \ - http://localhost:8080 -``` - -This will automatically obtain and manage Let's Encrypt TLS certificates for your domain. - -```json -{ - "mcpServers": { - "mcp": { - "type": "http", - "url": "https://{your-domain}/mcp" - } - } -} -``` +(Listen on 80/443 and automatically set up certificates, but use the no-auto-tls option if not needed.) +## Verified MCP Client -## Overview - -MCP Auth Proxy is a secure OAuth 2.1 authentication proxy for Model Context Protocol (MCP) servers. MCP servers are expected to support not only standard OAuth 2.1 flows but also Dynamic Client support (e.g., dynamic client registration) and authentication-related .well-known metadata. On top of that, different MCP clients handle tokens differently, which makes implementation tricky. +| MCP Client | Status | Notes | +| ----------------- | ------ | ------------------------------------------------- | +| Claude - Web | ✅ | | +| Claude - Desktop | ✅ | | +| Claude Code | ✅ | | +| ChatGPT - Web | ✅ | Need to implement `search` and `fetch` tools.(*1) | +| ChatGPT - Desktop | ✅ | Need to implement `search` and `fetch` tools.(*1) | +| GitHub Copilot | ✅ | | +| Cursor | ✅ | | -MCP Auth Proxy sits in front of your MCP services and enforces sign-in with OAuth providers (such as Google or GitHub or OIDC) or password before users can access protected MCP resources. - -## Note - -For a simpler approach to publish local MCP servers over OAuth, consider [MCP Warp](https://github.com/sigbit/mcp-warp), which provides an OAuth Proxy + ngrok-like service. We highly recommend considering this option as well. - -## 🔧 Configuration - -### Environment Variables - -| Variable | Required | Description | Default | -| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------ | -| `LISTEN` | No | Server listen address | `:80` | -| `TLS_LISTEN` | No | Address to listen on for TLS | `:443` | -| `AUTO_TLS` | No | Automatically setup TLS certificates from externalURL | `true` | -| `TLS_HOST` | No | Host name for automatic TLS certificate | - | -| `TLS_DIRECTORY_URL` | No | ACME directory URL for TLS certificates | `https://acme-v02.api.letsencrypt.org/directory` | -| `TLS_ACCEPT_TOS` | No | Accept TLS terms of service | `false` | -| `DATA_PATH` | No | Data directory path | `./data` | -| `EXTERNAL_URL` | No | External URL for OAuth callbacks | `http://localhost` | -| `GOOGLE_CLIENT_ID` | No | Google OAuth client ID | - | -| `GOOGLE_CLIENT_SECRET` | No | Google OAuth client secret | - | -| `GOOGLE_ALLOWED_USERS` | No | Comma-separated list of allowed Google emails | - | -| `GITHUB_CLIENT_ID` | No | GitHub OAuth client ID | - | -| `GITHUB_CLIENT_SECRET` | No | GitHub OAuth client secret | - | -| `GITHUB_ALLOWED_USERS` | No | Comma-separated list of allowed GitHub usernames | - | -| `OIDC_CONFIGURATION_URL` | No | OIDC configuration URL | - | -| `OIDC_CLIENT_ID` | No | OIDC client ID | - | -| `OIDC_CLIENT_SECRET` | No | OIDC client secret | - | -| `OIDC_SCOPES` | No | Comma-separated list of OIDC scopes | `openid,profile,email` | -| `OIDC_USER_ID_FIELD` | No | JSON pointer to user ID field in userinfo endpoint response | `/email` | -| `OIDC_PROVIDER_NAME` | No | Display name for OIDC provider | `OIDC` | -| `OIDC_ALLOWED_USERS` | No | Comma-separated list of allowed OIDC users | - | -| `PASSWORD` | No | Plain text password (will be hashed with bcrypt) | - | -| `PASSWORD_HASH` | No | Bcrypt hash of password for authentication | - | -| `PROXY_BEARER_TOKEN` | No | Bearer token to add to Authorization header when proxying requests | - | -| `PROXY_HEADERS` | No | Comma-separated list of headers to add when proxying requests (format: Header1:Value1,Header2:Value2) | - | -| `MODE` | No | Set to `debug` for development mode | `production` | - -### OAuth Provider Setup - -#### Google OAuth Setup -1. Go to the [Google Cloud Console](https://console.cloud.google.com/) -2. Create a new project or select an existing one -3. Enable the Google+ API -4. Create OAuth 2.0 credentials -5. Add authorized redirect URI: `{EXTERNAL_URL}/.auth/google/callback` - -#### GitHub OAuth Setup -1. Go to the [Register new GitHub App](https://github.com/settings/apps/new) -2. Set Authorization callback URL: `{EXTERNAL_URL}/.auth/github/callback` - -#### OIDC Provider Setup -1. Configure your OIDC provider (e.g., Keycloak, Auth0, Azure AD, etc.) -2. Create a new client application -3. Set redirect URI: `{EXTERNAL_URL}/.auth/oidc/callback` -4. Note the configuration URL (usually issuer URL + /.well-known/openid-configuration), client ID, and client secret -5. Configure the userinfo endpoint to return user identification field (default: email) +- *1: https://platform.openai.com/docs/mcp ## 🚀 Usage @@ -170,7 +67,7 @@ Download the latest binary from [releases](https://github.com/sigbit/mcp-auth-pr --oidc-client-id "your-oidc-client-id" \ --oidc-client-secret "your-oidc-client-secret" \ --oidc-allowed-users "user1@example.com,user2@example.com" \ - http://localhost:8080 + http://localhost:8080 # or execute command (for stdio transport) ``` ### Method 2: Docker @@ -192,9 +89,35 @@ docker run --rm --net=host \ -e OIDC_ALLOWED_USERS="user1@example.com,user2@example.com" \ -v ./data:/data \ ghcr.io/sigbit/mcp-auth-proxy:latest \ - http://localhost:8080 + http://localhost:8080 # or execute command (for stdio transport) ``` +## 🔧 Configuration + +### Provider Setup + +#### Google OAuth Setup +1. Go to the [Google Cloud Console](https://console.cloud.google.com/) +2. Create a new project or select an existing one +3. Create OAuth consent screen +4. Credentials → Create credentials → OAuth client ID（Web application） +5. Add authorized redirect URI: `{EXTERNAL_URL}/.auth/google/callback` + +#### GitHub OAuth Setup +1. Go to the [Register new OAuth App](https://github.com/settings/applications/new) +2. Set Authorization callback URL: `{EXTERNAL_URL}/.auth/github/callback` + +#### OIDC Provider Setup +1. Configure your OIDC provider (e.g., Keycloak, Auth0, Azure AD, etc.) +2. Create a new client application +3. Set redirect URI: `{EXTERNAL_URL}/.auth/oidc/callback` +4. Note the configuration URL (usually issuer URL + /.well-known/openid-configuration), client ID, and client secret +5. Configure the userinfo endpoint to return user identification field (default: email) + +## Note + +For a simpler approach to publish local MCP servers over OAuth, consider [MCP Warp](https://github.com/sigbit/mcp-warp), which provides an OAuth Proxy + ngrok-like service. We highly recommend considering this option as well. + ## 🤝 Contributing For developer guidelines, contribution instructions, and commit message conventions, please see [CONTRIBUTING.md](./CONTRIBUTING.md). From 595695377e7d9d4151f6d9b96d10d0f318869c6f Mon Sep 17 00:00:00 2001 From: Takanori Hirano Date: Wed, 20 Aug 2025 17:56:18 +0000 Subject: [PATCH 2/2] docs: improve README formatting and path references - Change filesystem path from / to ./ for better security - Fix table formatting in verified MCP clients section - Standardize punctuation in OAuth setup instructions --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 9d15a6a..c11b874 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ If you use stdio transport --external-url https://{your-domain} \ --tls-accept-tos \ --password changeme \ - -- npx -y @modelcontextprotocol/server-filesystem / + -- npx -y @modelcontextprotocol/server-filesystem ./ ``` That's it! Your streamable HTTP endpoint is now available at `https://{your-domain}/mcp`. @@ -34,15 +34,15 @@ To proxy SSE/streamable HTTP transport, specify a URL; to use the stdio transpor ## Verified MCP Client -| MCP Client | Status | Notes | -| ----------------- | ------ | ------------------------------------------------- | -| Claude - Web | ✅ | | -| Claude - Desktop | ✅ | | -| Claude Code | ✅ | | -| ChatGPT - Web | ✅ | Need to implement `search` and `fetch` tools.(*1) | -| ChatGPT - Desktop | ✅ | Need to implement `search` and `fetch` tools.(*1) | -| GitHub Copilot | ✅ | | -| Cursor | ✅ | | +| MCP Client | Status | Notes | +| ----------------- | ------ | ------------------------------------------------ | +| Claude - Web | ✅ | | +| Claude - Desktop | ✅ | | +| Claude Code | ✅ | | +| ChatGPT - Web | ✅ | Need to implement `search` and `fetch` tools.(1) | +| ChatGPT - Desktop | ✅ | Need to implement `search` and `fetch` tools.(1) | +| GitHub Copilot | ✅ | | +| Cursor | ✅ | | - *1: https://platform.openai.com/docs/mcp @@ -100,7 +100,7 @@ docker run --rm --net=host \ 1. Go to the [Google Cloud Console](https://console.cloud.google.com/) 2. Create a new project or select an existing one 3. Create OAuth consent screen -4. Credentials → Create credentials → OAuth client ID（Web application） +4. Credentials → Create credentials → OAuth client ID (Web application) 5. Add authorized redirect URI: `{EXTERNAL_URL}/.auth/google/callback` #### GitHub OAuth Setup