Connect a Client
This section connects a caller to a Gateway running on your network - an assistant
someone is driving, or an autonomous agent nobody is watching. The Gateway is a
Streamable HTTP MCP server, so the address you need is its URL plus /mcp:
https://mcp-gateway.example.internal/mcpReplace that with the URL your administrator gave you.
Before You Start
You need:
- Network access to the Gateway - on the VPN, if it requires one.
- A Britive identity with access to the tools you expect to see.
- A browser on the machine running the client, for the sign-in flow. Agents that present a token directly need no browser - see Connecting an agent.
- Your organization’s root CA in the operating-system trust store, if the Gateway uses a private certificate authority.
If a person is driving the client, sign in through OAuth. Do not paste bearer tokens into client configuration and do not disable TLS validation. (An agent presenting a Britive-issued token is a different, supported path - see Connecting an agent - not a workaround for a sign-in that isn’t working.)
If your Gateway is private, on a VPN, or on localhost, do not try to reach it with a hosted connector: the connection would originate from the vendor’s backend, which cannot see your network.
Choose the Right Method
| Your client | Use | Why |
|---|---|---|
| Claude Desktop | The Britive relay | Claude Desktop’s local extensions speak stdio; the relay bridges that to HTTPS and owns the OAuth callback. |
| Claude Code | Direct HTTP | Runs locally and performs HTTP MCP OAuth itself. |
| Codex | Direct HTTP | Runs locally and performs HTTP MCP OAuth itself. |
| MCP Inspector | Direct HTTP | No relay needed. |
| Browser-hosted clients | A supported tunnel or public ingress | A hosted service cannot reach a private Gateway through a relay on a user’s laptop. |
| An autonomous agent or workload | Direct HTTP with a Britive token | No browser is available, so it presents a token on the request instead of signing in. |
The Gateway Publishes No Tools of Its Own
Every tool you receive is a business tool from one of your backends, prefixed with
that backend’s identifier. There are no britive_* status, refresh, or connect
tools. Both things that can go wrong with authorization already have a channel of
their own, so a tool could only be a second, divergent answer to the same question.
| What went wrong | How you find out | What resolves it |
|---|---|---|
| Your Gateway session expired or is missing | HTTP 401 with a WWW-Authenticate header naming the protected-resource metadata URL | Your client runs the OAuth flow. Claude Code, Codex, and Inspector do this themselves; under Claude Desktop the relay does it for you. |
| A backend is not authorized for you | The tool call’s own AUTH_REQUIRED error, with the platform’s connect URL in its payload | Open that URL on the Britive platform, then retry the same call. |
| Your tool list looks stale | Nothing to check - the list is your Britive policy, and it is always valid | Call the tool you actually want. A real call re-asks the platform, so the retry the error asks for is what heals it. |
There is no preflight worth running. A status call would spend a round trip learning
what the next real call tells you for free, and an unauthorized backend is not a
session problem - answering 401 for it would send your client through a sign-in
that succeeds and changes nothing.
Connecting or revoking a downstream provider happens on the Britive platform, not through the Gateway. The Gateway only reports that authorization is missing and names where to fix it.
Why a Tool Might Fail
The tool list you receive comes from your Britive policy and nothing else. A tool being listed means it exists and your policy allows it - whether a given call succeeds is separate.
| Error code | What to do |
|---|---|
AUTH_REQUIRED | Open the connect URL carried in the error, authorize the backend on the Britive platform, then retry the same call. |
POLICY_DENIED | Your Britive policy does not allow this. Ask your administrator. |
BACKEND_UNAVAILABLE | The backend is down or unreachable. Not something you can fix from the client. |
RATE_LIMITED | You are calling too fast. Wait rather than retrying. |
TOOL_UNKNOWN | The name is genuinely absent from your catalogue. Check the spelling. |
See When a call fails for the full picture.
Connecting an Agent or Workload
An agent that cannot open a browser presents a Britive-issued credential directly on the request instead of completing an OAuth flow:
Authorization: <scheme> <token>This accepts an AI identity token, a workload token, or an API token. It requires
allowAgentTokens on the Gateway, which is off by default - with it
disabled, an opaque token is rejected with “gateway session required”.
Everything else is identical to a person’s connection: the same policy decides which tools the agent sees, the same credentials are injected, and the same audit trail records what it did.
An agent can also act for a named person by sending X-On-Behalf-Of: <username>.
Your tenant authorizes that delegation - the Gateway does not - and the audit trail
records the person as the actor while also naming the agent, so a delegated call is
always distinguishable from the person acting directly.
Full details in Agent tokens and delegation.
Staying Secure
- Use HTTPS with a trusted certificate chain. Install your organization’s CA rather than bypassing verification.
- Keep the Gateway on your own network. Do not expose it publicly merely to satisfy a client that would otherwise need a relay.
- Never put tokens or credentials in prompts, configuration files, or support tickets. The Gateway injects what a backend needs at call time, so a caller never has to hold a downstream credential.