Operations
Day-to-day running of the Gateway: who can administer it, what the console shows, and what to monitor.
Who Can Administer It
Administrator access is decided by your Britive tenant. A caller holding the
mcp.server.manage permission is an administrator - the Gateway checks this with the
platform and caches the answer per user.
There is no local administrator list, no static admin token, and no way to disable the check. Grant or revoke the permission on the tenant. If someone should have admin access and doesn’t, that is a tenant permission question, not a Gateway configuration question.
The Gateway’s root URL is a sign-in page, and the console is its only destination. Choose Login with Britive and, if your identity holds the permission, you land in the console directly - there is no second button to press.
If it does not, you are returned to that page with a notice saying the console was refused, and a Sign out button.
If the platform is unreachable, a cached answer is served for up to
adminCheckStaleIfErrorSeconds (default 600), after which access is denied.
Use of a stale answer is recorded in the audit trail and shown in the console, so it
is never silent.
The Admin Console
| Section | What it shows |
|---|---|
| Gateway Status | Health, the tenant it serves, and the cache windows in force. |
| Activity | Counters for calls, catalogues served, and checkouts since this container started, plus the result of the last platform sync. Sync Now runs a pass on demand. |
| Mounted Backends | Every backend with its status - pending, verified, issue, or Refused with a reason - plus its tools and platform OAuth configuration. |
| Audit Events | The searchable audit trail, filterable by actor, action, backend, tool, decision, outcome, session, and time range. |
| Settings | Every setting this container is running, read-only, with its source, whether it differs from the default, and when it was last fetched. |
Expanding an audit row shows the full event, including any inspection verdict with each finding’s severity, detector, message, and matched snippet, ordered worst-first.
The Settings tab
Settings are managed on the Britive platform, so the console shows them rather than editing them - the platform is the single writer, and an editable second copy would immediately raise the question of which one wins.
Filter by name, or narrow to values that differ from their default, which is the quickest way to see what someone actually decided about this pool.
A staleness notice on this tab means the last re-fetch from the platform failed. The values shown are still the ones in force, but they may no longer match the tenant portal. Without the notice you would have no way to tell the two apart.
Secrets - the pool encryption key, the metrics token, the SIEM webhook headers - show
as (set) or (not set) and never as a value. Whether a credential is configured is
all an operator checking a deployment needs.
Monitoring
Health checks
| Endpoint | Purpose |
|---|---|
GET /healthz | Liveness. Point your load balancer here. |
GET /readyz | Readiness. |
curl -sk https://mcp-gateway.example.internal/healthzMetrics
Prometheus metrics are served at GET /metrics, and are off by default. Turn on
metricsEnabled (“Serve Prometheus metrics”) in the pool’s Integrations group, and
set metricsToken alongside it.
When disabled, the route returns 404 rather than 403, so a disabled endpoint does not advertise its own existence.
With metricsToken set, /metrics requires Authorization: Bearer <token>, compared
in constant time. Leave it empty only if the port is reachable solely by your
collector. The token is stored encrypted on the pool and never shown again once saved.
What is exported:
- Counters - tool calls by backend and outcome, catalogues served, credential checkouts, downstream token fetches, rate-limit rejections, platform syncs, admin checks, client registrations, and audit events by category.
- Gauges - backends by verification state, mounted tool count, and audit webhook queue depth.
Labels are low-cardinality and non-identifying: no user identifiers, no per-tool series, no arguments. “Who called what” is answered by the audit trail, which is access-controlled - deliberately not by metrics, which usually are not.
What to alert on
| Signal | Why it matters |
|---|---|
/healthz failing on a replica | That container is out of rotation. |
Backends in issue state | Tools that should work are failing with BACKEND_UNAVAILABLE. |
| Audit webhook queue depth rising | Your SIEM is not keeping up; events are dropped when the buffer fills. |
| Rate-limit rejections climbing | Either a runaway agent loop, or limits set too tight for real usage. |
| Platform sync failures | Backend changes and settings changes on the tenant are not reaching the Gateway. The console flags the settings as stale. |
The Admin API
The console’s actions are available over HTTP for automation:
| Route | Purpose |
|---|---|
GET /admin/status | Gateway status. |
GET /admin/backends | Every mounted backend and its state. |
POST /admin/backends/sync | Run a synchronisation pass. |
GET /admin/audit | Query the audit log. Supports the console’s filters, including session_id. |
GET /admin/settings/resolved | The settings in force as JSON, with each value’s source, whether it differs from the default, and any staleness reason. |
GET /admin/backends is the fastest way to answer “is this backend platform-synced,
and what does the Gateway think its endpoint is” when a tool is missing.
Routine Tasks
Adding a backend. Register the MCP server on your tenant, then Sync Now. See Backends.
Removing a backend. Remove it from the tenant. The Gateway re-derives its whole view on each sync, so it disappears on the next pass.
Changing a setting. Edit the gateway pool in the tenant portal. Every container in
the pool applies the change on its next sync, within five minutes by default, and
records it in the audit trail as settings.refresh. Nothing needs restarting.
Rotating the pool token. Issue a new token for the pool, roll it through your replicas, and retire the old one. Sessions are unaffected: the encryption key is minted separately from the token precisely so that rotating one does not sign everyone out.
Upgrading. Pull the new image and restart replicas one at a time. Migrations run on startup. See Upgrades.