Quickstart

This guide brings up a working Gateway connected to your Britive tenant, signs you in, and gets a client talking to it. It is the fastest way to see the whole system end to end, and nothing you learn here is wasted - the same container image runs in production.

Overview

By the end you’ll have:

A Gateway serving MCP over HTTPS at https://localhost:8443/mcp.
A local Postgres holding its state, surviving restarts.
The admin console open in your browser, signed in with your Britive identity.
A client connected, listing the tools your policy allows.

This stack is for evaluation on one machine. For a real deployment see Compose, AWS ECS, or Kubernetes.

Before You Begin

You need:

Docker with Compose.
A Britive tenant name - the bare subdomain (acme) or a full URL.
A gateway pool token from the Britive admin console.
A Britive identity holding the mcp.server.manage permission, to reach the admin console.
Access to the gateway pool in the tenant portal, or someone who has it. The Gateway takes its settings from that pool, and one of them has to be set before sign-in works.

The stack contains only the Gateway, its database, and a TLS edge. Backends come from your tenant, and so does the Gateway’s own configuration - there is no local file for either.

Bring Up the Stack

Download the Compose file

Download docker-compose.quickstart.yaml - the Gateway, Postgres, and a TLS edge.

Save it as docker-compose.yaml in an empty directory.

Set your tenant values

Create a .env file beside it:

.env

TENANT=acme
GATEWAY_POOL_TOKEN=<your-pool-token>

That is the whole file. Everything else - the public base URL, audit settings, inspection, rate limits - lives on the gateway pool your token belongs to, and the container fetches it at startup.

There is no secret to generate. The key protecting stored tokens and sessions is minted by the platform for the pool, so your sign-in survives a restart and every replica reads the same data with nothing to keep in sync.

Point the pool at the TLS edge

In the Britive tenant portal, open the gateway pool your token belongs to and set Public base URL to:

https://localhost:8443

Clients arrive on 8443 through the TLS edge, and OAuth redirect and resource URLs are built from this value - so it has to be the edge’s address, not the container’s port.

Leave it unset and the Gateway falls back to http://localhost:8080 with a warning, which is the container’s own port rather than the one your browser uses. Sign-in then fails at the callback.

Start it

docker compose up -d

The TLS edge issues its own certificate from a local certificate authority, so there is nothing to install and no certificate to supply. The Gateway itself publishes no host port - clients reach it through the edge on 8443, so there is no plaintext bypass of the thing the edge exists to provide.

Confirm it is healthy

curl -sk https://localhost:8443/healthz

An unhealthy start is almost always an unreachable tenant or a rejected pool token. The logs say which:

docker compose logs gateway --since 2m

Sign In to the Admin Console

The Gateway’s root page exists for one purpose: reaching the admin console. Your MCP servers and their connections are managed on the Britive platform, not here.

Open the Gateway in a browser

Go to https://localhost:8443/.

Your browser will warn once that the certificate’s issuer is unknown. That is expected for a local evaluation - the edge signed its own certificate. Accept it and continue.

Sign in with Britive

Choose Login with Britive and complete the OAuth flow against your tenant.

If your identity holds the mcp.server.manage permission, you land in the admin console directly - there is no second button to press.

If it does not, you are returned to the sign-in page with a notice explaining that the console was refused, and a Sign out button. Administrator access is decided entirely by the platform: there is no local admin list and no static admin token. Grant the permission on the tenant and sign in again.

Register Your First Backend

Backends are defined on your Britive tenant and arrive at the Gateway through synchronisation. Nothing is configured locally.

Create an MCP server on your tenant

In the Britive admin console, create an MCP server pointing at your backend’s MCP URL - for example https://mcp.atlassian.com/v1/mcp - and give it a stable identifier, which becomes the backend’s name and its tool prefix.

The endpoint must be HTTPS. The platform rejects a plaintext endpoint, and the Gateway refuses to mount a backend it can only reach over http:// - a credential would cross that connection in a header.

Pull it into the Gateway

In the Gateway’s admin console, choose Sync Now. The Gateway also re-syncs on its own every five minutes, so this only saves you the wait.

The backend appears under Mounted Backends with a status of pending while it is probed in the background, then verified. A status of issue means it could not be reached or listed - see Troubleshooting.

Verify

Connect a client and confirm the tools appear. The quickest check is MCP Inspector, because it shows you the raw protocol:

npx @modelcontextprotocol/inspector

Create a Streamable HTTP connection to:

https://localhost:8443/mcp

Let Inspector follow the advertised OAuth flow and sign in.

Inspector runs in a browser and calls the Gateway cross-origin, which needs CORS enabled - it is off by default. See MCP Inspector.

A successful run looks like this:

Every tool is namespaced by its backend’s prefix - atlassian_getJiraIssue rather than getJiraIssue.
Signing in as an identity with narrower Britive policy shows a shorter list. This is the check worth doing twice - it is the whole point of the Gateway.
Calling a tool returns a real result, and the call appears under Audit Events in the admin console within seconds.

Troubleshoot

Symptom	Cause	Fix
`TENANT is required` at startup	`.env` missing or not beside the Compose file	Create `.env` with `TENANT` and `GATEWAY_POOL_TOKEN`.
Container restarts repeatedly	Tenant unreachable, or the pool token was rejected	Fetching settings from the tenant is fatal at startup by design. Check `docker compose logs gateway` - the message names both causes.
Sign-in fails at the callback	The pool’s Public base URL is unset or wrong	Set it to `https://localhost:8443`, then wait for the next sync or restart the container.
Signed in, but the console is refused	Identity lacks `mcp.server.manage`	Grant the permission on the tenant, then sign in again.
Admin console empty, no backends	Nothing registered on the tenant, or sync hasn’t run	Register an MCP server on the tenant, then Sync Now.
Backend stuck on `issue`	Unreachable endpoint, or no tools published	See Troubleshooting.
Tool list empty for a real identity	Policy allows nothing	Check that identity’s policy on the tenant.
Browser warns about the certificate	Expected - the edge signs its own	Accept it, or put your own certificate in front for a longer-lived setup.

Restarting Without Losing Your Work

The database is a named volume, so audit history and issued tokens survive a down and up:

docker compose down
docker compose up -d

docker compose down -v deletes the volume, and with it your audit history, issued tokens, and sessions.

Next Steps

Connect a Client

Claude Desktop, Claude Code, Codex, and agents.

Real Deployments

Compose replicas, AWS ECS, or Kubernetes.

Configuration

Move from environment variables to a config file.

Last updated on August 24, 2026

Docker Compose