Log inSign up →
Blue Banana
Docs
Features
API reference

MCP server

Blue Banana is a Model Context Protocol server. Any MCP client — Claude, Codex, or your own agent — can run the sandbox EHR from a conversation: look patients up, book and check in appointments, drop items in the clinical inbox, and manage the webhook subscriptions that start Keragon workflows.

It's the same sandbox as the API and the EHR: MCP writes land in your tenant, show up in the EHR, count toward your quota, and fire your webhooks like an API write.

Server URL

https://bluebananaehr.com/api/mcp

Streamable HTTP. Authenticate with OAuth (sign in to Blue Banana when the client asks), or send Authorization: Bearer bb_… with a key from /account. Each OAuth connection mints its own key, named after the client, on your Account page; revoke it there to disconnect.

Connect Claude

claude.ai and Claude Desktop

  1. Settings → Connectors → Add custom connector.
  2. Name Blue Banana EHR, URL https://bluebananaehr.com/api/mcp.
  3. Connect, sign in to Blue Banana, choose Allow.
  4. Enable the connector in a chat and ask, e.g. “Book John Smith with Dr. Chen tomorrow at 10am for a diabetes follow-up.”

Claude Code

Add the server, then run /mcp in Claude Code to sign in:

claude mcp add --transport http bluebanana https://bluebananaehr.com/api/mcp

Or use an API key instead of OAuth:

claude mcp add --transport http bluebanana https://bluebananaehr.com/api/mcp \
  --header "Authorization: Bearer bb_…"

Connect Codex

The Codex CLI, the IDE extension and the ChatGPT desktop app share one MCP config (~/.codex/config.toml), so set it up once in any of them.

Codex CLI

Add the server and sign in with OAuth:

codex mcp add bluebanana --url https://bluebananaehr.com/api/mcp
codex mcp login bluebanana

Or use an API key (no browser sign-in — good for CI):

export BLUEBANANA_API_KEY=bb_…
codex mcp add bluebanana --url https://bluebananaehr.com/api/mcp \
  --bearer-token-env-var BLUEBANANA_API_KEY

Check it with codex mcp list, or /mcp inside Codex. The equivalent config.toml entry:

[mcp_servers.bluebanana]
url = "https://bluebananaehr.com/api/mcp"
bearer_token_env_var = "BLUEBANANA_API_KEY"  # omit to use OAuth

Codex IDE extension and ChatGPT desktop app

  1. Settings → MCP servers → Add server (in the IDE extension: the gear menu).
  2. Name bluebanana, type Streamable HTTP, URL https://bluebananaehr.com/api/mcp. Save and restart.
  3. Choose Authenticate and sign in to Blue Banana.

Other MCP clients

Any client that supports remote (Streamable HTTP) servers works. OAuth is discovered from the WWW-Authenticate header on a 401 (/.well-known/oauth-protected-resource, dynamic client registration, PKCE S256); otherwise set a static Authorization header. For stdio-only clients:

{
  "mcpServers": {
    "bluebanana": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://bluebananaehr.com/api/mcp",
               "--header", "Authorization: Bearer bb_…"]
    }
  }
}

Start a Keragon workflow over MCP

  1. In Keragon, start a workflow with a Webhooktrigger (or the Blue Banana connector's appointment trigger) and copy its URL.
  2. Ask your assistant: “Create a Blue Banana webhook that fires when an Appointment is created and posts to https://…” It calls create_webhook_subscription; test_webhook_subscription sends a sample so you can map fields in Keragon.
  3. Ask it to book an appointment. book_appointment writes the Appointment, the subscription fires, and Keragon receives a signed criteria.matched POST. The tool result lists the triggers that fired.

Payloads and signatures: Webhooks.

Tools

Patients
search_patientsFind patients by name, birth date, gender or MRN.
get_patient_summaryProblems, meds, allergies, upcoming visits, encounters and coverage in one call.
patient_everythingThe full record ($everything), with counts per resource type.
check_eligibilityMock 270/271 insurance eligibility check.
Scheduling
list_providersPractitioners, and which ones have bookable schedules.
find_available_slotsOpen slots, earliest first, skipping already-booked times.
list_appointmentsThe schedule by day, range, patient, provider or status.
book_appointmentBook into a slot or at a time. Fires Appointment webhooks.
update_appointmentArrive, check in, check out, cancel, no-show or reschedule.
Clinical inbox
create_inbox_taskDrop a message, refill request, result or task into /app/inbox.
message_patientSend a patient a portal message (a Communication); in a test run with a simulated patient, they reply.
get_patient_messagesA patient's message thread, oldest first — read a simulated patient's replies.
create_form_linkA link a patient opens to fill a form (intake, insurance, PHQ-2…).
Webhooks (Keragon triggers)
list_webhook_eventsNamed events: appointment.cancelled, note.signed, charge.created…
list_webhook_subscriptionsWhat will fire, and where it goes.
create_webhook_subscriptionPoint events at a Keragon webhook trigger URL.
test_webhook_subscriptionSend a sample delivery now, using real sandbox data.
list_webhook_deliveriesWhat was delivered, when, and the HTTP status.
set_webhook_subscription_enabledPause or resume a subscription.
delete_webhook_subscriptionRemove a subscription.
Agent tests
list_test_scenariosGraded test scenarios an agent can take (scheduling, intake, triage…), with their persona variants.
start_test_runSet a scenario (or one of its persona variants) up in the sandbox and get its brief.
finish_test_runGrade the run: status, score and each expected result.
Any FHIR resource
fhir_searchSearch any of the 43 resource types.
fhir_readRead one resource.
fhir_create / fhir_update / fhir_patchWrite any resource. Fires webhooks.
fhir_deleteDelete (or hide a shared record) in your sandbox.
get_sandbox_infoYour tenant, quotas and useful links.

Limits and safety

  • Synthetic data only — every resource carries the synthetic-data extension. Never connect real PHI.
  • Each OAuth connection gets its own API key, limited to 60requests/minute. There are no refresh tokens: the key doesn't expire; if you revoke it, connect again.
  • Tool calls count toward your tenant's request rate and write quota, like API calls — see Limits.
  • Resources written through MCP carry meta.tag http://bluebananaehr.com/source|mcp, so workflows can tell where a change came from.
  • Times are UTC.