mcp-core-auth 0.2.1__tar.gz

mcp_core_auth-0.2.1/.env.example

@@ -0,0 +1,45 @@
+# mcp-core configuration
+#
+# Copy to .env (gitignored) and fill in values for your deployment.
+# All vars are MCP_CORE_*-prefixed so they don't collide with other libs
+# in your process. The minimal_server example reads these directly via
+# pydantic-settings — see examples/minimal_server/config.py.
+
+# --- Product identity ---
+MCP_CORE_PRODUCT_NAME=myapp
+
+# --- Logto auth (cloud or self-hosted) ---
+# Cloud:        https://your-tenant.logto.app
+# Self-hosted:  https://auth.example.com  (see deploy/logto/)
+MCP_CORE_LOGTO_ENDPOINT=https://your-tenant.logto.app
+MCP_CORE_LOGTO_API_RESOURCE=https://api.example.com
+
+# Set to 1 in local dev to accept "Bearer dev-bypass" as a valid token.
+# NEVER set this in production.
+MCP_CORE_DEV_AUTH_BYPASS=0
+
+# --- MCP OAuth (for Claude Code / Inspector) ---
+# Created by deploy/logto/bootstrap-apps.py or Logto admin console.
+MCP_CORE_MCP_LOGTO_APP_ID=
+MCP_CORE_MCP_LOGTO_APP_SECRET=
+
+# --- DCR (Dynamic Client Registration) ---
+# M2M app + role used to register per-client OAuth apps on demand.
+# On self-hosted Logto, the management token endpoint is on port 8443:
+#   MCP_CORE_LOGTO_MGMT_TOKEN_ENDPOINT=https://auth.example.com:8443/oidc/token
+# On Logto Cloud, omit it (defaults to <endpoint>/oidc/token).
+MCP_CORE_LOGTO_MGMT_APP_ID=
+MCP_CORE_LOGTO_MGMT_APP_SECRET=
+# MCP_CORE_LOGTO_MGMT_TOKEN_ENDPOINT=
+
+# --- MongoDB (for user/credit storage) ---
+MCP_CORE_MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/
+MCP_CORE_DB_NAME=myapp
+
+# --- Stripe billing (test mode keys for dev) ---
+MCP_CORE_STRIPE_SECRET_KEY=sk_test_...
+MCP_CORE_STRIPE_PRICE_ID=price_...
+MCP_CORE_STRIPE_WEBHOOK_SECRET=whsec_...
+MCP_CORE_STRIPE_METER_EVENT=mcp_tool_calls
+MCP_CORE_FREE_CREDITS=30
+MCP_CORE_BILLING_SUCCESS_URL=https://myapp.example.com/billing/success

mcp_core_auth-0.2.1/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.env.live
+tests/.env.live
+deploy/logto/bootstrap-apps.json
+.pytest_cache/
+htmlcov/
+.coverage
+*.so
+.mypy_cache/

mcp_core_auth-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to mcp-core
+
+Thanks for considering a contribution. mcp-core is a small library — issues and PRs are both welcome.
+
+## Reporting bugs
+
+Before filing, please:
+
+1. Reproduce on the latest `main`.
+2. Check open issues for duplicates.
+3. Include: Python version, mcp-core version, a minimal repro, and the full traceback (not just the last line).
+
+## Proposing changes
+
+For anything more than a one-line fix, open an issue first to discuss the approach. mcp-core has a deliberately narrow scope (auth + billing + MCP mount + tool logging for FastAPI MCP servers), and not every feature fits.
+
+## Pull requests
+
+- One topic per PR. Refactors and bug fixes go in separate PRs.
+- Include tests for new behavior. The `tests/` suite runs on mocks; if your change needs live services, add a `tests/live/` test guarded by `RUN_LIVE_TESTS=1`.
+- Keep public API changes backward-compatible when possible. If you must break something, call it out in the PR description.
+- Match the existing style — no formatter is enforced, but the code aims for short modules with docstrings on public classes and short inline comments only where intent isn't obvious.
+
+## Local development
+
+```bash
+git clone https://github.com/swapp1990/mcp-core
+cd mcp-core
+pip install -e ".[dev]"
+pytest                              # mock-based tests, run anywhere
+RUN_LIVE_TESTS=1 pytest tests/live  # needs tests/.env.live with real Logto/Mongo/Stripe
+```
+
+For OAuth flow changes, the reference deployment is `deploy/logto/` — spin up a local Logto in docker and run `verify.py` to confirm mcp-core still talks to it.
+
+## Auth providers
+
+mcp-core is currently Logto-specific. PRs that add support for additional OIDC providers (Auth0, Keycloak, generic OIDC) are welcome — the cleanest path is extracting a `BaseOIDCProvider` interface from `LogtoAuth` rather than dropping a parallel class. Open an issue first to discuss the shape.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same MIT license as the rest of the repo.

