Skip to content

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 pack copies 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

AppAuthentication it offersConnect BBM-Atlas with
claude.ai (and Claude Desktop)OAuth; no authentication; a fixed request header, in beta for some organisationsOAuth, or the API key in x-api-key where the organisation has Request headers
ChatGPTOAuth 2.1, or no authenticationOAuth
Gemini appOAuth: registered by the app itself, or with credentials you enterOAuth
Gemini EnterpriseOAuth 2.0 with a client id and secret entered by hand, or no authenticationOAuth

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 in BBM_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 Enterprise https://vertexaisearch.cloud.google.com/oauth-redirect.
terminal
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.com

With 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):

terminal
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-Key never 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.clientId and put oauth_introspection_client_secret in 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_only role.

Connecting claude.ai with an API key

  1. 1Deploy BBM-Atlas on a public HTTPS address with BBM_ATLAS_API_KEYS, BBM_ATLAS_MCP_ALLOWED_HOSTS (the public host name) and BBM_ATLAS_INDEX_ROOTS (what may be indexed, and so read). claude.ai calls it from Anthropic's cloud, not from your browser.
  2. 2Index the code you want to ask about.
  3. 3Give claude.ai a key of its own that can only read: with the Enterprise Edition, a service account with the read_only role. The connector's key is shared by everyone in the organisation who connects it.
  4. 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 header x-api-key set to the key.
  5. 5Behind a firewall, allow claude.ai's addresses, 160.79.104.0/21. If its calls come back 403 Invalid Origin header, set BBM_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

terminal
bbm-atlas pack repo_0b8be42a "how does checkout apply discounts?" | clip    # pbcopy on macOS

A 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.