Skip to main content

mcp-owner-auth

Single-user OAuth 2.1 for self-hosted MCP servers that you use from claude.ai and the Claude mobile app.

It turns an MCPServer (MCP Python SDK v2) into a Streamable HTTP app where the server is both authorization server and resource server, for exactly one owner and one client:

  • One static OAuth client (for claude.ai: Add custom connector → Use your own OAuth client). No dynamic client registration, no client ID metadata documents.
  • Login with username + password (argon2id) + TOTP, CSRF protection, no JavaScript, rate limit (5 failures per IP per 15 min) and a lockout after 20 failures in 24 h.
  • PKCE S256 only, exact redirect_uri allowlist, RFC 8707 resource binding, RFC 9207 iss.
  • Opaque tokens stored only as SHA-256 hashes: access tokens 1 h, refresh tokens 30 days, rotated on every use, reuse of a used refresh token revokes the whole family.
  • auth revoke-all takes effect on the next request, without a restart.
  • Host-header allowlist, body limit, timeout, optional IP allowlist on /mcp and /token, JSON-lines audit log of tool calls (no results, no secrets), strict security headers.
  • Fallback static_bearer mode for clients that can send a fixed Authorization header.

It is meant for personal, self-hosted servers. It is not a general-purpose identity provider. See SECURITY.md for the threat model and design.

Use

from pathlib import Path
from mcp_owner_auth import OwnerAuthConfig, serve
from mcp_owner_auth import cli as auth_cli

config = OwnerAuthConfig.from_env(
    "MY_MCP",  # reads MY_MCP_PUBLIC_URL, MY_MCP_AUTH_MODE, ...
    state_dir=Path("/data"),
    app_name="My Data",
    command="my-mcp",
    scope="mydata:read",
    consent="read-only access to your data",
)
serve(server, config, host="0.0.0.0", port=8000)  # server: your MCPServer

Add the CLI to your own argparse:

auth_cli.add_parser(subcommands)
...
if args.command == "auth":
    sys.exit(
        auth_cli.run(
            args.action,
            auth_db=state / "auth.db",
            app_name="My Data",
            command="my-mcp",
            force=args.force,
            redirect_uris=args.redirect_uri,
        )
    )

Then my-mcp auth init (username, password, TOTP QR code, prints the client ID and secret once), auth status, auth rotate-client, auth revoke-all, auth unlock.

Environment

Variable Meaning
<PREFIX>_PUBLIC_URL public base URL, e.g. https://mcp.example.com (https; http only for localhost)
<PREFIX>_AUTH_MODE oauth (default) or static_bearer
<PREFIX>_STATIC_BEARER_FILE file with the static token (at least 32 characters)
<PREFIX>_ALLOWED_CIDRS optional comma-separated allowlist for /mcp and /token
<PREFIX>_CLIENT_IP_HEADER e.g. CF-Connecting-IP; only when the app is reachable solely through that proxy

Routes

/mcp, /.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server, /authorize, /token, /login, /consent, /healthz.

License

Apache-2.0

Releasing

Releases go to PyPI from GitHub Actions with trusted publishing (no API token anywhere). Bump version in pyproject.toml, commit, then push a matching tag (git tag v0.1.1 && git push origin v0.1.1). One-time setup on pypi.org: a trusted publisher for project mcp-owner-auth, owner EmilbMadsen, repository mcp-owner-auth, workflow release.yml, environment pypi.

Metadata

Release files for mcp-owner-auth 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-owner-auth 0.1.1
File Size Uploaded Provenance Actions
mcp_owner_auth-0.1.1.tar.gz 19.4 kB With provenance Details for mcp_owner_auth-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-owner-auth 0.1.1
File Interpreter ABI Platform Actions
mcp_owner_auth-0.1.1-py3-none-any.whl Python 3 none any Details for mcp_owner_auth-0.1.1-py3-none-any.whl

Total release size: 41.6 kB

Release files / mcp_owner_auth-0.1.1.tar.gz

Download URL mcp_owner_auth-0.1.1.tar.gz
Size 19.4 kB
Tags Source
SHA-256 checksum
How to use checksums
8e63823a0fb0d457ee092c084a6f38813b88e646e76d5f6426daaf39276dcf48
BLAKE2b-256 checksum
How to use checksums
287e66a90fe35416593affe9830c882c29a458a4a998dcb46bdba7e543ac26dd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / mcp_owner_auth-0.1.1-py3-none-any.whl

Download URL mcp_owner_auth-0.1.1-py3-none-any.whl
Size 22.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ea08bccc1c7796b605a4f7f5006b571f66119dcaa5d39f8ebb2b97f291cf6330
BLAKE2b-256 checksum
How to use checksums
51b59f354c3249240547fcbeea7d2bf5b76d959aeaed2b7bb455975234b5b5f8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for mcp-owner-auth 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcp_owner_auth-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page