mcp_core_auth-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 swapp1990
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_core_auth-0.2.1/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: mcp-core-auth
+Version: 0.2.1
+Summary: Auth, billing, and logging infrastructure for MCP-first servers.
+Project-URL: Homepage, https://github.com/swapp1990/mcp-core
+Project-URL: Repository, https://github.com/swapp1990/mcp-core
+Author: swapp1990
+License-Expression: MIT
+License-File: LICENSE
+Keywords: auth,billing,fastapi,logto,mcp,stripe
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: motor>=3.3.0
+Requires-Dist: pyjwt>=2.8.0
+Requires-Dist: stripe>=8.0.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mongomock-motor>=0.0.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-core
+
+[![Release](https://img.shields.io/github/v/release/swapp1990/mcp-core)](https://github.com/swapp1990/mcp-core/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Auth, billing, and logging infrastructure for MCP-first servers. Sits between your product code and [fastapi-mcp](https://github.com/tadata-org/fastapi-mcp).
+
+```
+Your MCP Server  (product-specific tool handlers)
+     mcp-core    (auth, billing, logging, health)
+    fastapi-mcp  (MCP protocol: JSON-RPC, SSE, tool discovery)
+      FastAPI
+```
+
+## Install
+
+```bash
+pip install mcp-core-auth
+```
+
+The package is published as `mcp-core-auth` on PyPI (the bare `mcp-core` name is held by an unrelated project), but the import path is unchanged:
+
+```python
+from mcp_core import MCPCore
+```
+
+## Quick Start
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request
+from mcp_core import MCPCore
+
+core = MCPCore(
+    product_name="my-product",
+    logto_endpoint="https://your-tenant.logto.app",
+    logto_api_resource="https://api.my-product.app",
+    mongodb_uri="mongodb+srv://...",
+    stripe_secret_key="sk_test_...",
+    stripe_price_id="price_...",
+    free_credits=30,
+    tool_costs={"browse": 0, "generate": 5},
+    read_only_tools={"browse"},
+)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await core.connect_db()
+    yield
+
+app = FastAPI(lifespan=lifespan)
+core.install_routes(app)  # /health, /api/billing/credits, webhook, OAuth metadata
+
+@app.post("/api/mcp/generate")
+async def generate(request: Request):
+    user = await core.auth_and_bill(request, "generate")
+    result = do_generation()
+    await core.log_tool_call(request, "generate", user=user, duration_ms=1200)
+    return result
+```
+
+All config can also come from `MCP_CORE_*` environment variables.
+
+## Modules
+
+### Auth (`mcp_core.auth.LogtoAuth`)
+
+Logto JWT validation via JWKS. Creates MongoDB user records on first auth.
+
+- RS256/ES256/ES384/ES512 support
+- 30s clock skew tolerance
+- Race-condition-safe user upsert
+- Dev bypass (`Bearer dev-bypass`) for local development
+- M2M token rejection for paid tools
+
+### Billing (`mcp_core.billing.StripeBilling`)
+
+Stripe metered billing with free credit fallback.
+
+- Free credits deducted first
+- Stripe metered subscription as fallback
+- 402 with Checkout URL when no credits and no subscription
+- Webhook handler for `checkout.session.completed` and `customer.subscription.created`
+
+### Tool Logging (`mcp_core.tool_logging.ToolLogger`)
+
+Audit trail for every MCP tool call. Writes to MongoDB `tool_logs` collection.
+
+### Health (`mcp_core.health.HealthCheck`)
+
+Composable health check builder. Supports sync and async checks with timeouts.
+
+## Testing
+
+```bash
+# Mock tests (no external services)
+pip install -e ".[dev]"
+pytest tests/ -v
+
+# Live tests (requires .env.live with real credentials)
+RUN_LIVE_TESTS=1 pytest tests/live/ -v
+```
+
+## Contributing
+
+Bug reports and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and [SECURITY.md](SECURITY.md) for vulnerability reporting.
+
+Auth provider abstraction (Auth0, Keycloak, generic OIDC) is tracked in [#1](https://github.com/swapp1990/mcp-core/issues/1) — discussion-first.
+
+## License
+
+MIT

mcp_core_auth-0.2.1/README.md

@@ -0,0 +1,113 @@
+# mcp-core
+
+[![Release](https://img.shields.io/github/v/release/swapp1990/mcp-core)](https://github.com/swapp1990/mcp-core/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Auth, billing, and logging infrastructure for MCP-first servers. Sits between your product code and [fastapi-mcp](https://github.com/tadata-org/fastapi-mcp).
+
+```
+Your MCP Server  (product-specific tool handlers)
+     mcp-core    (auth, billing, logging, health)
+    fastapi-mcp  (MCP protocol: JSON-RPC, SSE, tool discovery)
+      FastAPI
+```
+
+## Install
+
+```bash
+pip install mcp-core-auth
+```
+
+The package is published as `mcp-core-auth` on PyPI (the bare `mcp-core` name is held by an unrelated project), but the import path is unchanged:
+
+```python
+from mcp_core import MCPCore
+```
+
+## Quick Start
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request
+from mcp_core import MCPCore
+
+core = MCPCore(
+    product_name="my-product",
+    logto_endpoint="https://your-tenant.logto.app",
+    logto_api_resource="https://api.my-product.app",
+    mongodb_uri="mongodb+srv://...",
+    stripe_secret_key="sk_test_...",
+    stripe_price_id="price_...",
+    free_credits=30,
+    tool_costs={"browse": 0, "generate": 5},
+    read_only_tools={"browse"},
+)
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await core.connect_db()
+    yield
+
+app = FastAPI(lifespan=lifespan)
+core.install_routes(app)  # /health, /api/billing/credits, webhook, OAuth metadata
+
+@app.post("/api/mcp/generate")
+async def generate(request: Request):
+    user = await core.auth_and_bill(request, "generate")
+    result = do_generation()
+    await core.log_tool_call(request, "generate", user=user, duration_ms=1200)
+    return result
+```
+
+All config can also come from `MCP_CORE_*` environment variables.
+
+## Modules
+
+### Auth (`mcp_core.auth.LogtoAuth`)
+
+Logto JWT validation via JWKS. Creates MongoDB user records on first auth.
+
+- RS256/ES256/ES384/ES512 support
+- 30s clock skew tolerance
+- Race-condition-safe user upsert
+- Dev bypass (`Bearer dev-bypass`) for local development
+- M2M token rejection for paid tools
+
+### Billing (`mcp_core.billing.StripeBilling`)
+
+Stripe metered billing with free credit fallback.
+
+- Free credits deducted first
+- Stripe metered subscription as fallback
+- 402 with Checkout URL when no credits and no subscription
+- Webhook handler for `checkout.session.completed` and `customer.subscription.created`
+
+### Tool Logging (`mcp_core.tool_logging.ToolLogger`)
+
+Audit trail for every MCP tool call. Writes to MongoDB `tool_logs` collection.
+
+### Health (`mcp_core.health.HealthCheck`)
+
+Composable health check builder. Supports sync and async checks with timeouts.
+
+## Testing
+
+```bash
+# Mock tests (no external services)
+pip install -e ".[dev]"
+pytest tests/ -v
+
+# Live tests (requires .env.live with real credentials)
+RUN_LIVE_TESTS=1 pytest tests/live/ -v
+```
+
+## Contributing
+
+Bug reports and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and [SECURITY.md](SECURITY.md) for vulnerability reporting.
+
+Auth provider abstraction (Auth0, Keycloak, generic OIDC) is tracked in [#1](https://github.com/swapp1990/mcp-core/issues/1) — discussion-first.
+
+## License
+
+MIT

mcp_core_auth-0.2.1/SECURITY.md

@@ -0,0 +1,34 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please **do not** file public GitHub issues for security vulnerabilities.
+
+Email the maintainer directly with:
+
+- A description of the issue and its impact.
+- Steps to reproduce, or a proof-of-concept.
+- Affected versions, if known.
+- Your name / handle for credit (optional).
+
+Contact: report security issues via [GitHub's private vulnerability reporting](https://github.com/swapp1990/mcp-core/security/advisories/new) on this repo.
+
+You should expect an acknowledgement within a few business days. If the report is valid, we'll work on a fix and coordinate disclosure with you. Critical issues that can be exploited remotely will be prioritized.
+
+## Scope
+
+In scope:
+- Auth bypass in `LogtoAuth` (token validation, JWKS handling, audience/issuer checks).
+- Privilege escalation through DCR (`LogtoDCR`).
+- Billing bypass in `StripeBilling` (credit accounting, webhook signature verification).
+- Information disclosure via `ToolLogger` or health endpoints.
+- Anything that lets an unauthenticated caller invoke a paid tool, or one user act as another.
+
+Out of scope:
+- Vulnerabilities in upstream dependencies (Logto, Stripe, FastAPI, MongoDB) — please report those upstream. We'll bump pins once a fix is released.
+- Self-inflicted misconfiguration of a downstream deployment (e.g. publishing your `.env` to a public S3 bucket).
+- Issues in `examples/` or `deploy/logto/demos/` — those are illustrative, not production code.
+
+## Supported versions
+
+Only the latest tagged minor version receives security fixes. Pre-1.0, the API may change between minors — pin your version and watch the changelog.

mcp_core_auth-0.2.1/deploy/logto/.env.example

@@ -0,0 +1,14 @@
+# Copy to .env next to the compose files (and to /opt/apps/logto-docker/.env on the prod server).
+
+# --- Required in prod ---
+# Public domain that fronts Logto via host nginx (see nginx-auth.conf.template).
+LOGTO_DOMAIN=auth.example.com
+LOGTO_ENDPOINT=https://auth.example.com
+LOGTO_ADMIN_ENDPOINT=https://auth.example.com:8443
+
+# Postgres password for the Logto DB. Generate with: openssl rand -hex 32
+POSTGRES_PASSWORD=
+
+# --- Optional ---
+# Pin Logto to a specific version instead of :latest
+# LOGTO_IMAGE=svhd/logto:1.23.0

mcp_core_auth-0.2.1/deploy/logto/README.md

@@ -0,0 +1,218 @@
+# Self-hosted Logto for mcp-core
+
+The reference Logto deployment that every mcp-core consumer can stand up on
+their own infrastructure. Runs Logto + Postgres in docker-compose. Works
+identically in local dev and prod; only the public URLs + port bindings
+differ between `docker-compose.local.yml` and `docker-compose.prod.yml`.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `docker-compose.yml` | Base: Logto + Postgres. No port bindings, no public URLs. |
+| `docker-compose.local.yml` | Dev override: binds 3001/3002, sets `ENDPOINT=http://localhost:3001`. |
+| `docker-compose.prod.yml` | Prod override: binds 3011/3012, reads public URLs from `.env`. |
+| `.env.example` | All env vars (`LOGTO_DOMAIN`, `LOGTO_ENDPOINT`, `LOGTO_ADMIN_ENDPOINT`, `POSTGRES_PASSWORD`). |
+| `nginx-auth.conf.template` | Host nginx vhost — render `__DOMAIN__` with your auth host. |
+| `bootstrap-apps.example.json` | Schema for product definitions consumed by `bootstrap-apps.py`. |
+| `bootstrap-apps.py` | Idempotent CLI that creates SPA + API resource + DCR M2M apps from a config. |
+| `verify.py` | End-to-end compatibility check: mcp-core talking to self-host. |
+| `deploy.sh` | One-shot prod deploy script (rsync compose files + `up -d`). |
+
+## Local dev
+
+```bash
+cd deploy/logto
+cp .env.example .env
+# Set POSTGRES_PASSWORD (generate with: openssl rand -hex 32).
+# LOGTO_ENDPOINT/ADMIN/DOMAIN aren't used by the local override — they
+# only matter for prod.
+
+docker compose -f docker-compose.yml -f docker-compose.local.yml up -d
+
+# Wait for boot, then run the end-to-end compatibility check:
+py verify.py
+```
+
+Admin console is at http://localhost:3002 — the first visit to that URL
+becomes the root admin. Close the browser tab after creating the account;
+no other "who is the admin" gate exists.
+
+Teardown (wipes the volume):
+```bash
+docker compose -f docker-compose.yml -f docker-compose.local.yml down -v
+```
+
+## Production deploy
+
+First-time server prep (once):
+
+1. **DNS**: A record `auth.example.com -> <server IP>`.
+2. **Nginx**: render the template with your domain, then enable + provision TLS:
+   ```bash
+   sed 's/__DOMAIN__/auth.example.com/g' nginx-auth.conf.template \
+     | sudo tee /etc/nginx/sites-available/auth.example.com >/dev/null
+   sudo ln -s /etc/nginx/sites-available/auth.example.com \
+              /etc/nginx/sites-enabled/auth.example.com
+   sudo certbot --nginx -d auth.example.com
+   sudo ufw allow 8443/tcp     # admin tenant port
+   ```
+3. **Docker**: install `docker` + `docker compose v2` on the server.
+
+Then from your workstation:
+```bash
+export LOGTO_SERVER=root@1.2.3.4
+export LOGTO_LIVE_URL=https://auth.example.com
+export LOGTO_SSH_KEY=~/.ssh/id_rsa     # optional — defaults to ~/.ssh/id_rsa
+./deploy.sh
+```
+
+The script rsyncs the compose files, generates `.env` if missing
+(`LOGTO_DOMAIN/ENDPOINT/ADMIN_ENDPOINT/POSTGRES_PASSWORD`), pulls images,
+brings the stack up, and smoke-tests the public URL.
+
+## Bootstrapping apps in Logto
+
+Once the stack is running and you've created the admin user, you can either
+click through the admin console or run `bootstrap-apps.py` to create your
+SPA + API resource + (optional) MCP-DCR M2M app idempotently.
+
+```bash
+cp bootstrap-apps.example.json bootstrap-apps.json     # gitignored
+# Edit bootstrap-apps.json with your products' redirect URIs, API resource,
+# scopes, etc.
+
+py bootstrap-apps.py \
+    --endpoint https://auth.example.com \
+    --admin    https://auth.example.com:8443 \
+    --config   bootstrap-apps.json \
+    --mgmt-secret "$(ssh root@1.2.3.4 'docker exec logto-docker-postgres-1 \
+        psql -U logto -d logto -t -A \
+        -c \"SELECT secret FROM applications WHERE id='\''m-default'\''\"')"
+```
+
+It prints a paste-ready `.env` snippet (`LOGTO_APP_ID`, `MCP_LOGTO_APP_ID/SECRET`,
+etc.) for each product at the end.
+
+## mcp-core compatibility notes
+
+Self-hosted Logto (OSS) is mostly drop-in compatible with Logto Cloud but
+has a few surface differences that affect how mcp-core talks to it.
+
+### Admin-tenant endpoint split
+
+OSS runs two logical tenants in one process:
+- **default** tenant (port 3001) — end-user sign-ins and app-scoped APIs.
+- **admin** tenant (port 3002) — admin console + Management API auth.
+
+Management-API M2M credentials (like the seeded `m-default` app) must be
+exchanged for tokens at the **admin** OIDC endpoint, not the user-facing
+one. This differs from Cloud, where everything lives on a single host.
+
+`LogtoDCR` accepts an optional `mgmt_token_endpoint` parameter to handle
+this:
+
+```python
+from mcp_core.dcr import LogtoDCR
+
+dcr = LogtoDCR(
+    logto_endpoint="https://auth.example.com",
+    mgmt_app_id="<m2m-app-id>",
+    mgmt_app_secret="<m2m-app-secret>",
+    mgmt_api_resource="https://default.logto.app/api",
+    # OSS-only: Management tokens are issued by the admin tenant.
+    mgmt_token_endpoint="https://auth.example.com:8443/oidc/token",
+)
+```
+
+### Admin must live on its own origin (not a path prefix)
+
+The admin SPA in Logto OSS hardcodes its API fetches as `/api/*` relative
+to the origin root — it does NOT use a base path derived from
+`ADMIN_ENDPOINT`. If you serve admin at `auth.example.com/admin`, the
+browser's `/api/*` calls land on the *user* tenant and fail.
+
+Workable separations, cleanest first:
+- **Different port on the same host** (what this repo uses):
+  `ENDPOINT=https://auth.example.com` and
+  `ADMIN_ENDPOINT=https://auth.example.com:8443`. Same cert, no new DNS,
+  open one firewall port.
+- **Subdomain**: `admin-auth.example.com`. Needs a DNS record + cert.
+
+The port-based setup only requires the nginx vhost to have a second
+`server { listen 8443 ssl; ... }` block that proxies to the admin
+container port. No path rewrites, no Host spoofing.
+
+When `mgmt_token_endpoint` is unset (default), `LogtoDCR` uses
+`f"{endpoint}/oidc/token"` — the Cloud behavior — so existing deployments
+see no regression.
+
+### ADMIN_ENDPOINT must be container-reachable
+
+Logto performs service-to-service JWKS fetches using `ADMIN_ENDPOINT`
+verbatim (see `koa-auth.getAdminTenantTokenValidationSet`). If the container
+cannot resolve/connect to that URL from *inside itself*, any Management-API
+request 500s with `ECONNREFUSED`.
+
+Two ways this manifests:
+- **Local dev:** using port remaps like `3012:3002` makes the container's
+  `localhost:3012` unreachable from inside the container. Fix: the local
+  override binds `3001:3001`/`3002:3002` 1:1 so `localhost:3001/3002`
+  resolves correctly from both host and container.
+- **Prod:** the public domain resolves publicly, but the prod override adds
+  `extra_hosts: - "${LOGTO_DOMAIN}:host-gateway"` to keep the internal
+  round-trip local (container -> host nginx -> container) instead of
+  depending on external DNS + egress.
+
+### Registration endpoint never advertised
+
+Logto (both Cloud and self-host) does **not** return `registration_endpoint`
+in `/oidc/.well-known/openid-configuration`, and `/oidc/register` 404s.
+mcp-core's `install_routes()` fills this gap by mounting `/oauth/register`
+and advertising it in the proxied metadata doc — works identically on
+self-host.
+
+### Management API resource
+
+For the single OSS tenant named `default`, the Management API resource
+indicator is `https://default.logto.app/api`. This is a logical string
+(not a reachable URL) — it's only used as the `resource`/`audience` value.
+
+## Verify compatibility
+
+`verify.py` is the source of truth for "does self-hosted Logto still work
+with mcp-core". It covers:
+
+- OIDC discovery (issuer, jwks_uri, authorize/token endpoints)
+- JWKS format + supported JWT algorithms
+- Management-API token exchange via admin tenant
+- `LogtoDCR.register()` end-to-end creating a Native/PKCE app
+- JWT signed by Logto validated by `LogtoAuth._get_jwks_client()`
+
+Run it after any Logto version bump:
+
+```bash
+py verify.py                                   # local compose
+py verify.py --endpoint https://auth.example.com \
+             --admin    https://auth.example.com:8443 \
+             --mgmt-secret <from-logto-admin-console>
+```
+
+## Post-deploy config (admin console)
+
+Either run `bootstrap-apps.py` (above) or do these once the stack is up:
+
+1. **SPA apps** — one per frontend. Note the client IDs.
+2. **API resources** — e.g. `https://app.example.com`. Add the scopes the product uses.
+3. **M2M app for DCR** — one per backend that needs Dynamic Client
+   Registration. Grant it the "Management API access for default" role.
+4. **Google social connector** — create a Google Cloud OAuth 2.0 client,
+   redirect URI `https://auth.example.com/callback/<connector-id>`.
+5. **SMTP / SES email connector** — see `provision-ses.sh` for AWS SES.
+6. **Sign-in experience** — enable email + password, plus any social connectors.
+
+Then update each product's frontend + backend `.env`:
+- Frontend: `LOGTO_CONFIG.endpoint = 'https://auth.example.com'`
+- Backend: `LOGTO_ENDPOINT=https://auth.example.com`,
+  `LOGTO_API_RESOURCE=...`, `LOGTO_DCR_MGMT_APP_ID/SECRET`, and
+  `LOGTO_DCR_MGMT_TOKEN_ENDPOINT=https://auth.example.com:8443/oidc/token`.

mcp_core_auth-0.2.1/deploy/logto/bootstrap-apps.example.json

@@ -0,0 +1,21 @@
+{
+  "_comment": "Example product config for bootstrap-apps.py. Copy to bootstrap-apps.json (gitignored) and edit. One entry per product (frontend + API + optional MCP-DCR M2M app).",
+  "products": [
+    {
+      "name": "myapp",
+      "spa_app_name": "MyApp (frontend)",
+      "redirect_uris": [
+        "http://localhost:5173/callback",
+        "https://app.example.com/callback"
+      ],
+      "post_logout_uris": [
+        "http://localhost:5173",
+        "https://app.example.com"
+      ],
+      "api_resource": "https://app.example.com",
+      "api_resource_name": "MyApp API",
+      "scopes": ["myapp:read", "myapp:write"],
+      "mcp_dcr_app_name": "MyApp MCP-DCR"
+    }
+  ]
+}