auth0-diagnostics-mcp 0.1.0__py3-none-any.whl

auth0_diagnostics_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: auth0-diagnostics-mcp
+Version: 0.1.0
+Summary: MCP server exposing Auth0 developer tools for Claude
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: httpx>=0.27
+Requires-Dist: PyJWT>=2.8
+Requires-Dist: cryptography>=41.0
+
+# auth0-mcp-server
+
+Auth0 developer tools for Claude Code and any MCP-compatible AI assistant.
+
+Decode JWTs, diagnose OAuth errors, validate tokens, and look up the right Auth0 flow — all without leaving your chat.
+
+## Installation
+
+Add this to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "auth0-local": {
+      "command": "uvx",
+      "args": ["auth0-mcp-server"]
+    }
+  }
+}
+```
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/). No other setup needed — `uvx` fetches and runs the server automatically.
+
+## Tools
+
+### `decode_token`
+Decode and explain a JWT. Shows the header, all claims, expiry status, and what each standard claim means. Does not verify the signature.
+
+> "Decode this token: eyJhbGci..."
+
+### `validate_token`
+Verify a JWT's signature against an Auth0 tenant's public JWKS endpoint.
+
+> "Validate this token against my-app.us.auth0.com"
+
+### `diagnose_auth_error`
+Explain an Auth0 or OAuth error code — what it means, why it happens, and how to fix it.
+
+> "What does invalid_grant mean?"
+
+### `explain_flow`
+Recommend the right Auth0 / OAuth 2.0 flow for your app type and use case.
+
+> "What flow should I use for a React SPA that calls an API?"
+
+### `get_tenant_config`
+Fetch and summarize an Auth0 tenant's OIDC discovery document — issuer, JWKS URI, supported scopes, grant types, and more.
+
+> "Show me the config for my-app.us.auth0.com"
+
+## Usage
+
+Just describe what you need in plain English — Claude picks the right tool automatically:
+
+- "Decode this JWT: eyJhbGci..."
+- "Why am I getting server_error on my callback URL?"
+- "What Auth0 flow should I use for a mobile app?"
+- "Validate this token against compass-os.us.auth0.com with audience https://my-api"
+
+## Requirements
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/getting-started/installation/)

auth0_diagnostics_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+server.py,sha256=NJkrQh2iNv7pvsMtBmeU96DfB15WHb8Y7CyoLZSiPxg,23211
+auth0_diagnostics_mcp-0.1.0.dist-info/METADATA,sha256=LchjHV0OEkM9ii_t80jYBIwqEn3krV5HcYRBcx7hGd8,2210
+auth0_diagnostics_mcp-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+auth0_diagnostics_mcp-0.1.0.dist-info/entry_points.txt,sha256=9bvHE9L7YFOGSoK51ZKYXiox9CfMvI75mNG-oDgicpk,54
+auth0_diagnostics_mcp-0.1.0.dist-info/top_level.txt,sha256=StKOSmRhvWS5IPcvhsDRbtxUTEofJgYFGOu5AAJdSWo,7
+auth0_diagnostics_mcp-0.1.0.dist-info/RECORD,,

auth0_diagnostics_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

auth0_diagnostics_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+auth0-diagnostics-mcp = server:main

auth0_diagnostics_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+server

server.py

@@ -0,0 +1,491 @@
+"""Auth0 MCP Server — developer tools for Auth0 integrations."""
+
+import base64
+import json
+import textwrap
+from typing import Any
+
+import httpx
+from mcp.server import MCPServer
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+mcp = MCPServer("auth0-diagnostics-mcp")
+
+
+# ── JWT helpers ────────────────────────────────────────────────────────────────
+
+def _b64_decode(segment: str) -> dict[str, Any]:
+    padded = segment + "=" * (-len(segment) % 4)
+    return json.loads(base64.urlsafe_b64decode(padded))
+
+
+def _split_token(token: str) -> tuple[dict[str, Any], dict[str, Any], str]:
+    parts = token.strip().split(".")
+    if len(parts) != 3:
+        raise ValueError("Not a valid JWT — expected 3 dot-separated parts.")
+    return _b64_decode(parts[0]), _b64_decode(parts[1]), parts[2]
+
+
+# ── Static knowledge bases ─────────────────────────────────────────────────────
+
+AUTH0_ERRORS: dict[str, dict[str, str]] = {
+    "invalid_grant": {
+        "summary": "The grant (auth code, refresh token, or device code) is invalid, expired, or already used.",
+        "common_causes": "Authorization code used more than once; refresh token revoked or expired; clock skew between client and server.",
+        "fix": "Restart the auth flow to get a fresh code. For refresh tokens, re-authenticate the user. Ensure system clocks are synced (NTP).",
+    },
+    "unauthorized_client": {
+        "summary": "The client application is not authorized to use this grant type.",
+        "common_causes": "Grant type not enabled for the application in the Auth0 dashboard; wrong client ID.",
+        "fix": "In Auth0 Dashboard → Applications → your app → scroll to 'Grant Types' and enable the required flow.",
+    },
+    "access_denied": {
+        "summary": "The user or authorization server denied the request.",
+        "common_causes": "User clicked 'Cancel' on the consent screen; a Rule/Action blocked the login; MFA failed.",
+        "fix": "Check your Auth0 Actions/Rules logs. If a custom action is blocking, review its logic in Dashboard → Auth Pipeline.",
+    },
+    "invalid_client": {
+        "summary": "Client authentication failed — wrong client ID or secret.",
+        "common_causes": "Mismatched client_id/client_secret; rotating a secret without updating the app config.",
+        "fix": "Verify your client_id and client_secret in Auth0 Dashboard → Applications → your app → Settings.",
+    },
+    "invalid_request": {
+        "summary": "The request is missing a required parameter or has an invalid value.",
+        "common_causes": "Missing redirect_uri, scope, or response_type; redirect_uri not whitelisted.",
+        "fix": "Add your redirect_uri to 'Allowed Callback URLs' in the Auth0 Dashboard. Check all required OAuth params are present.",
+    },
+    "unsupported_grant_type": {
+        "summary": "The authorization server does not support the requested grant type.",
+        "common_causes": "Typo in grant_type value; grant type not enabled for the application.",
+        "fix": "Check the grant_type value in your request. Enable it in Auth0 Dashboard → Applications → Grant Types.",
+    },
+    "invalid_scope": {
+        "summary": "The requested scope is invalid, unknown, or malformed.",
+        "common_causes": "Requesting a custom scope not defined in Auth0; typo in scope name.",
+        "fix": "Define custom scopes in Auth0 Dashboard → APIs → your API → Permissions. Ensure scopes are space-separated.",
+    },
+    "login_required": {
+        "summary": "The authorization server requires end-user authentication.",
+        "common_causes": "prompt=none used but the user has no active session.",
+        "fix": "Remove prompt=none or handle this error by redirecting the user to login.",
+    },
+    "consent_required": {
+        "summary": "The user must explicitly consent to the requested scopes.",
+        "common_causes": "prompt=none used but consent hasn't been granted yet.",
+        "fix": "Remove prompt=none for first-time users, or mark the application as first-party to skip consent.",
+    },
+    "mfa_required": {
+        "summary": "Multi-factor authentication is required for this user.",
+        "common_causes": "MFA policy enforced via Auth0 Actions or the user's profile.",
+        "fix": "Your app must handle the MFA challenge. Use Universal Login or the MFA API to complete the MFA step.",
+    },
+    "too_many_attempts": {
+        "summary": "The account has been blocked due to too many failed login attempts.",
+        "common_causes": "Brute force protection triggered.",
+        "fix": "User must wait for the lockout to expire, or an admin can unblock the account in Auth0 Dashboard → User Management → Users.",
+    },
+    "expired_token": {
+        "summary": "The provided token has expired.",
+        "common_causes": "Using an access token past its expiry; not refreshing tokens proactively.",
+        "fix": "Check the exp claim in the token. Use a refresh token to get a new access token, or re-authenticate the user.",
+    },
+    "invalid_token": {
+        "summary": "The token is malformed or its signature is invalid.",
+        "common_causes": "Token tampered with; wrong signing key; audience or issuer mismatch.",
+        "fix": "Verify the token using the validate_token tool. Ensure issuer matches https://{domain}/ and audience matches your API identifier.",
+    },
+    "PasswordStrengthError": {
+        "summary": "The password does not meet the tenant's strength requirements.",
+        "common_causes": "Password policy set to Fair, Good, or Excellent in Auth0.",
+        "fix": "Check the password policy in Auth0 Dashboard → Authentication → Database → your connection → Password Policy.",
+    },
+    "user_cancelled": {
+        "summary": "The user cancelled the authentication flow.",
+        "common_causes": "User clicked 'Cancel' or closed the login window.",
+        "fix": "Handle this gracefully — redirect to a landing page or show a re-login prompt.",
+    },
+    "server_error": {
+        "summary": "An unexpected error occurred on the Auth0 server.",
+        "common_causes": "Transient Auth0 service issue; misconfigured custom domain; an Action throwing an unhandled exception.",
+        "fix": "Check https://status.auth0.com for incidents. Review Auth0 Logs in Dashboard → Monitoring → Logs for stack traces.",
+    },
+}
+
+FLOWS_CONTENT = textwrap.dedent("""\
+    # Auth0 OAuth / OIDC Flows
+
+    ## Authorization Code Flow
+    **Best for:** Server-side web apps (Node, Python, Rails, etc.)
+    **How it works:** App redirects user → Auth0 login → Auth0 redirects back with a code →
+    App exchanges code + client_secret for tokens on the backend.
+    **Key property:** Client secret never exposed to the browser.
+    **Auth0 guide:** https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow
+
+    ---
+
+    ## Authorization Code Flow with PKCE
+    **Best for:** SPAs, mobile/native apps, CLI tools — any public client without a secure secret store.
+    **How it works:** Same as Authorization Code but replaces the client_secret with a
+    PKCE code_verifier / code_challenge pair generated by the client.
+    **Key property:** Secure even without a client secret.
+    **Auth0 guide:** https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce
+
+    ---
+
+    ## Client Credentials Flow
+    **Best for:** Machine-to-machine (M2M) — backend services, daemons, cron jobs acting as themselves.
+    **How it works:** App sends client_id + client_secret directly to /oauth/token and gets an access token.
+    **Key property:** No user involved.
+    **Auth0 guide:** https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow
+
+    ---
+
+    ## Device Authorization Flow
+    **Best for:** Input-constrained devices — smart TVs, IoT devices, CLI tools without a browser.
+    **How it works:** Device requests a user_code → user visits a URL on another device to authorize → device polls for token.
+    **Key property:** Decouples authentication from the device.
+    **Auth0 guide:** https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow
+
+    ---
+
+    ## Resource Owner Password Flow (Legacy)
+    **Best for:** Legacy systems only — highly trusted first-party apps where redirect-based flows are impossible.
+    **Key property:** Auth0 recommends AGAINST this for new projects — use PKCE instead.
+    **Auth0 guide:** https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow
+
+    ---
+
+    ## Implicit Flow (Deprecated)
+    **Status:** Deprecated — do not use for new applications.
+    **Replacement:** Authorization Code Flow with PKCE.
+""")
+
+FLOW_DETAILS: dict[str, dict[str, str]] = {
+    "authorization_code": {
+        "name": "Authorization Code Flow",
+        "when": "Server-side web applications with a secure backend.",
+        "why": "The client_secret stays on the server and is never exposed to the browser.",
+        "guide": "https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow",
+    },
+    "pkce": {
+        "name": "Authorization Code Flow with PKCE",
+        "when": "SPAs, mobile/native apps, CLI tools — any public client.",
+        "why": "PKCE replaces the client_secret with a cryptographic challenge, making it safe for clients that can't store secrets securely.",
+        "guide": "https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce",
+    },
+    "client_credentials": {
+        "name": "Client Credentials Flow",
+        "when": "Machine-to-machine communication — no user involved.",
+        "why": "The application authenticates as itself, not on behalf of a user.",
+        "guide": "https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow",
+    },
+    "device": {
+        "name": "Device Authorization Flow",
+        "when": "Input-constrained devices or headless CLIs without a browser.",
+        "why": "Decouples authentication from the device — the user authorizes on their phone or laptop.",
+        "guide": "https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow",
+    },
+}
+
+
+def _recommend_flow(app_type: str, use_case: str) -> str:
+    text = f"{app_type} {use_case}".lower()
+    if any(w in text for w in ["m2m", "machine", "service", "daemon", "cron", "backend to backend", "api to api", "server to server"]):
+        return "client_credentials"
+    if any(w in text for w in ["tv", "iot", "device", "limited input", "no browser", "headless", "smart "]):
+        return "device"
+    if any(w in text for w in ["spa", "single page", "react", "vue", "angular", "browser app", "mobile", "ios", "android", "native", "public client", "cli"]):
+        return "pkce"
+    if any(w in text for w in ["server", "backend", "rails", "django", "flask", "fastapi", "express", "next", "nuxt", "web app"]):
+        return "authorization_code"
+    return "pkce"
+
+
+# ── Tools ──────────────────────────────────────────────────────────────────────
+
+@mcp.tool()
+async def decode_token(token: str) -> str:
+    """Decode and explain a JWT — shows the header, all claims, expiry status,
+    and what each standard claim means. Does NOT verify the signature.
+    Strips a 'Bearer ' prefix automatically."""
+    from datetime import datetime, timezone
+    import time
+
+    token = token.removeprefix("Bearer ").strip()
+    try:
+        header, payload, _ = _split_token(token)
+    except ValueError as e:
+        return f"Invalid JWT: {e}"
+
+    now = int(time.time())
+    lines: list[str] = ["## JWT Decoded\n", "### Header"]
+    lines.append(f"```json\n{json.dumps(header, indent=2)}\n```")
+    lines.append("\n### Payload")
+    lines.append(f"```json\n{json.dumps(payload, indent=2)}\n```")
+    lines.append("\n### Key Claims Explained")
+
+    if "sub" in payload:
+        lines.append(f"- **sub** (Subject): `{payload['sub']}` — unique identifier for the user or entity")
+    if "iss" in payload:
+        lines.append(f"- **iss** (Issuer): `{payload['iss']}` — the Auth0 tenant that issued this token")
+    if "aud" in payload:
+        lines.append(f"- **aud** (Audience): `{payload['aud']}` — intended recipient(s); must match your API identifier")
+    if exp := payload.get("exp"):
+        exp_dt = datetime.fromtimestamp(exp, tz=timezone.utc).isoformat()
+        status = "**EXPIRED**" if now > exp else f"valid for {exp - now}s more"
+        lines.append(f"- **exp** (Expiry): `{exp_dt}` — {status}")
+    if iat := payload.get("iat"):
+        iat_dt = datetime.fromtimestamp(iat, tz=timezone.utc).isoformat()
+        lines.append(f"- **iat** (Issued At): `{iat_dt}`")
+    if nbf := payload.get("nbf"):
+        nbf_dt = datetime.fromtimestamp(nbf, tz=timezone.utc).isoformat()
+        not_yet = now < nbf
+        lines.append(f"- **nbf** (Not Before): `{nbf_dt}`{' — **not yet valid**' if not_yet else ''}")
+    if "scope" in payload:
+        lines.append(f"- **scope**: `{payload['scope']}` — granted permissions")
+    if "azp" in payload:
+        lines.append(f"- **azp** (Authorized Party): `{payload['azp']}` — client application that requested this token")
+
+    lines.append("\n> Signature not verified — use `validate_token` to cryptographically verify against the issuer's JWKS.")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def validate_token(token: str, domain: str, audience: str = "") -> str:
+    """Verify a JWT's signature and standard claims against an Auth0 tenant's
+    public JWKS endpoint. Returns a pass/fail result and decoded claims on success.
+
+    Args:
+        token: The JWT to validate.
+        domain: Auth0 domain, e.g. myapp.us.auth0.com
+        audience: Expected audience (your API identifier). Optional but recommended.
+    """
+    import jwt as pyjwt
+    from jwt.algorithms import RSAAlgorithm
+
+    token = token.removeprefix("Bearer ").strip()
+    domain = domain.removeprefix("https://").rstrip("/")
+
+    try:
+        header, _, _ = _split_token(token)
+    except ValueError as e:
+        return f"Invalid JWT format: {e}"
+
+    kid = header.get("kid")
+    alg = header.get("alg", "RS256")
+
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            jwks_resp = await client.get(f"https://{domain}/.well-known/jwks.json")
+            jwks_resp.raise_for_status()
+            jwks = jwks_resp.json()
+    except httpx.HTTPError as e:
+        return f"Failed to fetch JWKS from `{domain}`: {e}"
+
+    matching = [k for k in jwks.get("keys", []) if k.get("kid") == kid]
+    if not matching:
+        available = [k.get("kid") for k in jwks.get("keys", [])]
+        return f"No JWKS key found matching `kid={kid}`.\nAvailable kids: {available}"
+
+    try:
+        public_key = RSAAlgorithm.from_jwk(json.dumps(matching[0]))
+        decode_kwargs: dict[str, Any] = {
+            "algorithms": [alg],
+            "issuer": f"https://{domain}/",
+        }
+        if audience:
+            decode_kwargs["audience"] = audience
+        else:
+            decode_kwargs["options"] = {"verify_aud": False}
+
+        claims = pyjwt.decode(token, public_key, **decode_kwargs)
+        lines = [
+            "## Token Validation: PASSED ✓\n",
+            "Signature is valid and claims verified.\n",
+            f"```json\n{json.dumps(claims, indent=2)}\n```",
+        ]
+        if not audience:
+            lines.append("\n> Tip: pass an `audience` value to also verify the `aud` claim.")
+        return "\n".join(lines)
+
+    except pyjwt.ExpiredSignatureError:
+        return "## Token Validation: FAILED ✗\n\n**Reason:** Token has expired. Check the `exp` claim with `decode_token`."
+    except pyjwt.InvalidIssuerError:
+        return f"## Token Validation: FAILED ✗\n\n**Reason:** Issuer mismatch. Token issuer does not match `https://{domain}/`."
+    except pyjwt.InvalidAudienceError:
+        return f"## Token Validation: FAILED ✗\n\n**Reason:** Audience mismatch. Token `aud` does not match `{audience}`."
+    except Exception as e:
+        return f"## Token Validation: FAILED ✗\n\n**Reason:** {e}"
+
+
+@mcp.tool()
+async def get_tenant_config(domain: str) -> str:
+    """Fetch and summarize an Auth0 tenant's public OIDC discovery document —
+    issuer, JWKS URI, supported scopes, grant types, and more.
+
+    Args:
+        domain: Auth0 domain, e.g. myapp.us.auth0.com
+    """
+    domain = domain.removeprefix("https://").rstrip("/")
+    url = f"https://{domain}/.well-known/openid-configuration"
+
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            resp = await client.get(url)
+            resp.raise_for_status()
+            config: dict[str, Any] = resp.json()
+    except httpx.HTTPError as e:
+        return f"Failed to fetch OIDC config from `{domain}`: {e}"
+
+    lines = [
+        f"## Auth0 Tenant: `{domain}`\n",
+        f"**Issuer:** `{config.get('issuer', 'N/A')}`",
+        f"**JWKS URI:** `{config.get('jwks_uri', 'N/A')}`",
+        f"**Authorization endpoint:** `{config.get('authorization_endpoint', 'N/A')}`",
+        f"**Token endpoint:** `{config.get('token_endpoint', 'N/A')}`",
+        f"**Userinfo endpoint:** `{config.get('userinfo_endpoint', 'N/A')}`",
+    ]
+    if scopes := config.get("scopes_supported"):
+        lines.append(f"\n**Supported scopes:** {', '.join(f'`{s}`' for s in scopes)}")
+    if algs := config.get("id_token_signing_alg_values_supported"):
+        lines.append(f"**ID token signing algorithms:** {', '.join(algs)}")
+    if grants := config.get("grant_types_supported"):
+        lines.append(f"**Grant types:** {', '.join(f'`{g}`' for g in grants)}")
+    if response_types := config.get("response_types_supported"):
+        lines.append(f"**Response types:** {', '.join(response_types)}")
+
+    lines.append(f"\n<details><summary>Full OIDC config</summary>\n\n```json\n{json.dumps(config, indent=2)}\n```\n</details>")
+    return "\n".join(lines)
+
+
+@mcp.tool()
+def diagnose_auth_error(error: str) -> str:
+    """Explain an Auth0 or OAuth error code — returns what it means,
+    common reasons it happens, and how to fix it.
+
+    Args:
+        error: The OAuth/Auth0 error code, e.g. invalid_grant
+    """
+    info = AUTH0_ERRORS.get(error.strip())
+
+    if not info:
+        known = ", ".join(f"`{k}`" for k in AUTH0_ERRORS)
+        return (
+            f"Unknown error code: `{error}`.\n\n"
+            f"Known codes: {known}\n\n"
+            "For unlisted errors, check: https://auth0.com/docs/libraries/error-messages"
+        )
+
+    return "\n".join([
+        f"## Auth0 Error: `{error}`\n",
+        f"**What it means:** {info['summary']}\n",
+        f"**Common causes:** {info['common_causes']}\n",
+        f"**How to fix:** {info['fix']}",
+    ])
+
+
+@mcp.tool()
+def explain_flow(app_type: str, use_case: str) -> str:
+    """Given an application type and use case, recommend the right
+    Auth0 / OAuth 2.0 flow with an explanation of why it fits.
+
+    Args:
+        app_type: e.g. SPA, mobile app, CLI, backend service, IoT device
+        use_case: Brief description of what the app needs to do with auth
+    """
+    flow_key = _recommend_flow(app_type, use_case)
+    flow = FLOW_DETAILS[flow_key]
+
+    return "\n".join([
+        f"## Recommended Flow: **{flow['name']}**\n",
+        f"**When to use:** {flow['when']}",
+        f"**Why it fits your case:** {flow['why']}\n",
+        f"**Auth0 guide:** {flow['guide']}\n",
+        "---",
+        "\nRead the `auth0://flows` resource for a comparison of all Auth0 flows.",
+    ])
+
+
+# ── Resources ──────────────────────────────────────────────────────────────────
+
+@mcp.resource(
+    "auth0://flows",
+    name="Auth0 OAuth / OIDC Flows",
+    description="Reference guide for all Auth0 authentication flows — when to use each and why.",
+    mime_type="text/markdown",
+)
+def flows_resource() -> str:
+    return FLOWS_CONTENT
+
+
+# ── OAuth discovery stubs (no auth required) ──────────────────────────────────
+# Claude Code's MCP client hits these RFC 9728/8414 endpoints and fails hard if
+# the response body isn't valid JSON — even on 404.  It also probes path-based
+# discovery variants (RFC 9728 §3.1) and the SSE-prefixed paths, so all
+# variants need JSON responses.
+
+def _no_auth_json() -> JSONResponse:
+    return JSONResponse(
+        {"error": "not_found", "error_description": "This server does not require OAuth authentication."},
+        status_code=404,
+    )
+
+
+@mcp.custom_route("/.well-known/oauth-protected-resource", methods=["GET"])
+async def _oauth_protected_resource(request: Request) -> JSONResponse:
+    return _no_auth_json()
+
+
+@mcp.custom_route("/.well-known/oauth-protected-resource/sse", methods=["GET"])
+async def _oauth_protected_resource_sse(request: Request) -> JSONResponse:
+    return _no_auth_json()
+
+
+@mcp.custom_route("/.well-known/oauth-authorization-server", methods=["GET"])
+async def _oauth_authorization_server(request: Request) -> JSONResponse:
+    return _no_auth_json()
+
+
+@mcp.custom_route("/.well-known/oauth-authorization-server/sse", methods=["GET"])
+async def _oauth_authorization_server_sse(request: Request) -> JSONResponse:
+    return _no_auth_json()
+
+
+@mcp.custom_route("/.well-known/openid-configuration", methods=["GET"])
+async def _openid_configuration(request: Request) -> JSONResponse:
+    return _no_auth_json()
+
+
+@mcp.custom_route("/.well-known/openid-configuration/sse", methods=["GET"])
+async def _openid_configuration_sse(request: Request) -> JSONResponse:
+    return _no_auth_json()
+
+
+@mcp.custom_route("/sse/.well-known/openid-configuration", methods=["GET"])
+async def _sse_openid_configuration(request: Request) -> JSONResponse:
+    return _no_auth_json()
+
+
+@mcp.custom_route("/register", methods=["POST"])
+async def _register(request: Request) -> JSONResponse:
+    return JSONResponse(
+        {"error": "not_supported", "error_description": "Dynamic client registration is not supported."},
+        status_code=400,
+    )
+
+
+# ── Entry point ────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    import sys
+    transport = "stdio"
+    if "--transport" in sys.argv:
+        idx = sys.argv.index("--transport")
+        if idx + 1 < len(sys.argv):
+            transport = sys.argv[idx + 1]
+    mcp.run(transport=transport)
+
+
+if __name__ == "__main__":
+    main()