This project is a work in progress and should not be considered production ready. Though I'm fairly confident the overall architecture is sound, and I myself rely on the implementation — so it should work ™️. But it's definitely alpha software :)
Also, don't rely too much on the docs, they drift fairly quickly, I do not always keep them updated when doing changes or adding/removing features. They are mostly here to anchor me and help me stay focus on my initial vision.
OAuth 2.1 proxy for MCP (Model Context Protocol) servers. Authenticate once with Google, access all your MCP tools in Claude.ai.
mcp-front is an authentication proxy that sits between Claude.ai and your MCP servers. It provides:
- Single sign-on via Google OAuth for all MCP tools
- Domain validation to restrict access to your organization
- Per-user tokens for services like Notion
- Session isolation so multiple users can share infrastructure
Without mcp-front, each MCP server needs its own authentication, which isn't trivial — or need to be public.
With mcp-front:
- Users authenticate once with their Google account
- Access is restricted to your company domain
- MCP servers can run in secure environments (databases, internal APIs)
- Sessions are isolated between users
- You get a simple, unified setup to run pretty much any MCP server found on Docker Hub
- Claude.ai connects to
https://your-domain.com/<service>/sse - mcp-front validates the user's OAuth token
- If the server needs a user token, prompts via
/my/tokens - Proxies requests to the configured MCP server
- For stdio servers, each user gets an isolated process
- Create
config.json:
{
"version": "v0.0.1-DEV_EDITION_EXPECT_CHANGES",
"proxy": {
"baseURL": "https://mcp.yourcompany.com",
"addr": ":8080",
"auth": {
"kind": "oauth",
"issuer": "https://mcp.yourcompany.com",
"allowedDomains": ["yourcompany.com"],
"allowedOrigins": ["https://claude.ai"],
"tokenTtl": "1h",
"storage": "memory",
"googleClientId": { "$env": "GOOGLE_CLIENT_ID" },
"googleClientSecret": { "$env": "GOOGLE_CLIENT_SECRET" },
"googleRedirectUri": "https://mcp.yourcompany.com/oauth/callback",
"jwtSecret": { "$env": "JWT_SECRET" },
"encryptionKey": { "$env": "ENCRYPTION_KEY" }
}
},
"mcpServers": {
"postgres": {
"transportType": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"mcp/postgres:latest",
{ "$env": "DATABASE_URL" }
]
}
}
}- Set environment variables:
export GOOGLE_CLIENT_ID="your-oauth-client-id"
export GOOGLE_CLIENT_SECRET="your-oauth-client-secret"
export JWT_SECRET="your-32-byte-jwt-secret-for-oauth!"
export ENCRYPTION_KEY="your-32-byte-encryption-key-here!"
export DATABASE_URL="postgresql://user:pass@host:5432/db"- Run mcp-front:
docker run -d -p 8080:8080 \
-e GOOGLE_CLIENT_ID -e GOOGLE_CLIENT_SECRET \
-e JWT_SECRET -e ENCRYPTION_KEY -e DATABASE_URL \
-v /var/run/docker.sock:/var/run/docker.sock \
-v $(pwd)/config.json:/app/config.json \
dgellow/mcp-front:docker-client-latest- Add to Claude.ai:
https://mcp.yourcompany.com/postgres/sse
/<service>/sse- Server-sent events for MCP communication/<service>/message- Message handling for MCP requests
/my/tokens- Browser-based token management for per-user MCP server tokens
/.well-known/oauth-authorization-server- OAuth discovery/authorize- OAuth authorization/token- Token exchange/oauth/callback- Google OAuth callback/register- Dynamic client registration
- Create OAuth client in Google Cloud Console
- Set redirect URI:
https://your-domain.com/oauth/callback - Save Client ID and Secret
mcp-front uses explicit JSON syntax {"$env": "VAR_NAME"} for environment variables throughout its configuration. This deliberate choice eliminates the ambiguity and risks inherent in shell-style variable substitution. When configs pass through multiple layers of tooling and scripts, traditional $VAR syntax can expand unexpectedly, causing security issues and debugging nightmares. The JSON format ensures your configuration remains exactly as written until mcp-front processes it, providing predictable behavior across all deployment environments. For per-user authentication, {"$userToken": "{{token}}"} follows the same principle, keeping user credentials cleanly separated from system configuration.
Some MCP servers are better to use with each users having their own integration token (e.g., Notion). Configure with:
{
"notion": {
"transportType": "stdio",
"requiresUserToken": true,
"tokenSetup": {
"displayName": "Notion Integration Token",
"instructions": "Create an integration and copy the token",
"helpUrl": "https://www.notion.so/my-integrations"
},
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "OPENAPI_MCP_HEADERS", "mcp/notion:latest"],
"env": {
"OPENAPI_MCP_HEADERS": {
"$userToken": "{\"Authorization\": \"Bearer {{token}}\"}"
}
}
}
}After the initial OAuth authentication, when users try to use Claude.ai with the integration they will be prompted to
provide a token via the /my/tokens web UI.
See config-oauth.json for a complete example with multiple MCP servers.
- OAuth 2.1 with PKCE required for all flows
- Google Workspace domain validation
- Encrypted session cookies (AES-256-GCM)
- Per-user session isolation for stdio servers
- Memory (default): Fast, data lost on restart
- Firestore: Persistent storage for production
For Firestore, add to your auth config:
"storage": "firestore",
"gcpProject": {"$env": "GCP_PROJECT"},
"firestoreDatabase": "(default)",
"firestoreCollection": "mcp_front_oauth_clients"# Run tests
cd integration && go test -v
# Development mode (relaxed OAuth validation)
export MCP_FRONT_ENV=developmentCopyright 2025 Samuel "dgellow" El-Borai