MCP Server with HTTP Transport
A Python MCP (Model Context Protocol) server that supports both stdio and HTTP/SSE transports with optional OAuth2 authentication.
Features
- Dual transport support: stdio and HTTP with Server-Sent Events (SSE)
- Optional OAuth2 authentication with two modes:
- Built-in OAuth: Server issues its own tokens (demo/development)
- External OIDC: Validates tokens via introspection endpoint (production)
- Two tools:
list_profilesandget_titans - Demo data with Attack on Titan characters
- JSON-formatted responses
- Environment-based configuration
Installation```bash
pip install -r requirements.txt
## Quick Start
### Option 1: Without OAuth (Simple)```bash
python server.py
Configure in ChatGPT:```json
{
"name": "Demo MCP Server",
"url": "http://127.0.0.1:8000/sse"
}
### Option 2: With Built-in OAuth (Demo/Development)
1. Generate OAuth2 credentials:```bash
python generate_credentials.py
- Start the server:```bash
python server.py
3. Configure in ChatGPT with OAuth2 settings (see Configuration section below)
### Option 3: With External OIDC Provider (Production)
1. Configure external OIDC provider (Keycloak, Auth0, Okta, etc.)
2. Create `.env` file:```bash
OAUTH_ENABLED=true
OAUTH_MODE=external
OIDC_INTROSPECTION_ENDPOINT=https://auth.example.com/oauth/introspect
OIDC_CLIENT_ID=mcp-server-client-id
OIDC_CLIENT_SECRET=mcp-server-client-secret
- Start the server:```bash
python server.py
4. Configure ChatGPT to point to your external OIDC provider
## Usage
### HTTP/SSE Transport (default)
Run the server with HTTP transport:```bash
python server.py
# Or explicitly:
python server.py --transport sse --host 127.0.0.1 --port 8000
The server will be available at:
- SSE endpoint: http://127.0.0.1:8000/sse
- Messages endpoint: http://127.0.0.1:8000/messages/
Stdio Transport
Run the server with stdio transport:```bash
python server.py --transport stdio
## Configuration
### OAuth Modes
The server supports two OAuth modes:
| Mode | Description | Use Case |
|------|-------------|----------|
| `builtin` | Server issues its own tokens | Demo, development, small deployments |
| `external` | Validates tokens via introspection | Production, enterprise, SSO |
### Mode 1: Built-in OAuth (Default)
For demo and development purposes. The server handles the complete OAuth flow.```bash
# .env file
OAUTH_ENABLED=true
OAUTH_MODE=builtin
OAUTH_CLIENT_ID=chatgpt-mcp-xxxxxxxxxxxx
OAUTH_CLIENT_SECRET=your-secret-here
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
USE_HTTPS=false
Generate credentials automatically:```bash
python generate_credentials.py
**ChatGPT Configuration:**```json
{
"name": "Demo MCP Server",
"url": "http://127.0.0.1:8000/sse",
"description": "Demo server with built-in OAuth",
"auth": {
"type": "oauth2",
"authorization_url": "http://127.0.0.1:8000/oauth/authorize",
"token_url": "http://127.0.0.1:8000/oauth/token",
"client_id": "chatgpt-mcp-xxxxxxxxxxxx",
"client_secret": "your-secret-here",
"scope": "read write"
}
}
Mode 2: External OIDC Provider (Token Introspection)
For production deployments. The server validates tokens from your external OIDC provider using the token introspection endpoint.```bash
.env file
OAUTH_ENABLED=true
OAUTH_MODE=external
Token Introspection Configuration
OIDC_INTROSPECTION_ENDPOINT=https://auth.example.com/oauth/introspect
OIDC_CLIENT_ID=mcp-server-client-id
OIDC_CLIENT_SECRET=mcp-server-client-secret
Server Configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
**ChatGPT Configuration:**```json
{
"name": "Demo MCP Server",
"url": "http://127.0.0.1:8000/sse",
"description": "MCP server with external OIDC",
"auth": {
"type": "oauth2",
"authorization_url": "https://auth.example.com/oauth/authorize",
"token_url": "https://auth.example.com/oauth/token",
"client_id": "chatgpt-client-id",
"client_secret": "chatgpt-client-secret",
"scope": "openid profile read write"
}
}
Note: OAuth URLs point to your external provider, not the MCP server!
Provider-Specific Examples
Keycloak```bash
OAUTH_MODE=external
OIDC_INTROSPECTION_ENDPOINT=https://keycloak.example.com/realms/myrealm/protocol/openid-connect/token/introspect
OIDC_CLIENT_ID=mcp-server
OIDC_CLIENT_SECRET=your-secret-here
#### Auth0```bash
OAUTH_MODE=external
OIDC_INTROSPECTION_ENDPOINT=https://yourtenant.auth0.com/oauth/introspect
OIDC_CLIENT_ID=mcp-server-client-id
OIDC_CLIENT_SECRET=your-secret-here
Okta```bash
OAUTH_MODE=external
OIDC_INTROSPECTION_ENDPOINT=https://yourorg.okta.com/oauth2/default/v1/introspect
OIDC_CLIENT_ID=mcp-server-client-id
OIDC_CLIENT_SECRET=your-secret-here
### For Claude Desktop (HTTP/SSE)
In `claude_desktop_config.json`:```json
{
"mcpServers": {
"demo-mcp-server": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
For Claude Desktop (Stdio)```json
{
"mcpServers": {
"demo-mcp-server": {
"command": "python",
"args": ["/path/to/server.py", "--transport", "stdio"]
}
}
}
## Available Tools
### list_profiles
Lists all available profiles on the server.
**Parameters:** None
**Returns:** JSON array of profile objects with `profile_id` and `name` fields
**Example response:**```json
[
{
"profile_id": "eren",
"name": "Eren Yeager"
},
{
"profile_id": "mikasa",
"name": "Mikasa Ackerman"
}
]
get_titans
Gets titans for a specific profile.
Parameters:
- profile_id (string, required): The profile ID to get titans for
Returns: JSON object with titans for the specified profile
Example success response:```json
{
"profile_id": "eren",
"titans": [
"founding",
"war hammer"
],
"status": "success"
}
**Example error response:**```json
{
"profile_id": "unknown",
"status": "error",
"error": "Profile not found"
}
Demo Data
The server includes demo data with Attack on Titan characters:
- eren - Eren Yeager (founding and war hammer titans)
- mikasa - Mikasa Ackerman (attack titan)
Testing
Test Token Introspection
Use the included test script to validate your OIDC configuration:```bash
Test introspection endpoint
python test_oidc_token.py introspect --token "your-token-here" \
--introspection-url https://auth.example.com/oauth/introspect \
--client-id mcp-server --client-secret secret
Test token with MCP server
python test_oidc_token.py test --token "your-token-here" --server http://127.0.0.1:8000
Test OIDC discovery
python test_oidc_token.py discover --issuer https://auth.example.com
## Customization
Replace the demo data and logic in `server.py`:
1. **`DATA` dictionary** - Replace with your actual data source (database, file, API)
2. **`list_profiles()`** - Modify to return your profile format
3. **`get_titans(profile_id)`** - Modify to return your data format
## Troubleshooting
### Server not connecting
- Check server is running: `curl http://127.0.0.1:8000/sse`
- Verify URL is exactly `http://127.0.0.1:8000/sse`
- Check firewall allows port 8000
### Tools don't appear
- Check server logs for errors
- Tools should work even if not visible in UI
- Try asking directly: "list profiles" or "get titans for eren"
### OAuth/OIDC Issues
#### "Token introspection request timed out"
- Check introspection endpoint URL
- Verify network connectivity
- Check client credentials are correct
#### "Token is not active"
- Token may be expired
- Token may have been revoked
- Check token was issued by the correct provider
#### Authentication failing
- Verify `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET` are correct
- Check the introspection endpoint supports basic auth
- Verify your MCP server client has introspection permissions
## OAuth2 Details
### Built-in OAuth Mode
**How it works:**
1. ChatGPT redirects user to `/oauth/authorize`
2. Server auto-approves (demo mode) and returns authorization code
3. ChatGPT exchanges code for access token at `/oauth/token`
4. ChatGPT includes `Bearer {token}` in all MCP requests
5. Server validates token against in-memory storage
**Security Notes:**
- ⚠️ Auto-approval is for demo only - implement proper login/consent in production
- ⚠️ Tokens stored in memory - use database for production
- ⚠️ Use HTTPS for production - set `USE_HTTPS=true` when behind HTTPS proxy/load balancer
- ✓ Client secret is stored in `.env` (not committed to git)
### External OIDC Mode (Token Introspection)
**How it works:**
1. ChatGPT redirects user to external OIDC provider's authorization endpoint
2. User logs in at OIDC provider (supports SSO, MFA, etc.)
3. OIDC provider returns authorization code to ChatGPT
4. ChatGPT exchanges code for access token at OIDC provider
5. ChatGPT includes `Bearer {token}` in all MCP requests to your server
6. Your server validates token via introspection endpoint
**Why Token Introspection:**
- ✅ Works with any token format (JWT or opaque)
- ✅ Real-time token status (can detect revoked tokens immediately)
- ✅ Simpler configuration (no JWKS, audience, or issuer validation)
- ✅ Supports enterprise SSO and MFA (via provider)
- ⚠️ Network call per validation (slightly higher latency than JWT)
- ⚠️ Requires introspection endpoint access
**Security Notes:**
- ✅ Stateless (scales horizontally)
- ✅ Centralized user management
- ✅ Real-time token revocation
- ✅ Works with any OIDC provider
- ⚠️ Use HTTPS for production
**To disable OAuth:**```bash
# In .env file
OAUTH_ENABLED=false
Or simply don't create a .env file.
Comparison: Built-in vs External OIDC
| Feature | Built-in OAuth | External OIDC (Introspection) |
|---|---|---|
| Use Case | Demo/Development | Production/Enterprise |
| Token Issuer | MCP Server | External Provider |
| User Auth | Auto-approve (demo) | Full login via provider |
| Token Format | Opaque | Any (JWT or opaque) |
| SSO | ❌ No | ✅ Yes |
| MFA | ❌ No | ✅ Yes (via provider) |
| Token Revocation | Manual | Real-time |
| Scalability | Limited (in-memory) | Excellent (stateless) |
| Setup Complexity | ⭐ Simple | ⭐⭐ Moderate |
| Latency | ~0.1ms | ~50-100ms |
Files
server.py- Main MCP server with OAuth support (both modes)generate_credentials.py- OAuth2 credential generator (built-in mode)test_oidc_token.py- OIDC token validation testing toolconfig.py- Configuration defaultsrequirements.txt- Python dependencies.env.example- Example environment configuration (built-in mode).env.external_oidc.example- Example environment configuration (external OIDC)README.md- This file
