Claude Code, Codex & Inspector

Clients that run locally and can perform HTTP MCP OAuth themselves connect straight to the Gateway. There is no relay to install.

This covers Claude Code, Codex, and MCP Inspector. All three need the same thing: network access to the Gateway, and a browser for the sign-in flow.

If your Gateway uses a private certificate authority, install that CA in your operating system’s trust store before adding the server. Do not reach for a TLS-bypass option.

Claude Code

Run this on a machine that can reach the Gateway:

claude mcp add --transport http britive-gateway https://mcp-gateway.example.internal/mcp

Then open Claude Code and run /mcp. Select britive-gateway and complete the browser OAuth flow. Claude Code stores and refreshes its own Gateway token from then on.

To confirm:

claude mcp list

Codex

codex mcp add britive-gateway --url https://mcp-gateway.example.internal/mcp

Then sign in:

codex mcp login britive-gateway

This opens the browser OAuth flow. Confirm the registration with:

codex mcp get britive-gateway

If your organization manages Codex configuration centrally, use its approved MCP configuration mechanism rather than bypassing local policy with these commands.

MCP Inspector

Inspector is the best tool for seeing the raw protocol - what the tool list actually contains, and what a call actually returns.

npx @modelcontextprotocol/inspector

Create a Streamable HTTP connection to:

https://mcp-gateway.example.internal/mcp

Let Inspector follow protected-resource metadata and OAuth discovery, and sign in. Use a localhost callback registered with your Britive OAuth client - Inspector’s default is http://localhost:6274/oauth/callback/debug.

Inspector runs in a browser and calls the Gateway cross-origin, so its origin has to be named in browserCorsAllowedOrigins (“Browser origins”) on the gateway pool. The list is empty by default, and an empty list is what disables CORS - there is no separate switch. Leave it empty in production unless a browser-based client genuinely needs it.

If your tenant blocks localhost callbacks at the WAF or client-registration layer, the OAuth flow fails before the Gateway ever receives a token - the Gateway logs nothing because nothing reached it.

What the Gateway Advertises

These clients discover the OAuth flow automatically from metadata the Gateway serves. Useful when debugging a client that will not complete sign-in:

/.well-known/oauth-protected-resource
/.well-known/oauth-protected-resource/mcp
/.well-known/oauth-authorization-server

The Gateway acts as its own authorization server and brokers to your Britive tenant.

Verify

Whichever client you used:

Confirm the tool list

You should see your backends’ tools, each prefixed with its backend identifier - aws_list_buckets rather than list_buckets.

Confirm policy is being applied

Sign in as a user with narrower Britive policy. The list should be shorter. This is the check worth doing, because it verifies the Gateway is doing its actual job rather than merely proxying.

Call a tool

The result comes back, and the call appears in the admin console’s audit view within seconds.

Troubleshoot

Symptom	Cause	Fix
OAuth flow never completes	Callback URI not registered with your Britive OAuth client	Register the client’s localhost callback.
OAuth fails before the Gateway sees anything	Tenant WAF blocking localhost callbacks	Raise it with your Britive administrator - the Gateway is not involved.
Inspector cannot connect at all	CORS disabled	Add Inspector’s origin to Browser origins on the gateway pool. An empty list means CORS is off.
TLS verification error	Private CA not trusted	Install the CA in the OS trust store.
Connected, but no tools	Policy allows nothing, or policy evaluated as the wrong identity	Ask your administrator to run the doctor probe.
A tool returns `AUTH_REQUIRED`	Backend needs authorizing	Open the connect URL carried in the error on the Britive platform, then retry the same call.

Connecting an Agent Instead of a Person

An agent or workload that cannot perform a browser OAuth flow can present a Britive-issued token directly:

Authorization: <scheme> <token>

This accepts an AI identity token, a workload token, or an API token, and requires allowAgentTokens to be enabled on the Gateway - it is off by default. An agent can also act for a named person with an X-On-Behalf-Of header, if your tenant authorizes that delegation.

See Agent tokens and delegation.

Next Steps

Why a Tool Might Fail

The error codes, and what resolves each one.

Claude Desktop

Uses the relay instead of a direct connection.

Last updated on August 24, 2026

Claude Desktop