fastmcp-seaworthy

Production building blocks for FastMCP servers: serve one server under several public hostnames, each a full OAuth identity, and keep the OAuth proxy's state across restarts and rotations of the upstream client secret.

A FastMCP server that runs fine on a laptop can still fail in production: it answers OAuth discovery under one hostname only, and with an OAuthProxy-based auth provider (OIDCProxy, AWSCognitoProvider, GoogleProvider, AzureProvider, ...) every container restart signs every user out. This library closes both gaps with the same settings and the same code in every server that uses it.

• What Is This For
• Installation
• Usage
  • Serving several hostnames
  • Surviving restarts
  • Both together
• Configuration
  • Environment variables
  • DynamoDB table
• API Reference
  • serve_http
  • build_host_router
  • OAuthStateSettings
  • build_client_storage
  • ClientStorage
  • HostRouter
  • Helpers
• Contributing
• License

What Is This For

Typical use cases:

• Reaching one MCP server under an alias domain, for clients whose networks block the primary TLD.
• Running an MCP server with an OAuthProxy-based provider on Kubernetes, where the container filesystem — and with it FastMCP's default OAuth state store — does not survive a restart.
• Rotating the upstream IdP's client secret without invalidating every issued token and every client registration.
• Running several replicas of one MCP server that share their OAuth state.

Installation

pip install fastmcp-seaworthy
# or, with uv:
uv add fastmcp-seaworthy

The DynamoDB store backend needs the dynamodb extra:

pip install 'fastmcp-seaworthy[dynamodb]'
# or, with uv:
uv add 'fastmcp-seaworthy[dynamodb]'

Requires Python 3.10+ and FastMCP 4.

Usage

Serving several hostnames

A FastMCP auth provider is built around one base_url, which it advertises everywhere: in the protected-resource and authorization-server metadata, as the redirect_uri sent to the IdP, and in the tokens it mints. FastMCP never derives it from the request, so a provider can answer as one hostname only. Adding a second host at the ingress fixes TLS and routing, but the server keeps sending clients to the first hostname — the one the alias exists to avoid.

serve_http builds one app per base URL, each with its own provider, over one shared FastMCP server, and routes requests between them on the Host header:

import asyncio
import os

from fastmcp import FastMCP
from fastmcp.server.auth.providers.aws import AWSCognitoProvider
from fastmcp_seaworthy import serve_http, split_base_urls

# No auth= here: it is supplied per hostname below.
mcp = FastMCP(name="my-server")


def auth_for(base_url: str) -> AWSCognitoProvider:
    return AWSCognitoProvider(
        user_pool_id=os.environ["COGNITO_USER_POOL_ID"],
        aws_region=os.environ["COGNITO_AWS_REGION"],
        client_id=os.environ["COGNITO_CLIENT_ID"],
        client_secret=os.environ["COGNITO_CLIENT_SECRET"],
        base_url=base_url,
    )


asyncio.run(
    serve_http(
        mcp,
        # e.g. "https://mcp.example.io,https://mcp.example.com"
        split_base_urls(os.environ["BASE_URLS"]),
        auth_for,
        host="0.0.0.0",
        port=8080,
    )
)

The first base URL is canonical: it answers requests with no or an unknown Host header, such as container health probes addressing the pod IP. Register {base_url}/auth/callback as an allowed redirect URI with your IdP for every entry. With a single base URL, the same code serves one identity.

Surviving restarts

An OAuthProxy keeps state — the clients registered through DCR, the upstream IdP's tokens, and the mapping from the tokens it issued to them — and signs its tokens with a signing key. By default FastMCP keeps the state in an encrypted file store under ${FASTMCP_HOME} and derives the signing key from the upstream client secret. A container restart then loses all state, and a secret rotation strands it.

OAuthStateSettings reads a stable signing key and an external store from the environment, build_client_storage builds that store, encrypted the way FastMCP encrypts its own, and provider_kwargs hands both to the provider:

from fastmcp_seaworthy import OAuthStateSettings, build_client_storage

