Authentication and security

BridgeMCP authenticates in two directions:

DirectionWho authenticatesPurpose
InboundAI clients connecting to BridgeMCPAuthorize MCP tool access.
OutboundBridgeMCP connecting to upstream serversAuthenticate to upstream providers.

Inbound access supports API keys (simple and stateless) and OAuth (interactive, with a consent page). Outbound connectors support no auth, static token headers, and OAuth 2.0 with automatic token refresh.

API keys

API keys are the simplest way for an AI client to authenticate.

brg_live_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
  • Format: a brg_ prefix, an environment marker (live or test), an sk_ secret marker, and 32 random characters.
  • Storage: authentication uses the SHA-256 hash. An encrypted, recoverable copy is also stored so the key can be revealed again from the console.
  • Scope: each key is bound to a single Virtual MCP.

Send the key as a bearer token:

Authorization: Bearer brg_live_sk_...

Inbound OAuth

For interactive clients, BridgeMCP runs its own OAuth authorization server. When a client connects without credentials, the gateway returns 401 with discovery metadata. Modern clients can identify themselves with a Client ID Metadata Document (CIMD); Dynamic Client Registration (DCR) remains available as a compatibility fallback. The user is sent through a browser consent page, then the client exchanges an authorization code (validated with PKCE) for an opaque access token.

Inbound OAuth tokens are opaque and validated on each request. Token validation is a fast lookup, with expiry enforced on every call. Authorization responses include an exact issuer (iss) value so clients can reject issuer mix-ups.

Outbound OAuth

Connectors that reach OAuth-protected upstream servers authenticate independently of inbound auth. BridgeMCP runs a standard OAuth 2.0 authorization code flow with PKCE, stores the resulting tokens, and refreshes them automatically as they expire. Static-token connectors instead attach configured headers to every upstream request.

Automatic registration prefers an existing pre-registered client. Outbound CIMD selection is protected by the operator-controlled OutboundOAuth:CimdRegistrationEnabled rollout gate, which is off by default. When enabled and advertised by a compatible authorization server, CIMD is preferred; otherwise BridgeMCP falls back to deprecated DCR or requires manually supplied pre-registered details.

CIMD clients refresh the protected-resource and authorization-server metadata before authorization when discovery is available, and BridgeMCP records the selected authorization server with the authorization request. DCR clients store the issuer that minted their credentials and are re-registered if later discovery points to a different issuer. When an authorization request has a recorded issuer, BridgeMCP compares any returned iss exactly and rejects a missing iss when that server advertised issuer responses. Manually supplied pre-registered clients skip discovery and have no recorded issuer, so their callbacks proceed without an issuer comparison; operators must verify that their configured endpoints and credentials belong to the intended authorization server.

Security practices

  • Least privilege: scope each API key to one Virtual MCP, and scope each Virtual MCP to the connectors an agent actually needs.
  • Rotation: revoke and reissue keys regularly rather than sharing them widely.
  • PKCE everywhere: both inbound and outbound OAuth flows use PKCE (S256).
  • Short-lived state: authorization state and codes are single-use and expire in minutes.
  • Confidential secrets: keep API keys, OAuth client secrets, and webhook signing secrets out of source control and logs.

Next steps