Skip to main content
Bily MCP supports two authentication paths. Choose one for each connection.

​
Connect with Bily Connect

Bily Connect is the recommended choice for clients that support MCP OAuth. It keeps a long-lived key out of client configuration.
  • The client discovers Bily’s public authorization metadata.
  • The client can register dynamically as a public client.
  • The user signs in to Bily and grants the mcp_access scope.
  • The client uses Authorization Code with PKCE and can refresh the connection.
  • Bily resolves the signed-in identity and checks that user’s current organization and store memberships.
The OAuth token is not permanently limited to one store. A signed-in user can request stores available through their current Bily memberships. Removing a membership removes that access.

​
Access key fallback

Use a fallback key only when the client cannot complete Bily Connect.
  1. Select the intended store in Bily.
  2. Open Settings > MCP.
  3. Under Access key fallback, choose a name and expiration.
  4. Create the key and copy the full value immediately.
  5. Send it in the x-api-key header.
Bily shows the full key once. Save it in the client’s secret-aware configuration. The key carries the selected store and organization as its default scope. Bily rejects requests for another store or organization.
Replace any older settings-generated fallback key that lacks store scope. Select the intended store, create a new key, and update the client.Verify bily.context() before you revoke the older key. Bily rejects an unscoped older key instead of widening it automatically.
Create one fallback key for each client, environment, and store. Short expirations and descriptive names simplify rotation and revocation.

​
Know what each connection can access

Both paths follow these rules:
  • storeUrl must identify a store available to the authenticated identity.
  • organizationId must identify an accessible organization.
  • A scoped key cannot override its recorded store or organization in search or execute.
  • Bily checks scope on the server, not only in the client prompt.

​
Resolve authentication failures

  • 401 Unauthorized means the connection is missing, expired, revoked, or invalid. Reconnect or replace the key.
  • 403 Forbidden means the identity is authenticated, but the requested store, organization, permission, or action is outside its allowed scope. Confirm the requested scope.
If a 403 requires a store-scoped API key, select the intended store and create a replacement fallback key. Do not broaden a key to solve a 403 until you understand why the request needs more access.

​
Replace a key without interruption

Create a replacement before revoking a key used by an active client. Update the client and verify a read-only request. Then revoke the old key from Settings > MCP.