Skip to content

Commit 2cd3a2a

Browse files
hrntknrhrntknr
authored
docs: improve README overview and organization (#48)
* 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 * 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
1 parent 928761c commit 2cd3a2a

1 file changed

Lines changed: 51 additions & 128 deletions

File tree

‎README.md‎

Lines changed: 51 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,19 @@
22

33
![Secure your MCP server with OAuth 2.1 — in a minute](./mcp-auth-proxy.svg)
44

5-
If this project saves you time, please give it a star — it really helps visibility.
5+
> If you found value here, please consider starring.
6+
7+
## Overview
8+
9+
- **Drop-in OAuth 2.1/OIDC gateway for MCP servers — put it in front, no code changes.**
10+
- **Your IdP, your choice**: Google, GitHub, or any OIDC provider — e.g. Okta, Auth0, Azure AD, Keycloak — plus optional password with allow-list.
11+
- **Publish local stdio MCP servers safely**: bridge to a public streamable HTTP endpoint (/mcp) with automatic TLS (ACME/Let’s Encrypt).
12+
- **Verified across major MCP clients**: Claude, Claude Code, ChatGPT, GitHub Copilot, Cursor, etc. — the proxy smooths client-specific quirks for consistent auth.
613

714
## Quickstart
815

916
> Domain binding & 80/443 must be accessible from outside.
1017
11-
### Binary
12-
1318
Download binary from [release](https://github.com/sigbit/mcp-auth-proxy/releases) page.
1419

1520
If you use stdio transport
@@ -19,135 +24,27 @@ If you use stdio transport
1924
--external-url https://{your-domain} \
2025
--tls-accept-tos \
2126
--password changeme \
22-
-- npx -y @modelcontextprotocol/server-filesystem /
27+
-- npx -y @modelcontextprotocol/server-filesystem ./
2328
```
2429

25-
If you use sse/http transport
26-
27-
```sh
28-
./mcp-auth-proxy \
29-
--external-url https://{your-domain} \
30-
--tls-accept-tos \
31-
--password changeme \
32-
http://localhost:8080
33-
```
34-
35-
This will automatically obtain and manage Let's Encrypt TLS certificates for your domain.
36-
37-
```json
38-
{
39-
"mcpServers": {
40-
"mcp": {
41-
"type": "http",
42-
"url": "https://{your-domain}/mcp"
43-
}
44-
}
45-
}
46-
```
47-
48-
### Docker
49-
50-
51-
If you use stdio transport
52-
53-
```
54-
docker run --rm -p 80:80 -p 443:443 \
55-
-e EXTERNAL_URL=https://{your-domain} \
56-
-e TLS_ACCEPT_TOS=1 \
57-
-e PASSWORD=changeme \
58-
-v ./data:/data \
59-
ghcr.io/sigbit/mcp-auth-proxy:latest \
60-
-- npx -y @modelcontextprotocol/server-filesystem /
61-
```
62-
63-
If you use sse/http transport
64-
65-
```
66-
docker run --rm --net=host \
67-
-e EXTERNAL_URL=https://{your-domain} \
68-
-e TLS_ACCEPT_TOS=1 \
69-
-e PASSWORD=changeme \
70-
-v ./data:/data \
71-
ghcr.io/sigbit/mcp-auth-proxy:latest \
72-
http://localhost:8080
73-
```
74-
75-
This will automatically obtain and manage Let's Encrypt TLS certificates for your domain.
76-
77-
```json
78-
{
79-
"mcpServers": {
80-
"mcp": {
81-
"type": "http",
82-
"url": "https://{your-domain}/mcp"
83-
}
84-
}
85-
}
86-
```
87-
88-
89-
## Overview
90-
91-
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.
30+
That's it! Your streamable HTTP endpoint is now available at `https://{your-domain}/mcp`.
31+
To proxy SSE/streamable HTTP transport, specify a URL; to use the stdio transport, specify a command.
9232

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

95-
## Note
96-
97-
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.
35+
## Verified MCP Client
9836

99-
## 🔧 Configuration
37+
| MCP Client | Status | Notes |
38+
| ----------------- | ------ | ------------------------------------------------ |
39+
| Claude - Web | ✅ | |
40+
| Claude - Desktop | ✅ | |
41+
| Claude Code | ✅ | |
42+
| ChatGPT - Web | ✅ | Need to implement `search` and `fetch` tools.(1) |
43+
| ChatGPT - Desktop | ✅ | Need to implement `search` and `fetch` tools.(1) |
44+
| GitHub Copilot | ✅ | |
45+
| Cursor | ✅ | |
10046

101-
### Environment Variables
102-
103-
| Variable | Required | Description | Default |
104-
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
105-
| `LISTEN` | No | Server listen address | `:80` |
106-
| `TLS_LISTEN` | No | Address to listen on for TLS | `:443` |
107-
| `AUTO_TLS` | No | Automatically setup TLS certificates from externalURL | `true` |
108-
| `TLS_HOST` | No | Host name for automatic TLS certificate | - |
109-
| `TLS_DIRECTORY_URL` | No | ACME directory URL for TLS certificates | `https://acme-v02.api.letsencrypt.org/directory` |
110-
| `TLS_ACCEPT_TOS` | No | Accept TLS terms of service | `false` |
111-
| `DATA_PATH` | No | Data directory path | `./data` |
112-
| `EXTERNAL_URL` | No | External URL for OAuth callbacks | `http://localhost` |
113-
| `GOOGLE_CLIENT_ID` | No | Google OAuth client ID | - |
114-
| `GOOGLE_CLIENT_SECRET` | No | Google OAuth client secret | - |
115-
| `GOOGLE_ALLOWED_USERS` | No | Comma-separated list of allowed Google emails | - |
116-
| `GITHUB_CLIENT_ID` | No | GitHub OAuth client ID | - |
117-
| `GITHUB_CLIENT_SECRET` | No | GitHub OAuth client secret | - |
118-
| `GITHUB_ALLOWED_USERS` | No | Comma-separated list of allowed GitHub usernames | - |
119-
| `OIDC_CONFIGURATION_URL` | No | OIDC configuration URL | - |
120-
| `OIDC_CLIENT_ID` | No | OIDC client ID | - |
121-
| `OIDC_CLIENT_SECRET` | No | OIDC client secret | - |
122-
| `OIDC_SCOPES` | No | Comma-separated list of OIDC scopes | `openid,profile,email` |
123-
| `OIDC_USER_ID_FIELD` | No | JSON pointer to user ID field in userinfo endpoint response | `/email` |
124-
| `OIDC_PROVIDER_NAME` | No | Display name for OIDC provider | `OIDC` |
125-
| `OIDC_ALLOWED_USERS` | No | Comma-separated list of allowed OIDC users | - |
126-
| `PASSWORD` | No | Plain text password (will be hashed with bcrypt) | - |
127-
| `PASSWORD_HASH` | No | Bcrypt hash of password for authentication | - |
128-
| `PROXY_BEARER_TOKEN` | No | Bearer token to add to Authorization header when proxying requests | - |
129-
| `PROXY_HEADERS` | No | Comma-separated list of headers to add when proxying requests (format: Header1:Value1,Header2:Value2) | - |
130-
| `MODE` | No | Set to `debug` for development mode | `production` |
131-
132-
### OAuth Provider Setup
133-
134-
#### Google OAuth Setup
135-
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
136-
2. Create a new project or select an existing one
137-
3. Enable the Google+ API
138-
4. Create OAuth 2.0 credentials
139-
5. Add authorized redirect URI: `{EXTERNAL_URL}/.auth/google/callback`
140-
141-
#### GitHub OAuth Setup
142-
1. Go to the [Register new GitHub App](https://github.com/settings/apps/new)
143-
2. Set Authorization callback URL: `{EXTERNAL_URL}/.auth/github/callback`
144-
145-
#### OIDC Provider Setup
146-
1. Configure your OIDC provider (e.g., Keycloak, Auth0, Azure AD, etc.)
147-
2. Create a new client application
148-
3. Set redirect URI: `{EXTERNAL_URL}/.auth/oidc/callback`
149-
4. Note the configuration URL (usually issuer URL + /.well-known/openid-configuration), client ID, and client secret
150-
5. Configure the userinfo endpoint to return user identification field (default: email)
47+
- *1: https://platform.openai.com/docs/mcp
15148

15249
## 🚀 Usage
15350

@@ -170,7 +67,7 @@ Download the latest binary from [releases](https://github.com/sigbit/mcp-auth-pr
17067
--oidc-client-id "your-oidc-client-id" \
17168
--oidc-client-secret "your-oidc-client-secret" \
17269
--oidc-allowed-users "[email protected],[email protected]" \
173-
http://localhost:8080
70+
http://localhost:8080 # or execute command (for stdio transport)
17471
```
17572

17673
### Method 2: Docker
@@ -192,9 +89,35 @@ docker run --rm --net=host \
19289
-e OIDC_ALLOWED_USERS="[email protected],[email protected]" \
19390
-v ./data:/data \
19491
ghcr.io/sigbit/mcp-auth-proxy:latest \
195-
http://localhost:8080
92+
http://localhost:8080 # or execute command (for stdio transport)
19693
```
19794

95+
## 🔧 Configuration
96+
97+
### Provider Setup
98+
99+
#### Google OAuth Setup
100+
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
101+
2. Create a new project or select an existing one
102+
3. Create OAuth consent screen
103+
4. Credentials → Create credentials → OAuth client ID (Web application)
104+
5. Add authorized redirect URI: `{EXTERNAL_URL}/.auth/google/callback`
105+
106+
#### GitHub OAuth Setup
107+
1. Go to the [Register new OAuth App](https://github.com/settings/applications/new)
108+
2. Set Authorization callback URL: `{EXTERNAL_URL}/.auth/github/callback`
109+
110+
#### OIDC Provider Setup
111+
1. Configure your OIDC provider (e.g., Keycloak, Auth0, Azure AD, etc.)
112+
2. Create a new client application
113+
3. Set redirect URI: `{EXTERNAL_URL}/.auth/oidc/callback`
114+
4. Note the configuration URL (usually issuer URL + /.well-known/openid-configuration), client ID, and client secret
115+
5. Configure the userinfo endpoint to return user identification field (default: email)
116+
117+
## Note
118+
119+
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.
120+
198121
## 🤝 Contributing
199122

200123
For developer guidelines, contribution instructions, and commit message conventions, please see [CONTRIBUTING.md](./CONTRIBUTING.md).

0 commit comments

Comments
 (0)