| name | mcp-runtime-platform-public |
| description | Configure and debug public MCP Runtime installs with MCP_PLATFORM_DOMAIN, Let's Encrypt, registry/mcp/platform hostnames, registry TLS auth, and platform UI ingress. Use for --with-tls setup, ACME failures, DNS NXDOMAIN, registry forward-auth, or production hostname routing — not for local Kind test-mode (use qa-cluster-bringup). |
MCP Runtime — public platform (domain, TLS, DNS)
Hostname model
With export MCP_PLATFORM_DOMAIN=example.com (apex only, no https://):
| Role | Host |
|---|
| Registry (push/pull ingress) | registry.example.com |
| MCP servers (default host-based) | mcp.example.com |
| Dashboard / API / Grafana path | platform.example.com |
Override individual hosts with MCP_REGISTRY_INGRESS_HOST, MCP_MCP_INGRESS_HOST, MCP_PLATFORM_INGRESS_HOST.
Operator may set MCP_DEFAULT_INGRESS_HOST=mcp.<domain> from platform domain env.
Expected URLs (after DNS + TLS)
- Dashboard:
https://platform.<domain>/ (API at /api/v1/* via Traefik). Grafana at /grafana via mcp-sentinel-platform-observability + sentinel-admin-auth@file (admin cookie or admin x-api-key). Prometheus stays internal — port-forward only for backend debug.
- Registry:
https://registry.<domain>/v2/ (admin auth via registry-admin-auth@file → /api/v1/registry/authz)
- MCP server:
https://mcp.<domain>/<server-name>/mcp (path-based; set spec.publicPathPrefix and MCP_PATH)
Default MCPServer ingress class: traefik.
TLS setup
./bin/mcp-runtime setup --with-tls --acme-email <addr>
DNS requirements
- A/AAAA (or CNAME) for
registry., mcp., and platform. → same ingress IP/LB
- Port 80 → Traefik for HTTP-01 before certs issue
- Typos (
regsitry, platfrom) break matching certificates
Certificates
registry/registry-cert → registry/registry-tls (only supported owner for that Secret; registry Ingress must not use cert-manager.io/cluster-issuer on the Ingress itself)- Platform UI:
mcp-sentinel-platform-tls in mcp-sentinel via mcp-sentinel-platform-ui Ingress
- Bundled HTTPS may create
cert-manager/mcp-runtime-ca; nodes must trust tls.crt for image pulls
- Private CA without ACME:
config/cert-manager/ and omit --acme-email
Registry and image pull (public)
MCP_REGISTRY_HOST — public alias; do not let it override node pull endpoint incorrectly- HTTPS public:
MCP_REGISTRY_ENDPOINT=registry.<domain>
- Platform pull secrets:
MCP_PLATFORM_IMAGE_PULL_SECRET in mcp-runtime and mcp-sentinel when using external auth registries
- Tenant pulls: platform creates
mcp-runtime-registry-pull on mcp-workload SA per team namespace
OIDC / Google sign-in
Non-test public TLS (--platform-mode public --with-tls) requires GOOGLE_CLIENT_ID / MCP_GOOGLE_CLIENT_ID, or all of OIDC_ISSUER, OIDC_AUDIENCE, OIDC_JWKS_URL. Setup preserves existing values in mcp-sentinel-config on reruns.
k3s-specific
Use .codex/skills/k3s-public-ops/SKILL.md, docs/k3s-deployment-runbook.md, and docs/cluster-readiness.md for scripted deploy, node registries.yaml, and multitenancy smoke.
Troubleshooting cross-links
General failures (ImagePullBackOff, UI 404, cert-manager pods missing): .codex/skills/mcp-runtime-troubleshooting/reference.md.
