DocsUse
Chat apps
Ask claude.ai, ChatGPT and the Gemini app about your code: a context pack for any of them, or BBM-Atlas's tools as a remote MCP connector, signed in with OAuth or an API key.
Two ways in
- A context pack, for any chat app:
bbm-atlas packcopies the code a question needs, as Markdown, to paste in place of whole files. The console's Search page and the VS Code extension's Copy Context for a Chat App… make one too. - Remote MCP, for a chat app that accepts it: a BBM-Atlas on a public HTTPS address (Production) serves its tools at
/mcp, which the app calls as a connector.
What each app accepts
| App | Authentication it offers | Connect BBM-Atlas with |
|---|---|---|
| claude.ai (and Claude Desktop) | OAuth; no authentication; a fixed request header, in beta for some organisations | OAuth, or the API key in x-api-key where the organisation has Request headers |
| ChatGPT | OAuth 2.1, or no authentication | OAuth |
| Gemini app | OAuth: registered by the app itself, or with credentials you enter | OAuth |
| Gemini Enterprise | OAuth 2.0 with a client id and secret entered by hand, or no authentication | OAuth |
Connecting with OAuth
BBM-Atlas is the resource server: it issues no tokens. Your authorization server does - Keycloak, Auth0, Okta, Microsoft Entra ID, Google. A chat app sends the user there to sign in, gets a token for BBM-Atlas, and calls /mcp with it. The authorization server must:
- issue access tokens BBM-Atlas can check: JWTs signed with an asymmetric key it publishes (RS256, ES256, EdDSA…), or opaque tokens it answers about at its introspection endpoint (below);
- name BBM-Atlas in the token's audience:
/mcp's address, or a value you list inBBM_ATLAS_OAUTH_AUDIENCES; - let the chat app in as a client, with its redirect address allowed:
https://claude.ai/api/mcp/auth_callback,https://chatgpt.com/connector_platform_oauth_redirect, or for Gemini Enterprisehttps://vertexaisearch.cloud.google.com/oauth-redirect.
BBM_ATLAS_OAUTH_ISSUER=https://id.example.com/realms/acme # the authorization serverBBM_ATLAS_OAUTH_RESOURCE=https://atlas.example.com/mcp # /mcp's public addressBBM_ATLAS_OAUTH_SCOPES=bbm-atlas # optional: scopes every token must carryBBM_ATLAS_MCP_ALLOWED_HOSTS=atlas.example.comWith the Helm chart, set mcpOAuth.issuer; the resource defaults to the ingress host's /mcp. bbm-atlas oauth check fetches the issuer's discovery document and keys and shows what clients will see; --token <a token> says whether a real token is accepted, and as whom.
An unauthenticated call to /mcp is refused with 401 and a WWW-Authenticate header naming this server's protected resource metadata (RFC 9728), which names the authorization server: that is how a chat app finds where to sign in.
Opaque tokens
Some authorization servers issue tokens that aren't JWTs, which only they can vouch for. Give BBM-Atlas a confidential client of its own there, and it asks about each one (RFC 7662):
BBM_ATLAS_OAUTH_INTROSPECTION_CLIENT_ID=bbm-atlasBBM_ATLAS_OAUTH_INTROSPECTION_CLIENT_SECRET_FILE=/run/secrets/introspection# BBM_ATLAS_OAUTH_INTROSPECTION_ENDPOINT=... # default: the issuer's discovery document's# BBM_ATLAS_OAUTH_INTROSPECTION_CACHE_SECONDS=60- Only a bearer token that is neither a JWT nor one of the API keys is asked about: the keys are tried first, so a key never leaves for the authorization server, and a value sent as
X-API-Keynever does. - The answer must say the token is active and for this server, from this issuer, in date, an access token rather than a refresh token, for a subject, and with every scope asked for.
- An accepted answer is reused for
BBM_ATLAS_OAUTH_INTROSPECTION_CACHE_SECONDS, never past the token's expiry, so a token revoked at the authorization server stops working within that long. - With the Helm chart, set
mcpOAuth.introspection.clientIdand putoauth_introspection_client_secretin the credentials.
What a token's holder may do
- Read only, by default (
BBM_ATLAS_OAUTH_READ_ONLY=true): search, outline, read symbols, analyse impact, read the brief - not index, delete or write facts. - API keys keep working beside tokens. With OAuth on, nobody is anonymous: a call needs a key or a token.
- Enterprise Edition: a token from the single sign-on provider maps to the person's own account and roles; any other valid token acts with the
read_onlyrole.
Connecting claude.ai with an API key
- 1Deploy BBM-Atlas on a public HTTPS address with
BBM_ATLAS_API_KEYS,BBM_ATLAS_MCP_ALLOWED_HOSTS(the public host name) andBBM_ATLAS_INDEX_ROOTS(what may be indexed, and so read). claude.ai calls it from Anthropic's cloud, not from your browser. - 2Index the code you want to ask about.
- 3Give claude.ai a key of its own that can only read: with the Enterprise Edition, a service account with the
read_onlyrole. The connector's key is shared by everyone in the organisation who connects it. - 4Add the connector - Organization settings → Connectors → Add → Custom → Web, or Customize → Connectors on Pro and Max - with the URL
https://atlas.example.com/mcp, No sign-in, and the request headerx-api-keyset to the key. - 5Behind a firewall, allow claude.ai's addresses,
160.79.104.0/21. If its calls come back403 Invalid Origin header, setBBM_ATLAS_MCP_ALLOWED_ORIGINS=https://claude.ai.
claude.ai then gets the core profile's seven tools and the brief resource, a map of a repository to start a conversation from. A connector's authentication can't be edited once added: to change the key, remove the connector and add it again.
Context packs
bbm-atlas pack repo_0b8be42a "how does checkout apply discounts?" | clip # pbcopy on macOSA pack holds the code the question needs, read from the files now, with where it is used and its files' outlines, within --budget tokens (6,000 by default). When the files it draws on are smaller than a pack would be, it is those files whole. Each pack is counted in the token ledger, so the dashboard shows what it saved.