Skip to content
NimbleBrainNimbleBrainNimbleBrain

Credentials

Every connector is a remote MCP server, so every credential is a credential for reaching one. NimbleBrain never holds a connector’s own secrets on its behalf: it holds what it needs to authenticate the connection, workspace by workspace.

The three shapes

Section titled “The three shapes”

OAuth tokens (the common case)

Section titled “OAuth tokens (the common case)”

A connector installed from the catalog authenticates over OAuth. A token is a secret of the same class as a client secret, so it goes through the same door as every other one: the flow’s records are keys in the workspace’s credential store, one set per connector.

Key What it holds
mcp-oauth.{serverName}.tokens the access + refresh token pair
mcp-oauth.{serverName}.client the Dynamic Client Registration result, including a client_secret when the vendor issues a confidential client
mcp-oauth.{serverName}.verifier the PKCE verifier for the flow in progress
mcp-oauth.{serverName}.identity the OIDC claims behind “Connected as …” — not itself a secret
mcp-oauth.{serverName}.auth_lost a flag, set when the vendor rejects the credential and cleared by the next Connect or Disconnect, so a restart still shows Reconnection needed rather than Not connected — not a secret

Each value is a JSON string the store holds opaquely, so rotation, mode, atomic writes and the audit line are the store’s, and an encrypted backend reaches these without a connector noticing. Connecting a service in one workspace never exposes it to another; disconnecting deletes that workspace’s keys for the connector and nothing else.

A personal connector is the same flow bound to your identity instead of a workspace — the same keys, at user scope, following you across workspaces. See Personal connectors.

An operator’s OAuth client (static auth)

Section titled “An operator’s OAuth client (static auth)”

Vendors that don’t support Dynamic Client Registration (Gmail, Outlook, HubSpot, Asana, …) need an OAuth app the operator registers in the vendor’s developer portal. The workspace admin enters the client_id and client_secret on the connector’s Configure page. The id is public and sits in workspace.json; the secret goes to the workspace credential store and workspace.json holds only a credential reference to it, resolved per request, so it never appears in the workspace record or in any API response.

Until that pair is configured, the connector reads as needs setup and the Connect button is replaced by Set up OAuth.

A brokered connection

Section titled “A brokered connection”

A connector fronted by a gateway (Composio, Smithery) holds its upstream grant at the broker. NimbleBrain stores only an opaque pointer to that connection — never the vendor key. The platform-wide gateway API key stays in the platform environment. See Connector Providers.

A secret the workspace owns

Section titled “A secret the workspace owns”

A connector can also authenticate with a secret the workspace holds — a database URL, an API key the customer owns — named by a credential reference in its transport config or supplied by the built-in credential credential provider. One catalog entry then installs into two workspaces and each presents its own secret. Rotate it by setting the key again; nothing about the connector changes.

Section titled “Related”