Authplane Python SDK MCP server

Authplane Python SDK

OAuth 2.1 JWT validation and token operations for Python resource servers, with first-class adapters for Model Context Protocol (MCP) servers.

Why Authplane

• One call wires up everything. authplane_auth() (FastMCP) or authplane_mcp_auth() (MCP) does RFC 8414 metadata discovery, fetches the JWKS, validates RFC 9068 access tokens, and serves RFC 9728 Protected Resource Metadata — unpacked straight into your MCP server.
• Secure defaults. Asymmetric algorithms only, strict claim validation, SSRF-hardened fetches, background JWKS refresh, and a circuit breaker around the AS — out of the box.
• Standards-aligned. OAuth 2.1, DPoP (RFC 9449), Token Exchange (RFC 8693), Token Introspection (RFC 7662), Token Revocation (RFC 7009), Resource Indicators (RFC 8707).

Quickstart — FastMCP server with auth

import asyncio
from authplane_fastmcp import authplane_auth
from fastmcp import FastMCP
from fastmcp.server.auth import require_scopes


async def main() -> None:
    result = await authplane_auth(
        issuer="https://auth.company.com",
        base_url="https://mcp.company.com",
        scopes=["tools/query"],
    )
    mcp = FastMCP("My Server", **result)

    @mcp.tool(auth=require_scopes("tools/query"))
    def query(sql: str) -> str:
        return f"Ran: {sql}"  # replace with your real handler

    try:
        await mcp.run_async(transport="http", port=8080)
    finally:
        await result.aclose()


asyncio.run(main())

That's a complete, secure, standards-compliant MCP resource server. Swap authplane-fastmcp for authplane-mcp to use the official MCP Python SDK instead — see each adapter's README for the equivalent snippet.

Packages

Package	Install	Purpose
authplane-sdk	pip install authplane-sdk	Framework-agnostic JWT validation, AS metadata discovery, and token operations
authplane-mcp	pip install authplane-mcp	Adapter for the official MCP Python SDK
authplane-fastmcp	pip install authplane-fastmcp	Adapter for FastMCP

Adapter packages depend on authplane-sdk, so installing one adapter brings the core SDK along. Adapter packages export only the adapter-specific glue (authplane_auth, AuthplaneAuthResult, AuthplaneTokenVerifier, etc.); core types (ASCredentials, FetchSettings, IntrospectionRevocation, errors) come from authplane, and TokenExchangeOptions / TokenResponse from authplane.oauth.

Requires Python 3.11+.

Compatibility

Tested against authserver 0.2.0. Introspection-based revocation (IntrospectionRevocation) requires authserver ≥ 0.1.2 and a confidential resource-server client that is either the issuing client or a runtime-client of the Resource — see the user guide.

Capabilities

Standards and RFCs

• OAuth 2.1 (draft-ietf-oauth-v2-1)
• RFC 8414 — Authorization Server Metadata discovery
• RFC 9068 — JWT Profile for OAuth 2.0 Access Tokens
• RFC 7662 — Token Introspection
• RFC 7009 — Token Revocation
• RFC 8693 — Token Exchange
• RFC 8707 — Resource Indicators
• RFC 9449 — DPoP (sender-constrained access tokens)
• RFC 9728 — OAuth 2.0 Protected Resource Metadata
• RFC 6750 — Bearer Token Usage
• RFC 7234 — HTTP caching semantics on discovery responses
• RFC 7519 / 7517 — JWT and JWKS

Security

• JWT signature, issuer, audience, exp / nbf / iat, and typ (at+jwt) validation; required claims enforced (sub, client_id, exp, iat, jti)
• Algorithm-confusion defenses: only RS256 and ES256 (asymmetric) are accepted; none, HS256, HS384, HS512 are always rejected at construction
• AS metadata hardening: discovered issuer must match configured issuer exactly; required endpoints must be present
• SSRF hardening on outbound HTTP: DNS pinning, private/loopback/link-local/cloud-metadata IP blocking, HTTPS-only, response size limits, no redirects
• HTTPS-only by default with a dev_mode toggle for localhost and private networks
• JWKS resilience: stale-cache fallback, background refresh at 80% TTL, force-refresh on kid miss, coordinated fetches
• Inbound DPoP proof verification: binding, replay, htm / htu / ath checks
• Outbound DPoP proof generation with nonce retry and pluggable nonce storage
• Circuit breaker around authorization-server calls
• Token caching with TTL buffers

Framework integrations

• Official MCP Python SDK → authplane-mcp
• FastMCP → authplane-fastmcp

Observability

• Structured logging (logging module) across JWKS refresh, metadata discovery, circuit breaker transitions, token verification, and DPoP binding outcomes
• Strict Pyright typing and immutable validated claims

Documentation

• Core SDK: authplane/README.md · User Guide
• MCP adapter: authplane-mcp/README.md · User Guide
• FastMCP adapter: authplane-fastmcp/README.md · User Guide
• Release history: CHANGELOG.md
• Security policy: SECURITY.md
• Contributing: CONTRIBUTING.md
• Release policy: RELEASE_POLICY.md

License

Apache-2.0 — see LICENSE.