Install the platform

The platform is one Compose project: gateway, credential broker, portal, Keycloak and OpenBao with their databases, behind nginx. Check the requirements first. For a test on one computer without a domain, use Install locally. Without registry access, use the offline packages.

Install

Get the bundle:

git clone https://github.com/aiwcorpo/mcp-platform.git
cd mcp-platform

Copy the certificate chain and the key to certs/ as tls.crt and tls.key.
If a company CA signed the certificate, copy the CA certificate to certs/company-ca.crt.
Copy the environment template:
Terminal window
```
cp platform.env .env
```
Open .env and set the domain:
Terminal window
```
MCP_DOMAIN=mcp.corp.test
```
If https runs on a port other than 443, also set MCP_PUBLIC_ORIGIN=https://<domain>:<port> and MCP_HTTPS_PORT. Without MCP_PUBLIC_ORIGIN the addresses the platform hands out drop the port. All options are in Configure.
Start the platform:
Terminal window
```
docker compose up -d
```
The first start takes a few minutes: the gateway and the broker wait for Keycloak and OpenBao. During that time gateway-init can print warn broker ...: connection refused. This is expected.
Read the log of the init service:
Terminal window
```
docker compose logs init
```
Expected, last line: ok configuration, certificates and secrets are in place. init runs before every start. It checks that the certificate names the domain, that the key fits and that the chain verifies. If something is wrong, it stops the start and prints the reason.
Print the initial password of the first administrator:
Terminal window
```
docker compose run --rm init show admin-password
```
The administrator is mcp-admin (MCP_ADMIN_USERNAME). The password is never written to a log.
Open https://<domain>/auth/realms/mcp/account and sign in as mcp-admin. Keycloak asks for a new password (at least 12 characters) and to set up an OTP in an authenticator app.
Open https://<domain>/. This is the portal. The administration pages ask for a fresh sign-in with the OTP.

Check that it works

Check that every service is running or healthy:
Terminal window
```
docker compose ps
```
Check that the gateway answers through nginx:
Terminal window
```
curl -fsS https://<domain>/.well-known/mcp-jwks.json
```
Expected: a JSON document with keys. If the certificate is from a company CA, add --cacert certs/company-ca.crt.

A second docker compose up -d changes nothing: init keeps every generated value.

The Keycloak bootstrap account

The master realm has a bootstrap administrator for emergencies. Show its password with:

docker compose run --rm init show keycloak-admin

Sign in with it once, right after the installation, and set up its OTP at the console https://<domain>/auth/admin/master/console/. Whoever signs in first with the bootstrap password enrolls that OTP. Platform administrators (group mcp-platform-admin) manage users and groups in the console of the realm mcp, https://<domain>/auth/admin/mcp/console/, with their own account and OTP.

By default both consoles are reachable from every network. To narrow this, edit nginx/keycloak-admin-allow.conf: replace allow all; with one allow <network>; line per network, then deny all;, and run docker compose restart nginx.

Next steps

Add the systems and servers that users will connect to: Servers and Systems.
Create users and groups: Access.
Back up the platform: Backup.

If a service does not start

See Troubleshooting. The most common causes are a certificate that does not name the domain and a missing MCP_DOMAIN in .env.