Claude Desktop
Claude Desktop reaches a private Gateway through the Britive relay - a small extension that runs on your own computer, speaks stdio to Claude Desktop, and forwards traffic to the Gateway over HTTPS.
Why the Relay Exists
Claude Desktop’s custom connectors are hosted: the connection originates from Anthropic’s backend, which cannot see a server on your VPN, your internal DNS, or your laptop. A local extension runs on your machine, so it can.
flowchart LR
CD["Claude Desktop"]
R["Britive relay<br/>(on your computer)"]
G["Britive MCP Gateway<br/>(your network)"]
CD -->|"stdio"| R
R -->|"HTTPS + OAuth"| G
The relay keeps the Gateway private. It holds no credentials of its own beyond its own OAuth cache, which it encrypts on disk automatically.
Before You Begin
You need:
- Claude Desktop installed.
britive-mcp-gateway-relay.mcpbfrom your administrator.- The Gateway URL, ending in
/mcp. - Your organization’s CA certificate as a PEM file, if the Gateway uses a private CA and you cannot install it in your OS trust store.
Install
Open the extension installer
In Claude Desktop, go to Settings → Extensions → Advanced settings → Install Extension.
Select the relay package
Choose the britive-mcp-gateway-relay.mcpb file your administrator gave you.
Configure it
There are only three settings:
| Setting | Value |
|---|---|
| Gateway URL | https://mcp-gateway.example.internal/mcp |
| Custom CA Certificate Path | Path to your organization’s PEM file, if required. Leave empty otherwise. |
| Allow Insecure TLS | Leave off. |
Allow Insecure TLS disables certificate verification entirely. It is a testing-only last resort. Prefer installing your organization’s CA in the operating system trust store, or naming the PEM file above.
Sign-in always uses the Britive browser OAuth flow - there is no static-token mode to configure.
Start a new conversation
Extensions load per conversation, so open a fresh one.
Complete the sign-in in your browser
You do not start the sign-in - the relay does. As soon as it is enabled it tries its cached session silently, and if that cannot be reused it opens your browser to Britive by itself. Sign in with an identity that has MCP access. The relay completes the callback on localhost and retries the request that was waiting.
There is no tool to invoke to sign in. Claude Desktop speaks stdio, so it can never
see the Gateway’s HTTP 401 and can never run an OAuth flow of its own - the relay
acts on that 401 for it, at enablement, on its background poll, and when a tool
call turns out to be unauthenticated.
Confirm your tools loaded
Once you are signed in the relay re-lists the Gateway’s tools and emits a change
notification, so your prefixed business tools appear without a restart -
atlassian_getJiraIssue, aws_list_buckets, and so on.
Verify
- Your backends’ tools appear, each prefixed with its backend identifier.
- A narrower Britive identity sees a shorter list - that confirms the Gateway is applying policy rather than merely proxying.
- Calling a tool returns a real result.
The Relay Publishes No Tools
The relay forwards traffic and nothing else - it adds no tools of its own, and
neither does the Gateway. It reports its own problems through the only channel a
tool call always has: the failed result. Those results use the same
britive_gateway_error envelope the Gateway returns over HTTPS, tagged
"component": "relay", so a client that parses one parses both.
| Code | What it means | What you do |
|---|---|---|
AUTH_REQUIRED | The relay is not signed in to the Gateway. The tool is real and the call was well-formed; it was never sent. | Complete the browser sign-in, then retry the same call. The error says whether a window was actually opened. |
BACKEND_UNAVAILABLE | The relay cannot reach the Gateway at all. | A network or Gateway-availability problem, not an authorization one. Check the URL and your VPN. |
If Allow Insecure TLS is on, every relay failure payload carries a TLS warning. An insecure relay otherwise looks exactly like a healthy one once the startup log has scrolled away.
Troubleshoot
| Symptom | Cause | Fix |
|---|---|---|
AUTH_REQUIRED, and no browser window appeared | Repeated failed logins tripped the relay’s breaker, another relay instance owns the OAuth callback, or the Gateway failed its health preflight | Sign in to Britive, then restart the relay extension in Claude Desktop. The error payload says which of these applied. |
| TLS error | The Gateway’s CA is not trusted | Install your organization’s CA in the OS trust store, or set the relay’s CA PEM path. Do not use insecure TLS in production. |
| New tools do not appear | Claude Desktop is holding an older tool list | The relay polls the Gateway and emits a change notification when the client supports it. Otherwise start a new conversation. |
A tool returns AUTH_REQUIRED naming a backend | That backend is not authorized for you | Open the connect URL in the error on the Britive platform, then retry the same call. This is not a relay sign-in problem, and a browser sign-in to the relay will not fix it. |
| Extension sits dead after coming up before the Gateway | The startup sign-in ran while the Gateway was still down | Nothing to do - the background poll retries and escalates to a browser sign-in once the Gateway answers. |
| Repeated sign-in prompts after restarting | Relay cache unreadable | The relay re-runs the browser login when its cache or key is lost. If it happens every restart, check that ~/.britive/mcp-gateway-relay/ is writable. |
Where the Relay Stores Things
The relay persists its OAuth cache - client registration and refresh tokens - under:
~/.britive/mcp-gateway-relay/The cache is always encrypted at rest with AES-256-GCM, using a key generated automatically and stored alongside it with owner-only permissions. There is no passphrase to configure and no plaintext mode. If the key or cache is lost, the relay simply re-runs the browser login.
Persisting it matters: a transient Gateway error does not start a new login, and restarting does not trigger a fresh OAuth popup.
What the Relay Proxies
The Gateway is a tools-only MCP server: policy, credential injection, inspection
and audit all hang off tool calls, so tools are what it serves and what the relay
forwards - tools/list and tools/call.
The relay also polls the Gateway for tool-list changes and emits local change notifications, so Claude Desktop can pick up new tools without a restart.