Backends

A backend is an MCP server the Gateway proxies to. This section covers how backends arrive, how they are verified, and how each one gets its credential.

Backends Come From Your Tenant

Backends are not configured on the Gateway. An administrator defines an MCP server on the Britive platform, and the Gateway picks it up through synchronisation - the same route its own settings arrive by.

    flowchart LR
    Admin["Administrator"]
    Tenant["Britive tenant<br/>MCP server records"]
    GW["Gateway"]
    B["Backend MCP server"]

    Admin -->|"defines MCP server"| Tenant
    GW -->|"syncs every 5 min<br/>or on Sync Now"| Tenant
    GW -->|"mounts and probes"| B
  

This is deliberate. The tenant’s MCP server catalogue is the allowlist: there is one place that decides which servers exist, and it is the same place that decides who may use their tools.

The Gateway re-derives its whole view on every sync, so removing a server from the tenant removes it here on the next pass. backendSyncIntervalSeconds on the gateway pool (default 300) is the upper bound on how long a change takes to appear; Sync Now in the admin console does the same pass immediately.

Tool Names Are Prefixed

Each backend has a tool prefix, defaulting to its identifier. Every tool that backend publishes is namespaced with it:

Two backends can therefore both offer a query tool without colliding. Keep the identifier stable and URL-safe - it becomes the mounted backend’s name, so changing it renames every tool that backend publishes.

Mounting and Verification

Mounting a backend is an in-memory registration, so a tenant with many MCP servers becomes serviceable immediately. Each backend is then probed in the background and carries a status:

An issue often resolves itself once tools are published on the tenant or a network path is opened, which is why it is retried rather than treated as terminal.

Where Credentials May Be Sent

A backend URL is not just an address - every tool call forwards the calling user’s credential to it. The Gateway applies a destination policy when a backend is mounted:

• HTTPS is required by default. A credential would otherwise cross a plaintext connection in a header.
• Private network addresses are allowed by default, because reaching servers the platform cannot see is a primary purpose of the Gateway.
• Loopback, link-local, multicast, and reserved addresses are always refused, and this is not configurable. That includes cloud instance metadata endpoints such as 169.254.169.254.

An optional hostname allowlist narrows it further. See Where credentials may be sent.

The Two Auth Strategies

Every backend uses one of two strategies. This determines what a user has to do before a tool works, so it is worth being clear about which one you are deploying.

Britive checkout

The Gateway obtains temporary credentials from a Britive checkout for that user and injects them into each backend request as HTTP headers. The backend reads the credential from the request, uses it, and stores nothing - it stays stateless.

    sequenceDiagram
    participant U as User's client
    participant G as Gateway
    participant P as Britive platform
    participant B as Backend

    U->>G: tools/call aws_list_buckets
    G->>P: Check out credentials for this user
    P-->>G: Temporary credentials
    G->>B: tools/call + checkout credentials in headers
    B->>B: Use credentials, discard
    B-->>G: Result
    G-->>U: Result
  

Use this for backends you run: a database adapter, a cloud adapter, an internal service. The user does nothing beyond holding the right Britive policy - there is no authorization step and no consent screen.

A credential longer than checkout_header_max_value_length (default 2048) is rejected rather than truncated, because a truncated secret fails at the backend with a misleading error. Raise it for a backend that legitimately needs a long session token or a PEM-encoded key.

Downstream OAuth

The user authorizes the backend once, and the Britive platform manages the resulting token. Every OAuth flow to the SaaS provider runs on the platform: administrators connect the provider there, and users authorize there. The Gateway never runs the flow.

    sequenceDiagram
    participant U as User's client
    participant G as Gateway
    participant P as Britive platform
    participant B as Backend (SaaS MCP)

    U->>G: tools/call atlassian_getJiraIssue
    G->>P: Token for this user and backend?
    alt Not connected
        P-->>G: Not connected
        G-->>U: AUTH_REQUIRED + connect URL
    else Connected
        P-->>G: Access token
        G->>B: tools/call + Authorization: Bearer
        B-->>G: Result
        G-->>U: Result
    end
  

Use this for SaaS MCP servers such as Atlassian. The token is opaque to the Gateway - how the platform obtained it is invisible at injection time. It is cached for the token’s lifetime, and a 401 from the backend on a cached token triggers a single refetch before the call fails.

A user who has not connected yet gets AUTH_REQUIRED naming the backend, and the error itself carries the platform URL to complete the connection. The tools stay in the catalogue throughout - see The catalogue is policy.

Which one to choose

Both strategies are always available: there is no setting that turns one off. Removing one would silently unmount every backend configured that way on the tenant, which is a way to break your own deployment with no upside.

What a deployment can restrict is where a backend may live at all - see Backend Policy.

Explore