mcp-auth-proxy
OAuth 2.1 authorization server that fronts any OIDC IdP, so MCP clients can speak to your private MCP server without you writing a single line of auth code.
Power your agent
การติดตั้งจากผู้เผยแพร่ ไม่ใช่เอนด์พอยต์ของ PlugMCP
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
┌──────────────────┐ ┌────────────────────┐ ┌─────────────────┐
│ Claude / Cursor │ ───► │ mcp-auth-proxy │ ───► │ private MCP │
│ Claude Code │ │ OAuth 2.1 AS │ │ server │
│ MCP Inspector │ ◄─── │ (this project) │ ◄─── │ (unchanged) │
└──────────────────┘ └────────┬───────────┘ └─────────────────┘
│
▼
┌────────────────────┐
│ your OIDC IdP │
│ Keycloak · Entra │
│ Auth0 · Okta · … │
└────────────────────┘
docker run --rm -p 8080:8080 \
-e OIDC_ISSUER_URL=https://idp.example.com \
-e OIDC_CLIENT_ID=mcp-auth-proxy \
-e OIDC_CLIENT_SECRET='<your-idp-secret>' \
-e PROXY_BASE_URL=https://mcp.example.com \
-e UPSTREAM_MCP_URL=http://mcp-backend:8000/mcp \
-e TOKEN_SIGNING_SECRET="$(openssl rand -hex 32)" \
-e REDIS_URL=redis://your-redis-host:6379/0 \
ghcr.io/babs/mcp-auth-proxy:latest
Substitute the angle-bracketed placeholder with your real IdP
credential and pick a Redis URL that's reachable from the container
(host networking, an explicit --network, or the demo stack below
all work). Point your MCP client at https://mcp.example.com/mcp
and the proxy walks RFC 7591 → 8414 → 6749 → 8707 → OIDC → your
protected backend on its own.
For a full local stack with Keycloak + Redis + a sample MCP server already wired up, see Demo stack.
/.well-known/openid-configuration)
reachable from the proxy. Tested with Keycloak, Microsoft Entra ID;
any OIDC-compliant IdP works (Auth0, Okta, Google, …).REDIS_REQUIRED=true) so single-use authorization codes and
refresh-rotation reuse detection work across replicas. See
docs/redis-production.md for sizing.LISTEN_ADDR (:8080 by default). The IdP and the MCP clients both
see PROXY_BASE_URL over the public network.go.mod) if building from source. Container images are static
(CGO_ENABLED=0).manifests/. Production overlay enforces the safe
posture; see Deploying.UPSTREAM_FORWARD_IDP_TOKEN,
off by default) for MCP servers that call other APIs as the user
(e.g. on-behalf-of): the user's IdP access token reaches the upstream
as Authorization: Bearer, renewed at the IdP on every refresh, while
the IdP tokens stay sealed inside the proxy's own tokens. See
specs.md.RATE_LIMIT_ENABLED=true; =false fails startup under PROD_MODE) on every pre-auth endpoint, per-subject
concurrency caps on the authenticated route, email_verified
enforcement on the IdP id_token, Prometheus metrics for every
security-relevant event, and a proxy-rendered consent page on
by default./authorize, /consent and
/callback end up in the user's browser, so a request that asks for
text/html gets the failure (wrong group, unverified email, expired
session, throttled — the throttle page needs a real browser
navigation, Sec-Fetch-Dest: document) as a plain page carrying a
support code and advice matched to the failure, instead of a raw JSON
blob — the support-code vocabulary is catalogued in the
error-code table. Every
programmatic caller keeps the RFC 6749 JSON body unchanged, and
/token / /register stay JSON whatever they ask for. Failures that
happen once a redirect_uri is validated still go back to the client
as an RFC 6749 §4.1.2.1 error envelope — a redirect from /authorize
and /callback, a same-origin interstitial from /consent — never
the error page, except the invariant-violation fallback when that
already-validated URI fails to re-parse.The MCP spec requires an OAuth 2.1 Authorization Server in front of protected MCP servers. You probably do not want to implement RFC 8414 / 7591 / 9728 / 7636 / 8707 yourself, glue a session store in front of every replica, or rewrite your MCP backend to understand OIDC. Drop this in front, point it at your existing IdP, done.
Companion docs:
specs.md — design + flow rationale.docs/conformance.md — claim matrix +
compatibility notes + IdP evidence.docs/threat-model.md — STRIDE coverage
with code + test + runbook links.docs/configuration.md — full env-var
reference with rationale per knob.All configuration via environment variables. The five required vars are below; everything else is optional and defaults to the safe production posture.
Optional knobs (rate limits, replay store tuning, header trust,
observability, dev/compat) are documented in
docs/configuration.md.
PROD_MODE=true by default — the proxy fails startup if any
compatibility flag that weakens a security control is set. The
shipped defaults give you, with no extra effort:
REDIS_REQUIRED=true blocks startup without
REDIS_URL. Stateless mode (codes/refresh replayable within TTL)
is dev-only.PKCE_REQUIRED=true. Clients without PKCE
(Cursor, MCP Inspector) need an explicit operator override.RENDER_CONSENT_PAGE=true. Closes the
silent-token-issuance phishing path.N-replica deployment admits up to N × the
documented per-endpoint rate. Size TRUSTED_PROXY_CIDRS and any
upstream WAF accordingly./authorize — COMPAT_ALLOW_STATELESS=false.
The proxy refuses requests without a client-supplied state.TRUSTED_PROXY_CIDRS
must be set if you want the rate limiter to honour X-Forwarded-*.
Wildcard trust (TRUST_PROXY_HEADERS=true without a CIDR list)
fails startup.Set PROD_MODE=false only for single-replica dev / debugging that
needs one of the relaxation toggles. The CI manifest gate
(manifest-prod job) enforces this posture on the shipped overlay.
Everything transient is sealed, not stored. Client registrations,
authorize sessions, authorization codes, access tokens, refresh
tokens — each one is an AES-GCM blob carrying its own TTL and an
audience matching PROXY_BASE_URL. No application database is
required. Redis is required by default for replay protection
(single-use authorization codes, refresh-rotation reuse detection,
single-use consent + callback-state tokens) — the sealed payloads
alone remain replayable within their TTL.
Every payload verifies its audience on open. Two deployments that
accidentally share a TOKEN_SIGNING_SECRET but differ on
PROXY_BASE_URL cannot replay each other's tokens — tested
across every sealed type.
See specs.md for the full trade-off table,
revocation rollout notes, and the K8s deployment shape.
/register accepts https and loopback http redirect URIs. Native
clients with a custom scheme (Warp:
warp://dev.warp.Warp-Stable/mcp/callback, matched byte-exactly except
the scheme's case) need REDIRECT_URIS_EXTRA: exact URIs or
<scheme>://*, e.g. REDIRECT_URIS_EXTRA=warp://*. Any local app can
claim a custom scheme, so /authorize requires S256 PKCE for these
redirects whatever PKCE_REQUIRED says.
Per-endpoint contract details (params, error shapes, replay-claim
ordering) live in specs.md.
request_id (in the log AND the
X-Request-Id response header — inbound is stripped). Authenticated
requests carry sub and email.:9090, loopback-only
by default). Series families:
mcp_auth_tokens_issued_total{grant_type}mcp_auth_authorize_initiated_total{path} — funnel entrymcp_auth_consent_decisions_total{decision} — funnel approve/denymcp_auth_access_denied_total{reason} — every denial bucketmcp_auth_replay_detected_total{kind} — code / refresh /
consent / callback_state. consent also counts benign
double-submits (replay answers with a re-rendered consent page,
not a 4xx) — alert on sustained rate, not single ticksmcp_auth_rate_limited_total{endpoint} — pre-auth httprate 429smcp_auth_idp_exchange_throttled_total — outbound bucket denialsmcp_auth_clients_registered_total, mcp_auth_token_seals_total{purpose},
mcp_auth_groups_claim_shape_mismatch_totalmcp_auth_rpc_calls_total{tool} and friends — opt-in via
MCP_TOOL_METRICS=true (per-tool RPC traffic)GET /healthz (liveness, public router) and
GET /readyz (metrics port; reflects Redis when REDIS_URL is set,
cached ~1s to resist probe-flood amplification).Full alerting playbook + PromQL recipes (consent funnel rate, seal
counter rotation alert, etc.) in
docs/configuration.md.
manifests/ ships a turn-key local stack: Docker
Compose with Keycloak (pre-seeded realm + admin user), Redis, a
minimal MCP server, and the proxy itself wired end-to-end. The
manifests/k8s/ set is split between reference YAML templates and a
production-oriented kustomize overlay at
manifests/overlays/production. manifests/scripts/generate-signing-secret.sh
emits a 64-character cryptographically-random base64 string suitable
for TOKEN_SIGNING_SECRET.
./build.sh local # local binary only
./build.sh docker # docker image only
./build.sh # both
build.sh injects Version, CommitHash, BuildTimestamp,
Builder, and ProjectURL via -ldflags -X. CI
(release.yml) does the same on
tag pushes — native multi-arch builders for linux/amd64 and
linux/arm64, per-platform tags merged into a manifest list, GitHub
Release auto-created.
Release a new version:
git tag v1.2.3 && git push origin v1.2.3
Stateless → plain Deployment + Service. Required invariants
across replicas:
TOKEN_SIGNING_SECRET (mount from a Secret, do not
generate per-pod).PROXY_BASE_URL (public DNS, not a per-pod hostname).terminationGracePeriodSeconds ≥ SHUTDOWN_TIMEOUT so rolling
deploys don't chop SSE streams mid-flight.A ready-to-adapt manifest shape sits at
manifests/overlays/production/
and at the bottom of
specs.md.
Production posture guides:
docs/redis-production.md — what
"production Redis" means for this proxy (auth, TLS, HA, sizing).docs/conformance.md — spec claim matrix,
compatibility notes, current IdP evidence.docs/threat-model.md — STRIDE coverage
matrix.docs/release-checklist.md — checks
to run before and after publishing a release image.docs/runbooks/ — key rotation, bulk
revocation, Redis outage, IdP outage, consent denials, client
registration expired.go test ./... # unit + e2e (mock OIDC)
go test -tags=keycloak_e2e -run "^TestKeycloakE2E" -count=1 .
go test -race ./... # race detector
go test -cover ./... # coverage
The mock-IdP e2e (e2e_test.go) exercises registration → authorize →
callback → token → refresh → bearer-protected proxy. The
keycloak_e2e build tag runs the same flows + four negative-path
tests against the Docker Compose demo stack with real Keycloak. The
forwarding test (TestKeycloakE2E_ForwardsIdPAccessToken) needs the
stack started with --profile forwarding and is skipped otherwise. CI
runs both paths automatically on every PR.
Tagged releases are built by
release.yml with SLSA
provenance (mode=max) + SBOM attestations embedded in the OCI
image index, and keyless cosign signatures over both the
per-platform image digests and the merged multi-arch index, anchored
in the Rekor transparency log.
Image tags strip the v prefix (ghcr.io/babs/mcp-auth-proxy:1.0.0)
while git tags carry it (v1.0.0). The identity regex below matches
the git tag form.
cosign verify \
--certificate-identity-regexp '^https://github\.com/babs/mcp-auth-proxy/\.github/workflows/release\.yml@refs/tags/v' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/babs/mcp-auth-proxy:1.0.0
Inspect provenance and SBOM:
docker buildx imagetools inspect ghcr.io/babs/mcp-auth-proxy:1.0.0 \
--format '{{json .Provenance}}' | jq
docker buildx imagetools inspect ghcr.io/babs/mcp-auth-proxy:1.0.0 \
--format '{{json .SBOM}}' | jq
A policy controller (Kyverno, Sigstore policy-controller, …) can enforce these checks on every pull in a cluster — see each tool's docs for the exact policy syntax.
OAuth 2.1 + OIDC bridge for private MCP servers. Stateless, replay-safe, audit-defensible. Bring any IdP — Keycloak to Entra.
เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
MCP Auth Proxy ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-10-27 OAuth 2.1 + OIDC bridge for private MCP servers. Stateless, replay-safe, audit-defensible. Bring any IdP — Keycloak to Entra.