MCP Authentication

Choose how your application gets the signed-in user's access token

The b.well MCP server acts for one end user, identified by their access token. The method your application uses to get that token also sets the user's account experience. In an integrated account experience, the user signs in once, to your application, and never sees a b.well sign-in page; they leave your application only when a step needs them to, such as identity verification or a patient-portal sign-in. In a linked account experience, your application or MCP client opens a hosted b.well sign-in page in the browser, and the user signs in with their b.well account to link it.

Choose a method

MethodAccount experienceUse it when
Federated AuthenticationIntegratedUsers already sign in to your application through its own identity provider
Dynamic Client Registration (DCR)LinkedYou prefer a connector or account-linking model, where the MCP client registers itself with b.well when it connects
Static Client RegistrationLinkedYour application runs the OAuth flow itself, with a client ID and client secret that b.well issues ahead of time, if b.well has set it up for your integration

We recommend Federated Authentication if your platform can support it, because users get the integrated account experience.


Federated Authentication

Your application signs the user in with its own identity provider and exchanges the resulting ID token for a b.well access token. End-User Authentication covers the setup in full.

  1. Complete the identity provider setup that End-User Authentication describes.
  2. Exchange the ID token for an access token, as shown in Example: OAuth Token Exchange.
  3. Send the b.well access token from the exchange, not the ID token, as a bearer token in the Authorization header to https://api.client-sandbox.icanbwell.com/mcp in sandbox or https://api.icanbwell.com/mcp in production.
  4. Refresh the token before it expires, as shown in Example: Token Refresh.

Dynamic Client Registration (DCR)

With DCR, the MCP client registers itself with b.well, signs the user in, and manages tokens. You give it one URL.

The b.well MCP server supports DCR (RFC 7591) with the OAuth 2.1 authorization code flow and PKCE (RFC 7636). Guidelines and workflows covers tools and approvals for custom connectors.

How sign-in works

Add https://mcpfhiragent.client-sandbox.icanbwell.com/ to your MCP client. This is the sandbox server, at the root path /. DCR is available in sandbox. Ask b.well whether it's available for your production client. The client then:

  1. Sends a request with no access token. The server responds with HTTP 401 and a WWW-Authenticate header that points to its protected resource metadata.
  2. Reads the discovery metadata (URLs below).
  3. Registers at /register and receives a client_id. Request only the scopes in scopes_supported in the authorization server metadata, which vary by environment. In sandbox they're openid, profile, and email. Registration with any other scope fails with HTTP 400 invalid_client_metadata.
  4. Opens the hosted sign-in page in the user's browser, with a PKCE code challenge, and receives an authorization code.
  5. Exchanges the code for an access token and a refresh token, then sends the access token as a bearer token on each MCP request.

Use this server URL for DCR, because the server runs its own authorization server with the /register endpoint. The gateway URL, https://api.client-sandbox.icanbwell.com/mcp, also answers a request without a token with a 401, but its discovery metadata points to b.well's main authorization server.

Discovery URLs

MetadataSandbox URL
Protected resource metadata (RFC 9728)https://mcpfhiragent.client-sandbox.icanbwell.com/.well-known/oauth-protected-resource
Authorization server metadata (RFC 8414)https://mcpfhiragent.client-sandbox.icanbwell.com/.well-known/oauth-authorization-server

Register as a public client (token_endpoint_auth_method: none) and use PKCE.

Refresh tokens

The client sends the refresh token to the token_endpoint from the authorization server metadata.

ResponseWhat to do
A new access tokenUse the new access token. If the response carries a refresh_token, store it
invalid_grantSign the user in again. A sign-in can be refreshed for at most 90 days
HTTP 503 temporarily_unavailable with Retry-AfterKeep the refresh token and retry after the Retry-After interval

Static Client Registration

b.well registers your application through a manual process and issues a client ID and client secret. Use this method only if b.well has set it up for your integration.

Keep the client secret on your server. Don't put it in browser or mobile code.

  1. Request a client ID and client secret from b.well, include your redirect URIs, and confirm the authorization and token endpoints for your environment.
  2. Start the authorization code flow with PKCE. The user signs in on a hosted sign-in page in their browser.
  3. Exchange the authorization code at the token endpoint, authenticating with your client ID and client secret.
  4. Send the access token as a bearer token in the Authorization header on each MCP request.

Did this page help you?