MCP server reference

Endpoints, protocol, requests, results, and errors for the b.well MCP server

b.well hosts a remote MCP server that speaks JSON-RPC over the Streamable HTTP transport. Every request carries the signed-in user's access token.

Endpoints

EnvironmentMCP server URL
Sandboxhttps://api.client-sandbox.icanbwell.com/mcp
Productionhttps://api.icanbwell.com/mcp

Use the URL exactly as shown, with no trailing slash. MCP clients that register through Dynamic Client Registration use a different URL; see MCP Authentication.

Protocol

ItemValue
TransportStreamable HTTP. Requests return a text/event-stream response, and the JSON-RPC response arrives as a message event
Toolstools/list returns every tool enabled for your client in one response. Every tool declares an outputSchema and the readOnlyHint and destructiveHint annotations. MCP Tools describes each one
ResourcesHosts that support MCP Apps render ui://embeddables/composite.html when a tool returns embedded UI

Requests

Set BWELL_MCP_URL to an endpoint above and BWELL_ACCESS_TOKEN to the user's access token. The server accepts the token only in the Authorization header.

curl --request POST "$BWELL_MCP_URL" \
  --header "Authorization: Bearer $BWELL_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "curl-example", "version": "1.0.0" }
    }
  }'
curl --request POST "$BWELL_MCP_URL" \
  --header "Authorization: Bearer $BWELL_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "MCP-Protocol-Version: 2025-11-25" \
  --data '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'
curl --request POST "$BWELL_MCP_URL" \
  --header "Authorization: Bearer $BWELL_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "MCP-Protocol-Version: 2025-11-25" \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_current_date",
      "arguments": { "timezone_name": "America/New_York" }
    }
  }'

Results

FieldContents
structuredContentThe result object, matching the tool's outputSchema. Most tools return a formatted result string, an error string, and a meta object
contentA text item with the result text, or with the error text or error object as JSON when there's no result text. Tools that return files, such as document content, add image or resource items
isErrortrue when the tool call failed

A search that matches nothing, such as no records for the given filters, succeeds: isError is false and structuredContent.error says what wasn't found. Some tools also set error on a successful call to report data they couldn't read, so pass its text to the model instead of treating every error as no records.

Read isError first. When it's true, structuredContent holds the error object, so validate against the tool's outputSchema only when isError is false.

Large results

Each tool's section on its MCP Tools category page says how it limits large results.

PatternSignalNext step
Continuationhas_more is true, in meta for most toolsCall the tool again with the arguments in next_call. When next_call is null, narrow the request
PagesThe tool takes a page parameter and returns total_itemsRequest pages until you reach total_items, or, when it's null, until a page comes back empty
CappedA truncated flag, or a note in resultNarrow the request. There's no next page

Errors

ResponseMeaning
HTTP 401The access token is missing or invalid. Refresh it or sign the user in again; see MCP Authentication
HTTP 403The gateway refused the request for this token. Contact b.well
HTTP 400The MCP-Protocol-Version header names an unsupported revision
JSON-RPC errorA method other than tools/call failed, such as resources/read with an unknown URI
Result with isError: trueA tool call failed, including a call with invalid arguments or an unknown tool name

A failed tool call returns an object with code, message, data, and error, where error repeats message. data is null unless your client requires onboarding steps the user hasn't completed; then it holds reason and missing_fields.

{
  "code": -32301,
  "message": "Invalid arguments - start_date: Input should be a valid date or datetime, invalid character in year",
  "data": null,
  "error": "Invalid arguments - start_date: Input should be a valid date or datetime, invalid character in year"
}
CodeMeaning
-32300The user is rate limited
-32301Invalid or missing arguments
-32302Permission denied, such as a failed authentication check or Terms of Service the user hasn't accepted
-32400The tool failed, the requested item doesn't exist, or the tool name is unknown
-32500The call exceeded its deadline
-32502A service the tool depends on is unavailable

Retry read tools that return -32300, -32500, or -32502 with backoff. Don't automatically retry a tool that changes data; the change may already have been made. -32301 and -32302 fail again until the arguments or the user's permissions change.

Security considerations

The server identifies the user from the access token, so keep patient identifiers out of prompts.

The server confirms these write tools with the user before they write: create_consent, enable_ias_import_consent, save_fhir_resource, update_user_profile, create_connection, disconnect_connection, delete_connection, and reconnect_connection. How the confirmation reaches the user depends on your client. When a write tool returns a confirmation request or a preview instead of a result, nothing has been written yet: show it to the user, and make the confirming call only after they approve. For write tools that the server doesn't confirm, configure your host to ask the user before the call.

Tool results can carry text written by others, such as clinical notes, documents, and insurance policy text. Treat that text as data, never as instructions to the model.


Did this page help you?