settings = OAuthStateSettings.from_env()
storage = build_client_storage(settings)  # None for FastMCP's default file store

provider = AWSCognitoProvider(
    ...,
    **settings.provider_kwargs(storage),
)

Open the store before serving, so a missing table or missing permissions fail the rollout rather than the first sign-in, and close it afterwards — serve_http does both when given the store.

Both together

Build the store once and share it between the hostnames: they are separate OAuth identities of one deployment, not separate deployments.

async def main() -> None:
    settings = OAuthStateSettings.from_env()
    storage = build_client_storage(settings)

    def auth_for(base_url: str) -> AWSCognitoProvider:
        return AWSCognitoProvider(
            ...,
            base_url=base_url,
            **settings.provider_kwargs(storage),
        )

    await serve_http(
        mcp,
        split_base_urls(os.environ["BASE_URLS"]),
        auth_for,
        client_storage=storage,
        host="0.0.0.0",
        port=8080,
    )


asyncio.run(main())

Configuration

Environment variables

Read by OAuthStateSettings.from_env(). Empty values count as unset.

The values written to an external store are Fernet-encrypted with a key derived from JWT_SIGNING_KEY exactly as FastMCP derives its file store's key, so the store never holds an upstream token in plaintext. An entry written under a different key reads as missing: clients re-register and users sign in again, instead of every request failing.

JWT_SIGNING_KEY is worth setting with the default file store too: it decouples the stored state from the upstream client secret.

DynamoDB table

Credentials and region come from the AWS SDK's usual chain (IRSA or EKS Pod Identity, instance profile, AWS_* environment variables); AWS_ENDPOINT_URL_DYNAMODB points it at DynamoDB Local for testing. Create the table with your infrastructure code:

The server needs dynamodb:DescribeTable, dynamodb:DescribeTimeToLive, dynamodb:GetItem, dynamodb:PutItem and dynamodb:DeleteItem on the table. STORE_DYNAMODB_AUTO_CREATE=true additionally needs dynamodb:CreateTable and dynamodb:UpdateTimeToLive; so does a table without TTL enabled.

API Reference

serve_http

async serve_http(server, base_urls, auth_for, /, *, client_storage=None, show_banner=True, host=None, port=None, log_level=None, path=None, uvicorn_config=None, json_response=None, stateless_http=None, stateless=None, middleware=None, host_origin_protection=None, allowed_hosts=None, allowed_origins=None, session_idle_timeout=None) — serves server under every base URL until uvicorn stops. Mirrors FastMCP.run_http_async: unset keywords fall back to FastMCP's settings, so FASTMCP_* environment variables keep working.

The remaining keywords are those of FastMCP.run_http_async. With host_origin_protection enabled, allowed_hosts must list every public hostname, since one list applies to every identity's app.

build_host_router

build_host_router(server, base_urls, auth_for, /, *, path=None, json_response=None, stateless_http=None, middleware=None, host_origin_protection=None, allowed_hosts=None, allowed_origins=None, session_idle_timeout=None) — builds the HostRouter that serve_http serves, for callers that run the ASGI app themselves. Those callers hold server._lifespan_manager() open around it if the server lifespan must outlive the router, as serve_http does.

OAuthStateSettings

OAuthStateSettings(jwt_signing_key=None, store_backend="file", store_dynamodb_table=None, store_dynamodb_region=None, store_dynamodb_auto_create=False) — the signing key and the store an OAuthProxy keeps its state in. Frozen dataclass; construction raises ValueError for a combination the server could not keep readable.

build_client_storage

build_client_storage(settings) — returns the encrypted ClientStorage the settings select, or None for FastMCP's default file store. Imports no backend dependency for file; raises RuntimeError when the backend's extra is missing.

ClientStorage

Returned by build_client_storage.

HostRouter

HostRouter(apps, canonical_base_url) — an ASGI app dispatching to per-hostname child apps keyed by base URL, and running every child's lifespan under its own. Rejects an empty mapping, two base URLs sharing a hostname, and a canonical base URL that is not among them.

Helpers

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache-2.0 — see LICENSE.