mcp-auth-bridge
leonard-cs/mcp-auth-bridge
A FastMCP proxy that wraps a header-auth-only remote MCP server, exposing it via OAuth or no-auth for clients that don't support header authentication.
Instalação
npx convez-ai leonard-cs/mcp-auth-bridge1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
mcp-auth-bridge
A FastMCP proxy that wraps any MCP server — remote (header-auth or none) or local stdio — and re-exposes it over HTTP with header-auth, OAuth, or no-auth. It bridges servers to clients whose auth or transport support differs, and can fan several upstream servers into one endpoint.
MCP client ──HTTP (none | header | oauth)──▶ mcp-auth-bridge ──▶ upstream MCP server(s)
(stdio or remote, from .mcp.json)
Features
- Three bridge auth modes:
none,header(static bearer token),oauth. - OAuth, two ways: a local in-memory server for testing, or a generic remote verifier that works with any DCR-capable OIDC provider (WorkOS AuthKit, Descope, Keycloak, …).
- Upstream from
.mcp.json: the standardmcpServersschema (stdio or remote). Multiple servers are merged into one prefixed tool list. - Configured via
.env— switch modes without touching code.
Quickstart
# 1. Install
uv sync
# 2. Configure the upstream server(s) you want to bridge
cp .mcp.json.example .mcp.json # then edit: command/args/env or url/headers
# 3. Configure the bridge
cp .env.example .env # then edit: AUTH_MODE, etc.
# 4. Run
uv run -m mcp_auth_bridge # serves http://localhost:8000/mcp
Test it with the MCP Inspector:
npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP URL: http://localhost:8000/mcp
Configuration
All settings come from environment / .env (see .env.example):
| Variable | Default | Purpose |
|---|---|---|
AUTH_MODE | none | none | header | oauth |
HOST | 0.0.0.0 | bind host |
PORT | 8000 | bind port |
MCP_CONFIG | .mcp.json | upstream definition (mcpServers schema) |
OAUTH_PROVIDER | memory | memory (local test) | remote (real IdP) |
BRIDGE_PUBLIC_URL | http://localhost:8000 | public URL advertised in OAuth metadata |
OAUTH_ISSUER | — | OIDC issuer (remote) |
OAUTH_JWKS_URI | — | JWKS endpoint (remote) |
OAUTH_AUTH_SERVER | = issuer | authorization server to advertise |
OAUTH_AUDIENCE | — | expected token audience (blank = skip) |
OAUTH_ALGORITHM | RS256 | JWT signing algorithm |
Auth modes
none
No authentication — the bridge is an open proxy. Useful for local development.
header
Clients must send Authorization: Bearer <token>. The accepted token(s) are
defined in src/mcp_auth_bridge/auth/header.py (BRIDGE_TOKENS). Replace the
sample token before any real use.
oauth
Full OAuth 2.1. Selected sub-mode via OAUTH_PROVIDER:
memory— the bridge is its own in-memory OAuth server (DCR, authorize, token exchange, auto-approved). No external account; works onlocalhost. Testing/dev only.remote— the bridge verifies JWTs from a real external IdP and advertises it to clients. Provider-agnostic; configure viaOAUTH_*.
To set up oauth + remote with WorkOS AuthKit (incl. the ngrok tunnel and how
to register / refresh the public URL), see
docs/authkit-ngrok-setup.md.
Project layout
src/mcp_auth_bridge/
__main__.py # entrypoint: reads host/port, runs the proxy
server.py # build_server(): load upstream + auth, create proxy
config.py # Settings (pydantic-settings), loads .env
upstream.py # load_upstream_config(): reads .mcp.json
auth/
__init__.py # build_auth_provider(settings): dispatch on AUTH_MODE
none.py # no auth
header.py # static bearer token (StaticTokenVerifier)
oauth.py # in-memory + generic remote OAuth