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
| Environment | MCP server URL |
|---|---|
| Sandbox | https://api.client-sandbox.icanbwell.com/mcp |
| Production | https://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
| Item | Value |
|---|---|
| Transport | Streamable HTTP. Requests return a text/event-stream response, and the JSON-RPC response arrives as a message event |
| Tools | tools/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 |
| Resources | Hosts 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
| Field | Contents |
|---|---|
structuredContent | The result object, matching the tool's outputSchema. Most tools return a formatted result string, an error string, and a meta object |
content | A 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 |
isError | true 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.
| Pattern | Signal | Next step |
|---|---|---|
| Continuation | has_more is true, in meta for most tools | Call the tool again with the arguments in next_call. When next_call is null, narrow the request |
| Pages | The tool takes a page parameter and returns total_items | Request pages until you reach total_items, or, when it's null, until a page comes back empty |
| Capped | A truncated flag, or a note in result | Narrow the request. There's no next page |
Errors
| Response | Meaning |
|---|---|
HTTP 401 | The access token is missing or invalid. Refresh it or sign the user in again; see MCP Authentication |
HTTP 403 | The gateway refused the request for this token. Contact b.well |
HTTP 400 | The MCP-Protocol-Version header names an unsupported revision |
JSON-RPC error | A method other than tools/call failed, such as resources/read with an unknown URI |
Result with isError: true | A 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"
}| Code | Meaning |
|---|---|
-32300 | The user is rate limited |
-32301 | Invalid or missing arguments |
-32302 | Permission denied, such as a failed authentication check or Terms of Service the user hasn't accepted |
-32400 | The tool failed, the requested item doesn't exist, or the tool name is unknown |
-32500 | The call exceeded its deadline |
-32502 | A 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.
Updated about 18 hours ago

