authplane-mcp 0.1.0__tar.gz

authplane_mcp-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/

authplane_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12.8

authplane_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: authplane-mcp
+Version: 0.1.0
+Summary: Authplane JWT validation adapter for the official MCP Python SDK
+Project-URL: Homepage, https://github.com/AuthPlane/python-sdk/tree/main/authplane-mcp
+Project-URL: Issues, https://github.com/AuthPlane/python-sdk/issues
+Author: Authplane Team
+License-Expression: Apache-2.0
+Keywords: adapter,authplane,jwt,mcp,oauth
+Requires-Python: >=3.11
+Requires-Dist: authplane-sdk==0.1.0
+Requires-Dist: mcp<1.28.0,>=1.23.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: coverage>=7; extra == 'dev'
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# authplane-mcp
+
+[![PyPI](https://img.shields.io/pypi/v/authplane-mcp?style=flat-square&label=authplane-mcp)](https://pypi.org/project/authplane-mcp/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
+
+Authplane JWT validation for servers built on the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).
+
+## Install
+
+```bash
+pip install authplane-mcp
+```
+
+## Compatibility
+
+Supported `mcp` range: **`>=1.23.0, <1.28.0`**. MCP 1.28 renamed the elicitation field from `elicitationId` (camelCase) to `elicitation_id` (snake_case), which breaks this adapter's current wire handling. If your project needs MCP 1.28+, please open an issue — the adapter update is straightforward, we just haven't cut it yet.
+
+## Quickstart
+
+```python
+import asyncio
+from authplane_mcp import authplane_mcp_auth
+from mcp.server.fastmcp import FastMCP
+
+auth_result = asyncio.run(
+    authplane_mcp_auth(
+        issuer="https://auth.company.com",
+        resource="https://mcp.company.com",
+        scopes=["tools/query", "tools/write"],
+    )
+)
+
+mcp = FastMCP("My MCP Server", json_response=True, **auth_result)
+
+@mcp.tool()
+async def query_database(query: str) -> str:
+    return f"Result for: {query}"
+
+mcp.run(transport="streamable-http")
+```
+
+`mcp.run()` starts its own event loop, so the auth setup runs synchronously via `asyncio.run(...)` first. `auth_result` holds background JWKS and metadata refresh tasks — call `await auth_result.aclose()` during server shutdown.
+
+## Documentation
+
+PRM behavior, dev mode, revocation checking, manual setup, the full `authplane_mcp_auth` / `AuthplaneTokenVerifier` API, and error handling: **[User Guide](docs/user-guide.md)**.

authplane_mcp-0.1.0/README.md

@@ -0,0 +1,46 @@
+# authplane-mcp
+
+[![PyPI](https://img.shields.io/pypi/v/authplane-mcp?style=flat-square&label=authplane-mcp)](https://pypi.org/project/authplane-mcp/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
+
+Authplane JWT validation for servers built on the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).
+
+## Install
+
+```bash
+pip install authplane-mcp
+```
+
+## Compatibility
+
+Supported `mcp` range: **`>=1.23.0, <1.28.0`**. MCP 1.28 renamed the elicitation field from `elicitationId` (camelCase) to `elicitation_id` (snake_case), which breaks this adapter's current wire handling. If your project needs MCP 1.28+, please open an issue — the adapter update is straightforward, we just haven't cut it yet.
+
+## Quickstart
+
+```python
+import asyncio
+from authplane_mcp import authplane_mcp_auth
+from mcp.server.fastmcp import FastMCP
+
+auth_result = asyncio.run(
+    authplane_mcp_auth(
+        issuer="https://auth.company.com",
+        resource="https://mcp.company.com",
+        scopes=["tools/query", "tools/write"],
+    )
+)
+
+mcp = FastMCP("My MCP Server", json_response=True, **auth_result)
+
+@mcp.tool()
+async def query_database(query: str) -> str:
+    return f"Result for: {query}"
+
+mcp.run(transport="streamable-http")
+```
+
+`mcp.run()` starts its own event loop, so the auth setup runs synchronously via `asyncio.run(...)` first. `auth_result` holds background JWKS and metadata refresh tasks — call `await auth_result.aclose()` during server shutdown.
+
+## Documentation
+
+PRM behavior, dev mode, revocation checking, manual setup, the full `authplane_mcp_auth` / `AuthplaneTokenVerifier` API, and error handling: **[User Guide](docs/user-guide.md)**.

authplane_mcp-0.1.0/authplane_mcp/__init__.py

@@ -0,0 +1,25 @@
+"""Authplane Python SDK - MCP adapter.
+
+This package provides a thin adapter between the Authplane Python SDK and the
+official Model Context Protocol (MCP) Python SDK, enabling MCP servers to
+validate Authplane-issued JWT access tokens.
+
+Core SDK types (``ASCredentials``, ``FetchSettings``, ``IntrospectionRevocation``,
+DPoP types, errors, etc.) are imported from ``authplane`` directly. This package
+exports only the adapter-owned glue.
+"""
+
+__version__ = "0.1.0"
+
+from .auth import AuthplaneAuthResult, authplane_mcp_auth, require_scope
+from .url_elicitation import to_url_elicitation_required_error
+from .verifier import AuthplaneTokenVerifier
+
+__all__ = [
+    "AuthplaneAuthResult",
+    "AuthplaneTokenVerifier",
+    "__version__",
+    "authplane_mcp_auth",
+    "require_scope",
+    "to_url_elicitation_required_error",
+]

authplane_mcp-0.1.0/authplane_mcp/auth.py

@@ -0,0 +1,327 @@
+"""Convenience factory for enabling Authplane auth on MCP servers.
+
+Provides ``authplane_mcp_auth()``, an async factory function that creates
+and configures all the components needed to add Authplane JWT validation
+to an official MCP Python SDK server in a single call.
+"""
+
+from collections.abc import Iterator
+from typing import Any
+
+from authplane import (
+    ASCredentials,
+    AuthplaneClient,
+    DPoPProvider,
+    FetchSettings,
+    InboundDPoPOptions,
+    IntrospectionRevocation,
+    RevocationChecker,
+)
+from authplane.oauth import TokenExchangeOptions, TokenResponse
+from mcp.server.auth.middleware.auth_context import get_access_token as _get_access_token
+from mcp.server.auth.settings import AuthSettings
+from pydantic import AnyHttpUrl
+
+from .url_elicitation import to_url_elicitation_required_error
+from .verifier import AuthplaneTokenVerifier
+
+
+def _wrap_client_for_elicitation(client: AuthplaneClient) -> AuthplaneClient:
+    """Translate ``client.exchange`` consent errors into MCP ``-32042``.
+
+    Wrapping ``exchange()`` (the only method that realistically surfaces
+    ``ConsentRequiredError`` from the AS) means user tool code can call
+    ``result.client.exchange(...)`` without any try/except: a consent error
+    becomes a ``UrlElicitationRequiredError`` transparently, and FastMCP /
+    the MCP server forwards it as a ``-32042`` JSON-RPC error.
+    """
+    original_exchange = client.exchange
+
+    async def exchange(options: TokenExchangeOptions) -> TokenResponse:
+        try:
+            return await original_exchange(options)
+        except Exception as error:
+            mapped = to_url_elicitation_required_error(error)
+            if mapped is not None:
+                raise mapped from error
+            raise
+
+    client.exchange = exchange
+    return client
+
+
+def require_scope(scope: str) -> None:
+    """Raise PermissionError if the current request token is missing a required scope.
+
+    Call this at the top of a tool handler to enforce per-tool scope requirements::
+
+        @mcp.tool()
+        async def add(a: float, b: float) -> float:
+            require_scope("tools/add")
+            return a + b
+
+    Args:
+        scope: The scope string that must be present in the token.
+
+    Raises:
+        PermissionError: If the token is absent or does not contain ``scope``.
+    """
+    token = _get_access_token()
+    if token is None or scope not in token.scopes:
+        raise PermissionError(f"Missing required scope: {scope}")
+
+
+class AuthplaneAuthResult:
+    """Return value of ``authplane_mcp_auth()``.
+
+    Supports ``**`` unpacking into ``FastMCP()`` — only ``token_verifier``
+    and ``auth`` keys are included in the mapping view so FastMCP receives
+    exactly what it expects. ``client`` is exposed as a plain attribute for
+    advanced use cases such as RFC 8693 token exchange::
+
+        result = await authplane_mcp_auth(issuer=..., resource=..., ...)
+        mcp = FastMCP("My Server", **result)
+
+        # Inside a tool handler — exchange a user token for a downstream token:
+        downstream = await result.client.exchange(TokenExchangeOptions(
+            subject_token=user_token,
+        ))
+
+    Call ``await result.aclose()`` on server shutdown to release background
+    tasks and HTTP connections held by the underlying ``AuthplaneClient``.
+    """
+
+    def __init__(
+        self,
+        token_verifier: AuthplaneTokenVerifier,
+        auth: AuthSettings,
+        client: AuthplaneClient,
+    ) -> None:
+        self.token_verifier = token_verifier
+        self.auth = auth
+        self.client = client
+
+    async def aclose(self) -> None:
+        """Release resources held by the underlying ``AuthplaneClient``.
+
+        Cancels the background JWKS refresh task and closes the HTTP
+        connection pool.  Safe to call multiple times.
+        """
+        await self.client.aclose()
+
+    # Mapping protocol — yields only what FastMCP expects.
+    def keys(self) -> list[str]:
+        return ["token_verifier", "auth"]
+
+    def __getitem__(self, key: str) -> Any:
+        if key == "token_verifier":
+            return self.token_verifier
+        if key == "auth":
+            return self.auth
+        raise KeyError(key)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.keys())
+
+
+async def authplane_mcp_auth(
+    issuer: str,
+    resource: str,
+    scopes: list[str] | None = None,
+    *,
+    enforce_scopes_on_all_requests: bool = False,
+    as_credentials: ASCredentials | None = None,
+    dpop: DPoPProvider | None = None,
+    allowed_algorithms: list[str] | None = None,
+    jwks_refresh_seconds: int | None = None,
+    metadata_refresh_seconds: int | None = None,
+    cache_ttl_buffer_seconds: float | None = None,
+    default_ttl_seconds: float | None = None,
+    circuit_breaker_threshold: int | None = None,
+    circuit_breaker_cooldown_seconds: float | None = None,
+    clock_skew_seconds: int | None = None,
+    dev_mode: bool | None = None,
+    fetch_settings: FetchSettings | None = None,
+    inbound_dpop: InboundDPoPOptions | None = None,
+    revocation_checker: IntrospectionRevocation | RevocationChecker | None = None,
+) -> AuthplaneAuthResult:
+    """Build the kwargs to enable Authplane auth on a FastMCP server.
+
+    This async factory performs RFC 8414 metadata discovery, fetches the
+    JWKS, and wires up all components (client, resource, token verifier,
+    auth settings) in a single awaitable call.
+
+    Usage::
+
+        mcp = FastMCP(
+            "My Server",
+            **await authplane_mcp_auth(
+                issuer="https://auth.company.com",
+                resource="https://mcp.company.com",
+                scopes=["tools/query", "tools/write"],
+            )
+        )
+
+    Args:
+        issuer: Authplane authorization server URL
+            (e.g., ``"https://auth.company.com"``).
+        resource: URL of this MCP server / resource identifier
+            (e.g., ``"https://mcp.company.com"``). This is used as the
+            JWT audience (``aud`` claim) and ``resource_server_url`` in
+            AuthSettings.
+        scopes: All scopes this server supports. Defaults to an empty
+            list.
+        enforce_scopes_on_all_requests: When ``True``, ``scopes`` are passed
+            to the MCP SDK as ``AuthSettings.required_scopes``. This causes
+            two things:
+
+            1. The Protected Resource Metadata (PRM) endpoint advertises
+               them as ``scopes_supported`` — required for OAuth-discovery
+               clients (e.g. Claude Code) to know which scopes to request
+               on a fresh token mint, otherwise they fall back to the AS
+               metadata's global ``scopes_supported`` (every scope across
+               every resource) and the AS rejects with ``invalid_scope``.
+            2. ``RequireAuthMiddleware`` rejects any request whose token
+               does not carry **all** listed scopes — coarse-grained
+               enforcement at the request layer.
+
+            This is a workaround for an MCP reference SDK limitation:
+            ``AuthSettings`` has no separate "supported" field, so the SDK
+            uses ``required_scopes`` for both purposes (see
+            ``mcp/server/fastmcp/server.py`` ``create_protected_resource_routes``
+            calls).  Per-tool ``require_scope()`` is the intended granular
+            pattern; keep those calls in place even when this flag is
+            ``True`` — they remain correct, are simply redundant under
+            request-level enforcement, and continue to work unchanged
+            once the upstream SDK gains a separate "supported" field and
+            this flag becomes unnecessary.
+
+            Defaults to ``False``: PRM advertises no scopes, per-tool
+            ``require_scope()`` is the only enforcement.
+        dpop: Optional DPoP provider used for outbound calls from the
+            underlying SDK client to the authorization server.
+        allowed_algorithms: Algorithms allowed for signature verification.
+            Defaults to SDK defaults (``["RS256", "ES256"]``).
+        jwks_refresh_seconds: JWKS cache TTL in seconds (default ``300``).
+        cache_ttl_buffer_seconds: Buffer subtracted from token TTLs
+            before cache expiry (default ``30.0``).
+        default_ttl_seconds: Fallback token cache TTL used when token
+            responses do not include expiry metadata (default ``3600.0``).
+        circuit_breaker_threshold: Number of transient failures before
+            opening the AS circuit breaker (default ``5``).
+        circuit_breaker_cooldown_seconds: Cooldown before allowing a
+            half-open probe request after the circuit opens
+            (default ``30.0``).
+        clock_skew_seconds: Leeway in seconds for exp/nbf/iat validation
+            (default ``30``).
+        dev_mode: Enable development mode. Relaxes SSRF checks to allow
+            HTTP, localhost, and private networks. Can also be set via
+            ``AUTHPLANE_DEV_MODE=true`` environment variable.
+        metadata_refresh_seconds: AS metadata cache TTL in seconds
+            (default ``3600``).
+        fetch_settings: Full ``FetchSettings`` object applied to both
+            metadata and JWKS fetches. When provided, overrides
+            ``dev_mode`` for those fetches.
+        inbound_dpop: Per-resource inbound DPoP policy
+            (:class:`InboundDPoPOptions`).  Bundles ``required``,
+            ``signing_algs``, ``max_proof_age_seconds``,
+            ``clock_skew_seconds`` and ``replay_store``; see RFC 9728 §2 +
+            RFC 9449 §7.1 for the field semantics.
+        as_credentials: Client credentials for authenticating to the AS.
+            Shared by introspection (RFC 7662) and token exchange (RFC 8693).
+            Required when using ``IntrospectionRevocation`` for authenticated
+            introspection, or when calling ``client.exchange()``.
+        revocation_checker: Controls token revocation checking after
+            signature validation passes.
+
+            - ``None`` (default): disables revocation checking (offline
+              validation only).
+            - ``IntrospectionRevocation()``: calls the AS
+              ``introspection_endpoint`` (RFC 7662) discovered from AS
+              metadata. Raises ``TokenRevokedError`` if ``active=false``.
+              Pass ``as_credentials`` for authenticated introspection.
+              Fails open if the endpoint is unavailable.
+            - async callable: custom checker called with
+              ``(VerifiedClaims, raw_token)``; return ``True`` to reject
+              the token (raises ``TokenRevokedError``).
+
+    Returns:
+        ``AuthplaneAuthResult`` with ``token_verifier`` (``AuthplaneTokenVerifier``),
+        ``auth`` (``AuthSettings``), and ``client`` (``AuthplaneClient``) attributes.
+        Supports ``**`` unpacking into ``FastMCP()`` — only ``token_verifier``
+        and ``auth`` are included in the mapping view. Access ``client`` directly
+        for RFC 8693 token exchange via ``result.client.exchange()``.
+
+    Raises:
+        ValueError: If configuration is invalid (bad algorithms, etc.).
+        JWKSFetchError: If metadata discovery or JWKS fetching fails.
+    """
+    resolved_scopes = scopes or []
+
+    # Prepare client-level kwargs, filtering out None to use SDK defaults
+    client_kwargs_raw: dict[str, Any] = {
+        "dpop": dpop,
+        "dev_mode": dev_mode,
+        "fetch_settings": fetch_settings,
+        "jwks_refresh_seconds": jwks_refresh_seconds,
+        "metadata_refresh_seconds": metadata_refresh_seconds,
+        "cache_ttl_buffer_seconds": cache_ttl_buffer_seconds,
+        "default_ttl_seconds": default_ttl_seconds,
+        "circuit_breaker_threshold": circuit_breaker_threshold,
+        "circuit_breaker_cooldown_seconds": circuit_breaker_cooldown_seconds,
+    }
+    client_kwargs: dict[str, Any] = {k: v for k, v in client_kwargs_raw.items() if v is not None}
+
+    # Prepare resource-level kwargs, filtering out None to use SDK defaults
+    verifier_kwargs_raw: dict[str, Any] = {
+        "allowed_algorithms": allowed_algorithms,
+        "clock_skew_seconds": clock_skew_seconds,
+        "inbound_dpop": inbound_dpop,
+    }
+    verifier_kwargs: dict[str, Any] = {
+        k: v for k, v in verifier_kwargs_raw.items() if v is not None
+    }
+
+    # Create the AuthplaneClient (handles metadata discovery, JWKS fetching, caching)
+    client = await AuthplaneClient.create(
+        issuer=issuer,
+        auth=as_credentials,
+        **client_kwargs,
+    )
+
+    # Translate ConsentRequiredError → MCP UrlElicitationRequiredError at the
+    # client boundary, before user tool code sees it.  Tool authors don't need
+    # to wrap handlers or import elicitation primitives — the MCP wire-format
+    # mapping is owned by the adapter that constructs the client.
+    client = _wrap_client_for_elicitation(client)
+
+    # Create the resource from the client
+    verifier = client.resource(
+        resource=resource,
+        scopes=resolved_scopes,
+        revocation_checker=revocation_checker,
+        **verifier_kwargs,
+    )
+
+    # Wrap in AuthplaneTokenVerifier
+    token_verifier = AuthplaneTokenVerifier(verifier)
+
+    # Create AuthSettings for FastMCP.
+    #
+    # The MCP SDK's AuthSettings has no separate "supported" field — it uses
+    # ``required_scopes`` for both PRM ``scopes_supported`` advertisement
+    # AND RequireAuthMiddleware enforcement.  See the docstring on
+    # ``enforce_scopes_on_all_requests`` above for the trade-off and why
+    # this flag exists.  Per-tool ``require_scope()`` is the intended
+    # granular pattern in either mode.
+    auth_settings = AuthSettings(
+        issuer_url=AnyHttpUrl(issuer),
+        resource_server_url=AnyHttpUrl(resource),
+        required_scopes=resolved_scopes if enforce_scopes_on_all_requests else None,
+    )
+
+    return AuthplaneAuthResult(
+        token_verifier=token_verifier,
+        auth=auth_settings,
+        client=client,
+    )

authplane_mcp-0.1.0/authplane_mcp/url_elicitation.py

@@ -0,0 +1,42 @@
+"""URL elicitation primitive for the MCP adapter.
+
+The factory function :func:`authplane_mcp.authplane_mcp_auth` wraps the
+``AuthplaneClient`` it returns so that ``client.exchange()`` consent errors
+auto-translate into MCP ``-32042`` (URL elicitation required) before user
+tool code sees them.  This module exposes the underlying conversion as a
+small primitive for unusual flows where users build a consent error outside
+the wrapped client and want to raise the MCP-shaped error themselves.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from authplane.errors import ConsentRequiredError
+from mcp.shared.exceptions import UrlElicitationRequiredError
+from mcp.types import ElicitRequestURLParams
+
+
+def to_url_elicitation_required_error(
+    error: BaseException,
+) -> UrlElicitationRequiredError | None:
+    """Map a :class:`ConsentRequiredError` with a ``consent_url`` to MCP -32042.
+
+    Returns ``None`` for any other input — non-consent errors and consent
+    errors without a ``consent_url`` are not translatable.  Callers then
+    re-raise the original exception unchanged.
+    """
+    if not isinstance(error, ConsentRequiredError) or not error.consent_url:
+        return None
+
+    return UrlElicitationRequiredError(
+        elicitations=[
+            ElicitRequestURLParams(
+                mode="url",
+                url=error.consent_url,
+                elicitationId=str(uuid4()),
+                message=error.describe(),
+            )
+        ],
+        message=str(error),
+    )

authplane_mcp-0.1.0/authplane_mcp/verifier.py

@@ -0,0 +1,71 @@
+"""AuthplaneTokenVerifier - MCP SDK TokenVerifier backed by AuthplaneResource.
+
+Bridges the Authplane core SDK with the official MCP Python SDK's
+``TokenVerifier`` interface, delegating all JWT validation to
+``AuthplaneResource`` and mapping results to MCP's ``AccessToken``.
+"""
+
+from authplane import AuthplaneError, AuthplaneResource
+from mcp.server.auth.provider import AccessToken, TokenVerifier
+
+
+class AuthplaneTokenVerifier(TokenVerifier):
+    """MCP SDK TokenVerifier backed by AuthplaneResource.
+
+    Validates JWTs once per request via the core Authplane SDK and returns
+    an MCP ``AccessToken`` populated with standard OAuth 2.1 claims
+    (``client_id``, ``scopes``, ``expires_at``, ``resource``).
+
+    All security-critical logic (signature verification, claim validation,
+    JWKS caching, SSRF protection) is handled by the core SDK. This class
+    is a thin adapter that maps between the two interfaces.
+    """
+
+    def __init__(self, verifier: AuthplaneResource) -> None:
+        """Initialize the token verifier.
+
+        Args:
+            verifier: A fully initialized ``AuthplaneResource`` instance,
+                typically created via ``AuthplaneClient.create()`` and
+                ``client.resource()``.
+        """
+        self._verifier = verifier
+
+    @property
+    def verifier(self) -> AuthplaneResource:
+        """The underlying ``AuthplaneResource`` instance."""
+        return self._verifier
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Validate a JWT and return an MCP AccessToken.
+
+        Called by the MCP server once per authenticated request. Delegates
+        to ``AuthplaneResource.verify()`` for all validation, then maps the
+        resulting ``VerifiedClaims`` to an MCP ``AccessToken``.
+
+        Args:
+            token: The raw JWT string (the server strips ``'Bearer '``
+                before calling this method).
+
+        Returns:
+            ``AccessToken`` on successful validation with ``token``,
+            ``client_id``, ``scopes``, ``expires_at``, and ``resource``
+            fields populated. Returns ``None`` on any validation failure
+            (the MCP server responds with 401).
+        """
+        try:
+            claims = await self._verifier.verify(token)
+        except AuthplaneError:
+            return None
+
+        # AccessToken.resource must be a string. Since audience is a list,
+        # take the first one (standard JWT behavior when multiple audiences are present).
+        resource = claims.audience[0]
+
+        return AccessToken(
+            token=token,
+            client_id=claims.client_id,
+            scopes=list(claims.scopes),
+            expires_at=claims.expires_at,
+            resource=str(resource),
+        )

authplane_mcp-0.1.0/demo/README.md

@@ -0,0 +1,65 @@
+# Calculator Service Example
+
+A minimal MCP server demonstrating Authplane JWT authentication with per-tool scope enforcement and RFC 8693 token exchange surfaced via MCP URL elicitation.
+
+The server exposes three tools:
+
+| Tool | Per-tool scope |
+|------|---------------|
+| `add` | `tools/add` |
+| `multiply` | `tools/multiply` |
+| `consent_demo` | `tools/consent_demo` |
+
+`consent_demo` calls `client.exchange(...)` to swap the inbound user token for a Google Calendar token. The local authserver responds with `consent_required` plus a `consent_url`; the wrapped client translates that into `UrlElicitationRequiredError` (JSON-RPC `-32042`), and the MCP client surfaces the URL elicitation prompt to the user.
+
+## Scope advertisement and consent prompt
+
+This demo passes `enforce_scopes_on_all_requests=True` to `authplane_mcp_auth`. With that flag set, the three demo scopes are listed in the Protected Resource Metadata's `scopes_supported` and your MCP client requests all of them when minting a token — so the **OAuth consent prompt asks you to grant all three scopes at once**. Approve all of them; declining any one will cause the AS to reject the token.
+
+This is a workaround for an MCP reference SDK limitation: `AuthSettings` has no separate "supported" field, so the SDK uses `required_scopes` for both PRM advertisement and request-layer enforcement. The flag is opt-in; production deployments that don't need OAuth-discovery clients to know the scope list can leave it off and rely solely on per-tool `require_scope()`.
+
+The per-tool `require_scope()` calls remain in the demo on purpose — they are the granular enforcement pattern, become no-ops under request-level enforcement, and stay correct once the upstream SDK gains a separate "supported" field and the flag goes away.
+
+## Prerequisites
+
+- Python 3.11+
+- The **Authplane authserver** running locally — from a checkout of the `authserver` repo, run:
+
+  ```bash
+  bash demo/mcp-demo-server-start.sh
+  ```
+
+  This starts the auth server on `http://localhost:9000`, registers the calculator client and scopes, and creates a demo user.
+
+## Run
+
+```bash
+cd authplane-mcp
+./demo/run.sh
+```
+
+`run.sh` creates a virtualenv, installs dependencies, and starts the server on port `8080`. All demo credentials are pre-configured — no additional setup needed.
+
+## How it works
+
+```
+MCP Client ──Bearer JWT──► mcpserver.py (port 8080)
+                                │
+                                ├─ authplane_mcp_auth()
+                                │    • Discovers JWKS from ISSUER_URL
+                                │    • Validates JWT signature, aud, exp
+                                │    • Introspects token (revocation check)
+                                │
+                                └─ require_scope("tools/add")
+                                     • Reads token from request context
+                                     • Raises PermissionError if scope missing
+                                       → MCP returns isError=true to client
+```
+
+## Key patterns shown
+
+**`authplane_mcp_auth()`** — wires up the verifier and auth settings in one call. By default the `scopes` list is **not** propagated to the PRM — see "Scope advertisement and consent prompt" above for why this demo opts in via `enforce_scopes_on_all_requests=True` and what that means.
+
+**`require_scope(scope)`** — call at the top of any tool handler to enforce per-tool scope. If the token is missing the scope the tool returns an error result (`isError: true`) to the MCP client.
+
+**`client.exchange(...)`** — performs RFC 8693 token exchange. If the AS responds with `consent_required` and a `consent_url`, the wrapped client raises `UrlElicitationRequiredError` (JSON-RPC `-32042`) instead of `ConsentRequiredError`, and the MCP client surfaces it as a URL elicitation prompt — no try/except needed in the tool handler. See `consent_demo` in `mcpserver.py`.