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
| Method | Account experience | Use it when |
|---|---|---|
| Federated Authentication | Integrated | Users already sign in to your application through its own identity provider |
| Dynamic Client Registration (DCR) | Linked | You prefer a connector or account-linking model, where the MCP client registers itself with b.well when it connects |
| Static Client Registration | Linked | Your 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.
- Complete the identity provider setup that End-User Authentication describes.
- Exchange the ID token for an access token, as shown in Example: OAuth Token Exchange.
- Send the b.well access token from the exchange, not the ID token, as a bearer token in the
Authorizationheader tohttps://api.client-sandbox.icanbwell.com/mcpin sandbox orhttps://api.icanbwell.com/mcpin production. - 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:
- Sends a request with no access token. The server responds with HTTP 401 and a
WWW-Authenticateheader that points to its protected resource metadata. - Reads the discovery metadata (URLs below).
- Registers at
/registerand receives aclient_id. Request only the scopes inscopes_supportedin the authorization server metadata, which vary by environment. In sandbox they'reopenid,profile, andemail. Registration with any other scope fails with HTTP 400invalid_client_metadata. - Opens the hosted sign-in page in the user's browser, with a PKCE code challenge, and receives an authorization code.
- 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
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.
| Response | What to do |
|---|---|
| A new access token | Use the new access token. If the response carries a refresh_token, store it |
invalid_grant | Sign the user in again. A sign-in can be refreshed for at most 90 days |
HTTP 503 temporarily_unavailable with Retry-After | Keep 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.
- Request a client ID and client secret from b.well, include your redirect URIs, and confirm the authorization and token endpoints for your environment.
- Start the authorization code flow with PKCE. The user signs in on a hosted sign-in page in their browser.
- Exchange the authorization code at the token endpoint, authenticating with your client ID and client secret.
- Send the access token as a bearer token in the
Authorizationheader on each MCP request.
Updated about 18 hours ago

