# OAuth 2.1 Authentication Guide
Complete guide for using OAuth 2.1 authentication with MCP Hub.
---
## 📋 Table of Contents
1. [Overview](#overview)
2. [Quick Start](#quick-start)
3. [Configuration](#configuration)
4. [OAuth Flows](#oauth-flows)
5. [Registering OAuth Clients](#registering-oauth-clients)
6. [OpenAI GPT Integration](#openai-gpt-integration)
7. [Claude Custom Connectors](#claude-custom-connectors-remote-mcp)
8. [Testing](#testing)
9. [Security Best Practices](#security-best-practices)
10. [Troubleshooting](#troubleshooting)
---
## Overview
MCP Hub implements **OAuth 2.1** with **API Key-Based Authorization** and **MCP Specification Compliance**:
- ✅ **API Key Authentication** - Users authorize with their existing API Keys
- ✅ **Permission Inheritance** - OAuth tokens inherit API Key's scope and project access
- ✅ **PKCE Mandatory** - Proof Key for Code Exchange (S256)
- ✅ **Refresh Token Rotation** - Security best practice
- ✅ **JWT Access Tokens** - Stateless validation
- ✅ **Multiple Grant Types** - Authorization Code, Refresh Token, Client Credentials
- ✅ **Scope-based Authorization** - Fine-grained access control
- ✅ **Backward Compatible** - API Keys still work
- ✅ **Open DCR for MCP Clients** - Claude/ChatGPT can register automatically (RFC 7591) 🆕
- ✅ **Protected Resource Metadata** - RFC 9728 compliant endpoints 🆕
- ✅ **401 + WWW-Authenticate** - Proper OAuth discovery for MCP clients 🆕
### Security Model (Updated for MCP Compliance)
**🔓 Open DCR for Trusted Clients**: Claude and ChatGPT can automatically register OAuth clients without authentication:
- Redirect URIs must match allowlist (claude.ai, chatgpt.com, localhost)
- Rate limited per IP (10/min, 30/hour)
- All registrations are audit logged
**🔐 Protected DCR for Custom Apps**: Custom applications still require Master API Key for registration.
**🔒 API Key Authorization**: Users MUST provide their API Key when authorizing OAuth clients (required mode).
**🎯 Permission Inheritance**: OAuth tokens automatically inherit the API Key's permissions:
- **Master API Key** → OAuth token with full access
- **Per-project API Key** → OAuth token limited to that project
- **Read-only API Key** → OAuth token with read-only access
**✅ Claude/ChatGPT Integration**: MCP clients automatically discover OAuth endpoints and register themselves.
### Supported Grant Types
1. **Authorization Code** (with PKCE) - For third-party apps
2. **Refresh Token** (with rotation) - Renew access tokens
3. **Client Credentials** - Machine-to-machine auth
---
## Quick Start
### 1. Generate JWT Secret
```bash
# Generate a secure secret key
python -c "import secrets; print(secrets.token_urlsafe(64))"
# OR using openssl
openssl rand -base64 64
```
### 2. Configure Environment
Add to `.env`:
```bash
# Required
OAUTH_JWT_SECRET_KEY=your_generated_secret_key_here
# Optional (defaults shown)
OAUTH_JWT_ALGORITHM=HS256
OAUTH_ACCESS_TOKEN_TTL=3600 # 1 hour
OAUTH_REFRESH_TOKEN_TTL=604800 # 7 days
```
### 3. Rebuild & Deploy
```bash
# Local development
docker-compose up --build -d
# Coolify deployment
# Update environment variables in Coolify UI and redeploy
```
---
## Configuration
### Environment Variables
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `OAUTH_JWT_SECRET_KEY` | Secret key for signing JWTs | - | ✅ Yes |
| `OAUTH_JWT_ALGORITHM` | JWT signing algorithm | `HS256` | No |
| `OAUTH_ACCESS_TOKEN_TTL` | Access token lifetime (seconds) | `3600` (1h) | No |
| `OAUTH_REFRESH_TOKEN_TTL` | Refresh token lifetime (seconds) | `604800` (7d) | No |
| `OAUTH_STORAGE_TYPE` | Storage backend | `json` | No |
| `OAUTH_STORAGE_PATH` | Storage path for JSON files | `/app/data` | No |
### JWT Algorithms
Supported algorithms:
- `HS256` (default) - HMAC with SHA-256
- `HS384` - HMAC with SHA-384
- `HS512` - HMAC with SHA-512
- `RS256` - RSA with SHA-256 (requires RSA keys)
- `RS384` - RSA with SHA-384
- `RS512` - RSA with SHA-512
---
## OAuth Flows
### Authorization Code Flow (with PKCE)
**Use Case**: Third-party applications (like OpenAI GPTs)
```
┌──────────┐ ┌──────────────┐
│ Client │ │ MCP Server │
└────┬─────┘ └──────┬───────┘
│ │
│ 1. Generate PKCE verifier & challenge │
│─────────────────────────────────────────────► │
│ │
│ 2. GET /oauth/authorize? │
│ client_id=xxx& │
│ redirect_uri=https://app.com/callback& │
│ response_type=code& │
│ code_challenge=yyy& │
│ code_challenge_method=S256& │
│ scope=read+write& │
│ state=random_state │
│───────────────────────────────────────────────►│
│ │
│ 3. Authorization Code (5-min expiry) │
│◄───────────────────────────────────────────────│
│ │
│ 4. POST /oauth/token │
│ grant_type=authorization_code& │
│ client_id=xxx& │
│ client_secret=zzz& │
│ code=auth_abc& │
│ redirect_uri=https://app.com/callback& │
│ code_verifier=original_verifier │
│───────────────────────────────────────────────►│
│ │
│ 5. Access Token + Refresh Token │
│◄───────────────────────────────────────────────│
│ │
```
### Refresh Token Flow
**Use Case**: Renewing expired access tokens
```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&
client_id=cmp_client_xxx&
client_secret=your_secret&
refresh_token=rt_xxx
```
**Response**:
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "rt_new_token",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read write"
}
```
**Security**: Old refresh token is immediately revoked (rotation).
### Client Credentials Flow
**Use Case**: Machine-to-machine authentication
```
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&
client_id=cmp_client_xxx&
client_secret=your_secret&
scope=read
```
**Response**:
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read"
}
```
**Note**: No refresh token for client credentials.
---
## Registering OAuth Clients
### Two Registration Modes
The `/oauth/register` endpoint supports two authentication modes:
#### 1. Open DCR (No Auth Required) 🆕
For trusted MCP clients (Claude, ChatGPT), registration is automatic:
```bash
# Claude/ChatGPT automatically calls this - no auth needed
curl -X POST https://your-mcp-server.com/oauth/register \
-H "Content-Type: application/json" \
-d '{
"client_name": "Claude MCP Client",
"redirect_uris": ["https://claude.ai/oauth/callback"],
"grant_types": ["authorization_code", "refresh_token"]
}'
```
**Allowed Redirect URI Patterns:**
- `https://claude.ai/*`
- `https://claude.com/*`
- `https://chatgpt.com/*`
- `https://chat.openai.com/*`
- `https://platform.openai.com/*`
- `http://localhost:*/*` (development)
- `http://127.0.0.1:*/*` (development)
**Rate Limits (per IP):**
- 10 requests per minute
- 30 requests per hour
#### 2. Protected DCR (Master API Key Required)
For custom applications with non-allowlisted redirect URIs:
```bash
curl -X POST https://your-mcp-server.com/oauth/register \
-H "Authorization: Bearer YOUR_MASTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_name": "My Custom App",
"redirect_uris": ["https://myapp.com/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"scope": "read write"
}'
```
### Security Flow (MCP Compliant)
```
1. MCP Client (Claude) discovers OAuth via /.well-known/oauth-authorization-server
2. MCP Client registers via Open DCR at /oauth/register (no auth for trusted URIs)
3. MCP Client receives client_id + client_secret
4. User is redirected to /oauth/authorize
5. User enters their API Key → Authorization code returned
6. MCP Client exchanges code for tokens at /oauth/token
7. OAuth token inherits user's API Key permissions
```
**Benefits**:
- ✅ Claude/ChatGPT connect with one click (Open DCR)
- ✅ Custom apps still require admin approval
- ✅ Users control their own permissions via API Keys
- ✅ Rate limiting prevents abuse
**Example**:
- User has "read-only" API Key → OAuth token gets "read-only" access
- User has project-specific API Key → OAuth token limited to that project
- User has Master API Key → OAuth token gets full access
### ChatGPT Integration (OAuth Manual Mode)
ChatGPT now supports **OAuth (manual)** integration where you manually configure the OAuth client credentials.
#### ⚠️ Security Considerations
**Current Limitation**: Due to ChatGPT OAuth (manual) design:
- ChatGPT cannot pass user-specific API Keys in authorization URL
- Must use `OAUTH_AUTH_MODE=optional` which allows anyone with the authorization URL to connect
- OAuth tokens issued to ChatGPT get **full access** (no API Key inheritance)
**Security Measures You Can Take**:
1. **Use Minimal Scopes** (Recommended):
- Register ChatGPT client with `scope: "read"` only
- Create separate clients for different access levels
2. **Private Deployment Only**:
- Only share client credentials with trusted users
- Use this integration for personal/team use, not public GPTs
3. **Monitor Usage**:
- Check audit logs regularly: `tail -f logs/audit.log`
- Review OAuth tokens: use `oauth_list_tokens()` tool
4. **Future Enhancement** (Phase E - Planned):
- 🔒 **Custom Authorization Page** (Priority 2)
- Beautiful HTML form for API Key input
- OAUTH_AUTH_MODE=required works with ChatGPT
- Per-user access control
- Multi-language support (EN/FA)
- See `docs/ROADMAP.md` Phase E for details
- IP whitelisting for OAuth endpoints
- Per-client rate limiting
**For Production/Public Use**: Consider using `OAUTH_AUTH_MODE=required` with a custom client that supports API Key parameters, instead of ChatGPT OAuth (manual).
---
#### Step-by-Step Setup:
**1. Register OAuth Client (Admin Only)**
Use MCP tool or API with Master API Key:
```bash
# Using curl with Master API Key
curl -X POST https://your-mcp-server.com/oauth/register \
-H "Authorization: Bearer YOUR_MASTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_name": "ChatGPT OAuth Integration",
"redirect_uris": ["https://chatgpt.com/connector_platform_oauth_redirect"],
"grant_types": ["authorization_code", "refresh_token"],
"scope": "read"
}'
```
**Response**: Save the `client_id` and `client_secret` (shown only once!)
**2. Configure ChatGPT**
1. Go to ChatGPT → Settings → Authentication
2. Select **OAuth (manual)**
3. Enter:
- **Client ID**: `cmp_client_xxx` (from step 1)
- **Client Secret**: `secret_xxx` (from step 1)
- **Authorization URL**: `https://your-mcp-server.com/oauth/authorize`
- **Token URL**: `https://your-mcp-server.com/oauth/token`
- **Scope**: `read write`
**3. Configure Environment for ChatGPT**
⚠️ **IMPORTANT SECURITY NOTE**: ChatGPT OAuth (manual) has a limitation:
ChatGPT builds the authorization URL automatically and **does not allow users to add API Key parameters**. Therefore, you must use `optional` mode:
```bash
# In .env file
OAUTH_AUTH_MODE=optional
```
**Security Implications**:
- ⚠️ **Anyone with the URL can authorize** - Client ID/Secret alone don't prevent access
- ⚠️ **OAuth tokens get full access** - No API Key = no permission inheritance
- 🔒 **Mitigation**: Use restricted `scope` when registering the client
**Recommended Scopes for ChatGPT**:
- `read` - Read-only access (safest)
- `read write` - Allow content creation (moderate risk)
- ⚠️ Avoid `admin` scope for public ChatGPT integrations
**4. User Authorization**
When users connect ChatGPT to your MCP server:
1. ChatGPT redirects to authorization endpoint automatically
2. Server validates client_id and redirect_uri
3. User approves the connection
4. OAuth token is issued with the scope defined during client registration
5. Redirects back to ChatGPT - Done!
✅ **Best Practice**: Register separate OAuth clients for different use cases with minimal required scopes
### Using MCP Tools
You can also pre-register clients using MCP tools:
```python
# 1. Register a new OAuth client
result = await oauth_register_client(
client_name="My OpenAI GPT",
redirect_uris="https://chat.openai.com/aip/callback",
grant_types="authorization_code,refresh_token",
allowed_scopes="read,write"
)
# Save these credentials securely!
print(f"Client ID: {result['client_id']}")
print(f"Client Secret: {result['client_secret']}") # Only shown once!
```
### Using Direct API (Admin Required)
⚠️ **Master API Key Required** - Only server administrators can register OAuth clients.
```bash
curl -X POST https://mcp-dev.mcphub.dev/oauth/register \
-H "Authorization: Bearer YOUR_MASTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_name": "My Application",
"redirect_uris": ["https://example.com/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"scope": "read write"
}'
```
**Success Response** (201 Created):
```json
{
"client_id": "cmp_client_abc123",
"client_secret": "very_long_secret_string",
"client_id_issued_at": 1234567890,
"client_secret_expires_at": 0,
"client_name": "My Application",
"redirect_uris": ["https://example.com/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"token_endpoint_auth_method": "client_secret_post"
}
```
⚠️ **Important**: Save `client_secret` immediately - it's shown only once!
**Error Response** (401 Unauthorized):
```json
{
"error": "unauthorized",
"error_description": "Master API Key required for OAuth client registration. Add 'Authorization: Bearer YOUR_MASTER_API_KEY' header."
}
```
### List Registered Clients
```python
result = await oauth_list_clients()
for client in result['clients']:
print(f"{client['client_name']}: {client['client_id']}")
```
### Revoke a Client
```python
result = await oauth_revoke_client(
client_id="cmp_client_abc123"
)
```
---
## OpenAI GPT Integration
### Step 1: Register OAuth Client
Use the MCP tool to register:
```python
result = await oauth_register_client(
client_name="OpenAI GPT Integration",
redirect_uris="https://chat.openai.com/aip/callback,https://chatgpt.com/aip/callback",
allowed_scopes="read,write"
)
# Save these!
# Client ID: cmp_client_abc123
# Client Secret: very_long_secret_string
```
### Step 2: Configure GPT Action
In OpenAI GPT editor, add an Action with:
**Authentication Type**: OAuth
**Client ID**: `cmp_client_abc123`
**Client Secret**: `very_long_secret_string`
**Authorization URL**: `https://your-mcp-server.com/oauth/authorize`
**Token URL**: `https://your-mcp-server.com/oauth/token`
**Scope**: `read write`
**Token Exchange Method**: `POST` with Basic auth
### Step 3: Test Integration
1. In GPT conversation, trigger an action
2. OAuth consent flow will start
3. User approves (or auto-approved in MCP context)
4. GPT receives access token
5. GPT can now call MCP tools via OAuth!
---
## Claude Custom Connectors (Remote MCP)
Claude supports **Custom Connectors** for Remote MCP servers, allowing direct integration without SSH tunnels or local setup.
### Requirements
- **Claude Plan**: Pro, Max, Team, or Enterprise
- **MCP Server**: Publicly accessible with HTTPS
- **OAuth**: Automatically handled via Open DCR 🆕
### Step 1: Add Connector in Claude
1. Open Claude (claude.ai or desktop app)
2. Go to **Settings** → **Connectors** (or **Integrations**)
3. Click **Add custom connector**
4. Enter your MCP server URL:
- Full access: `https://your-mcp-server.com/mcp`
- Per-project: `https://your-mcp-server.com/project/{alias}/mcp`
5. Click **Add connector** or **Connect**
### Step 2: Authorize (Automatic Flow) 🆕
Thanks to **Open DCR** and **MCP OAuth Compliance**, the OAuth flow is now automatic:
1. Claude discovers OAuth metadata at `/.well-known/oauth-authorization-server`
2. Claude automatically registers via Open DCR at `/oauth/register`
3. Claude redirects you to the authorization page
4. Enter your API Key
5. Done! Claude now has access to your MCP tools
**No manual client registration required!**
### Alternative: Manual Registration (Optional)
If you prefer to pre-register the OAuth client:
```bash
curl -X POST https://your-mcp-server.com/oauth/register \
-H "Content-Type: application/json" \
-d '{
"client_name": "Claude Custom Connector",
"redirect_uris": ["https://claude.ai/oauth/callback"],
"grant_types": ["authorization_code", "refresh_token"],
"scope": "read write"
}'
```
Note: Authorization header is optional for Claude's redirect URIs (Open DCR).
### Security Considerations
⚠️ **Important Security Notes**:
- **Only add trusted connectors** - Remote MCP servers have access to your Claude conversations
- **Use minimal scopes** - Register clients with only required permissions (`read` for safe exploration)
- **Disable write-actions** for Research feature if using with sensitive data
- **Monitor usage** via audit logs: `get_audit_log` tool
### Recommended Configuration
For **safe exploration** (read-only):
```bash
curl -X POST https://your-mcp-server.com/oauth/register \
-H "Authorization: Bearer YOUR_MASTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_name": "Claude (Read-Only)",
"redirect_uris": ["https://claude.ai/api/mcp/auth_callback", "https://claude.com/api/mcp/auth_callback"],
"scope": "read"
}'
```
For **full access** (trusted environments):
```bash
curl -X POST https://your-mcp-server.com/oauth/register \
-H "Authorization: Bearer YOUR_MASTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_name": "Claude (Full Access)",
"redirect_uris": ["https://claude.ai/api/mcp/auth_callback", "https://claude.com/api/mcp/auth_callback"],
"scope": "read write admin"
}'
```
### Using Per-Project Endpoints
For better security isolation, connect Claude to project-specific endpoints:
```
https://your-mcp-server.com/project/{alias}/mcp
```
This restricts Claude to tools for that specific project only.
### Troubleshooting Claude Connectors
#### "Configure" button instead of "Connect"
This was fixed in Phase K.1. If you still see this:
- Ensure server is updated to v2.10.0+
- Check that `OAuthRequiredMiddleware` is active
- Verify `/.well-known/oauth-protected-resource` returns 200
#### "Connection failed" or "Error connecting to server"
1. **Check server accessibility**: `curl https://your-server.com/health`
2. **Check OAuth metadata**: `curl https://your-server.com/.well-known/oauth-authorization-server`
3. **Check path-specific metadata**: `curl https://your-server.com/.well-known/oauth-protected-resource/mcp`
4. **Check logs** for errors:
```bash
docker logs your-container | grep -i oauth
```
#### "Unauthorized" during authorization
- Enter a valid API Key on the authorization page
- Check that your API Key has the required scope
#### DCR Rate Limited
If you see rate limit errors:
- Wait 1 minute (per-minute limit: 10)
- Or wait 1 hour (per-hour limit: 30)
- Configure limits: `DCR_RATE_LIMIT_PER_MINUTE` and `DCR_RATE_LIMIT_PER_HOUR`
#### Tools not appearing
- Check endpoint path (should include `/mcp`)
- Verify OAuth scopes match tool requirements
- Review server logs for errors
---
## Testing
### Manual Testing
#### 1. Test Authorization Endpoint
```bash
# Generate PKCE challenge
python -c "
import secrets, hashlib, base64
verifier = secrets.token_urlsafe(64)[:64]
challenge = base64.urlsafe_b64encode(
hashlib.sha256(verifier.encode()).digest()
).decode().rstrip('=')
print(f'Verifier: {verifier}')
print(f'Challenge: {challenge}')
"
# Call authorization endpoint
curl -X GET "http://localhost:8000/oauth/authorize?\
client_id=cmp_client_xxx&\
redirect_uri=http://localhost:3000/callback&\
response_type=code&\
code_challenge=YOUR_CHALLENGE&\
code_challenge_method=S256&\
scope=read+write"
```
#### 2. Test Token Endpoint
```bash
# Exchange authorization code for tokens
curl -X POST http://localhost:8000/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&\
client_id=cmp_client_xxx&\
client_secret=YOUR_SECRET&\
code=auth_abc123&\
redirect_uri=http://localhost:3000/callback&\
code_verifier=YOUR_VERIFIER"
```
#### 3. Test Access Token
```bash
# Use access token to call MCP tools
curl -X POST http://localhost:8000/tools/wordpress_post_list \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"site": "site1", "status": "publish"}'
```
### Automated Testing
```bash
# Run integration tests
pytest tests/test_oauth_integration.py -v
# Run all OAuth tests
pytest tests/test_oauth*.py -v
```
---
## Security Best Practices
### 1. JWT Secret Key Management
✅ **DO**:
- Use cryptographically secure random keys (64+ characters)
- Store in environment variables, never in code
- Rotate keys periodically
- Use different keys for dev/staging/production
❌ **DON'T**:
- Use weak or predictable secrets
- Commit secrets to version control
- Share secrets between environments
### 2. Client Secrets
✅ **DO**:
- Save client secrets immediately after creation
- Store securely (password manager, secrets vault)
- Rotate if compromised
❌ **DON'T**:
- Log client secrets
- Expose in error messages
- Transmit over insecure channels
### 3. PKCE
✅ **DO**:
- Always use S256 method
- Generate new verifier for each flow
- Validate code_challenge correctly
❌ **DON'T**:
- Reuse code verifiers
- Use plain method (OAuth 2.1 disallows it)
### 4. Token Handling
✅ **DO**:
- Use short-lived access tokens (1 hour)
- Implement refresh token rotation
- Detect and prevent token reuse
- Validate JWT signatures
❌ **DON'T**:
- Store tokens in localStorage (XSS risk)
- Log tokens in production
- Ignore token expiration
### 5. Scope Management
✅ **DO**:
- Grant minimum necessary scopes
- Validate scopes on every request
- Document scope requirements
❌ **DON'T**:
- Grant "admin" scope by default
- Allow scope escalation
---
## Troubleshooting
### ChatGPT OAuth (Manual) Issues
#### 1. "Something went wrong with setting up the connection"
**Common Causes**:
- Wrong redirect URI
- OAUTH_AUTH_MODE is set to `required` (should be `optional` for ChatGPT)
- Client ID/Secret mismatch
**Solution**:
```bash
# 1. Check redirect URI in oauth_clients.json
cat /app/data/oauth_clients.json | grep -A 3 redirect_uris
# Should contain: "https://chatgpt.com/connector_platform_oauth_redirect"
# 2. Verify OAUTH_AUTH_MODE
echo $OAUTH_AUTH_MODE
# Should be: optional
# 3. Check logs for specific error
tail -f logs/audit.log | grep -i oauth
```
#### 2. "API Key is required" error during authorization
**Cause**: `OAUTH_AUTH_MODE=required` but ChatGPT cannot pass API Key
**Solution**:
```bash
# In .env file, change to:
OAUTH_AUTH_MODE=optional
# Then restart/redeploy
```
#### 3. "Invalid redirect_uri" error
**Cause**: Redirect URI mismatch between client registration and ChatGPT request
**Solution**:
```bash
# Register new client with correct URI
curl -X POST https://your-server.com/oauth/register \
-H "Authorization: Bearer YOUR_MASTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_name": "ChatGPT OAuth",
"redirect_uris": ["https://chatgpt.com/connector_platform_oauth_redirect"],
"grant_types": ["authorization_code", "refresh_token"],
"scope": "read"
}'
# Update ChatGPT config with new client_id and client_secret
```
#### 4. ChatGPT connection works but has too much access
**Cause**: OAuth client registered with broad scopes (e.g., "read write admin")
**Solution**:
```bash
# Revoke old client
curl -X POST https://your-server.com/tools/oauth_revoke_client \
-H "Authorization: Bearer YOUR_MASTER_API_KEY" \
-d '{"client_id": "cmp_client_old"}'
# Register new client with minimal scope
curl -X POST https://your-server.com/oauth/register \
-H "Authorization: Bearer YOUR_MASTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client_name": "ChatGPT (Read-Only)",
"redirect_uris": ["https://chatgpt.com/connector_platform_oauth_redirect"],
"scope": "read"
}'
```
---
### Common Issues
#### 1. "Invalid client credentials"
**Cause**: Wrong client_id or client_secret
**Solution**:
```bash
# List registered clients
curl -H "Authorization: Bearer $MASTER_API_KEY" \
http://localhost:8000/tools/oauth_list_clients
# Verify credentials match
```
#### 2. "PKCE validation failed"
**Cause**: Mismatch between code_verifier and code_challenge
**Solution**:
- Ensure code_verifier used in token request matches the original
- Verify code_challenge was generated correctly with S256
#### 3. "Token expired"
**Cause**: Access token expired (default 1 hour)
**Solution**:
```bash
# Use refresh token to get new access token
curl -X POST http://localhost:8000/oauth/token \
-d "grant_type=refresh_token&\
client_id=xxx&\
client_secret=yyy&\
refresh_token=rt_zzz"
```
#### 4. "Insufficient scope"
**Cause**: Access token doesn't have required scope
**Solution**:
- Request correct scopes during authorization
- Check allowed_scopes for the client
- Ensure scope is included in JWT payload
#### 5. "Authorization code already used"
**Cause**: Attempting to reuse authorization code
**Solution**:
- Authorization codes are single-use only
- Start a new authorization flow
- Check for client-side caching issues
### Debug Logging
Enable debug logging:
```bash
# .env
LOG_LEVEL=DEBUG
```
View logs:
```bash
docker-compose logs -f mcp-server | grep -i oauth
```
---
## API Reference
### Endpoints
#### GET /oauth/authorize
Authorization endpoint for OAuth flow.
**Query Parameters**:
- `client_id` (required) - OAuth client ID
- `redirect_uri` (required) - Callback URI
- `response_type` (required) - Must be "code"
- `code_challenge` (required) - PKCE challenge
- `code_challenge_method` (required) - Must be "S256"
- `scope` (optional) - Requested scopes (space-separated)
- `state` (optional) - CSRF protection token
**Response**:
```json
{
"redirect_uri": "http://localhost:3000/callback?code=auth_xxx&state=yyy",
"code": "auth_xxx",
"expires_in": 300
}
```
#### POST /oauth/token
Token endpoint for all OAuth grants.
**Request Body** (application/x-www-form-urlencoded or JSON):
- `grant_type` (required) - "authorization_code" | "refresh_token" | "client_credentials"
- `client_id` (required) - OAuth client ID
- `client_secret` (required) - Client secret
For authorization_code:
- `code` (required) - Authorization code
- `redirect_uri` (required) - Same as /authorize
- `code_verifier` (required) - PKCE verifier
For refresh_token:
- `refresh_token` (required) - Current refresh token
For client_credentials:
- `scope` (optional) - Requested scopes
**Response**:
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "rt_xxx",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read write"
}
```
### MCP Tools
#### oauth_register_client
Register a new OAuth client.
#### oauth_list_clients
List all registered OAuth clients.
#### oauth_revoke_client
Revoke (delete) an OAuth client.
---
## Resources
- [OAuth 2.1 Specification](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-10)
- [RFC 7636 - PKCE](https://datatracker.ietf.org/doc/html/rfc7636)
- [JWT Best Practices](https://datatracker.ietf.org/doc/html/rfc8725)
- [OpenAI Actions Documentation](https://platform.openai.com/docs/actions)
---
## Support
For issues or questions:
- GitHub Issues: https://github.com/airano-ir/mcphub/issues
- Documentation: `/docs`
---
**Last Updated**: 2025-12-05
**Version**: v2.10.0 (Phase K.1 - OAuth MCP Compliance, Open DCR, RFC 9728)
