Skip to content

docs: improve README overview and organization #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hrntknr merged 2 commits into from
Aug 20, 2025
Merged

docs: improve README overview and organization #48

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
97aba57
docs: improve README overview and organization
hrntknr Aug 20, 2025
5956953
docs: improve README formatting and path references
hrntknr Aug 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 51 additions & 128 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -19,135 +24,27 @@ 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 ./
```

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

```
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"
}
}
}
```


## 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.
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.

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.
(Listen on 80/443 and automatically set up certificates, but use the no-auto-tls option if not needed.)

## 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.
## Verified MCP Client

## 🔧 Configuration
| 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 | ✅ | |

### 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
Copy link

Copilot AI Aug 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] The footnote reference should use a standard format. Consider changing '(*1)' to '(1)' for consistency with markdown conventions.

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Aug 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nitpick] The footnote reference should use a standard format. Consider changing '(*1)' to '(1)' for consistency with markdown conventions.

Copilot uses AI. Check for mistakes.

## 🚀 Usage

Expand All @@ -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 "[email protected],[email protected]" \
http://localhost:8080
http://localhost:8080 # or execute command (for stdio transport)
```

### Method 2: Docker
Expand All @@ -192,9 +89,35 @@ docker run --rm --net=host \
-e OIDC_ALLOWED_USERS="[email protected],[email protected]" \
-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).
Expand Down