Running Open MCP Portal
For operators: what Open MCP Portal needs, how to install it with Docker Compose or Kubernetes, and how to run it.
Open MCP Portal is one stateless binary, open-mcp-portal, in one container image. It needs:
- PostgreSQL 17: the only state. Every replica shares it, including rate-limit counters.
- An OpenID Connect identity provider for sign-in.
- TLS in front of it:
APP_URLmust be https (an ingress or reverse proxy terminates TLS). - Two secrets you generate:
ENCRYPTION_KEYandAPI_KEY_PEPPER.
There is no worker, cache, queue or object storage. The binary serves the web app, the management API, the MCP endpoints, the OAuth endpoints and the background loops (health checks, signing-key rotation, retention, usage rollups).
Pre-1.0
Open MCP Portal v0.1.0 isn't released yet, and no container image is published: build the image from the repository (make docker). The docs follow the main branch until the release is tagged.
| Command | Does |
|---|---|
open-mcp-portal serve | The web app, APIs, MCP endpoints and background loops (the default) |
open-mcp-portal migrate | Applies database migrations and exits |
open-mcp-portal doctor | Checks the configuration, PostgreSQL, migrations and keys (Health and doctor) |
open-mcp-portal rotate-keys | Re-encrypts stored secrets after an ENCRYPTION_KEY change (Secrets and key rotation) |
open-mcp-portal version | Prints the version |
Install with Docker Compose
The image, the demo, and a single-instance install.
Install on Kubernetes
The Kustomize base and example overlay.
Configuration
Every setting, with its default.
Secrets and key rotation
The encryption key, the pepper, and rotating both.
Migrations and upgrades
Forward-only migrations and rolling upgrades.
Scaling
Replicas, background loops and the database.
Health and doctor
Probes, graceful shutdown and the doctor command.
Metrics
Prometheus metrics and useful alerts.
Backups
What to back up, and what a backup is useless without.
Security model
What the portal protects, and how.