Unfortunately, the Heidi API and Widget are no longer available for future integrations in Australia and New Zealand. If you are a current Heidi customer looking to integrate, reach out to your Customer Success representative. Otherwise, contact our team to find out what this means for you.
Connectors
Tool connectors

Tool connectors: bring your own MCP server

Tool connectors are in preview. The transport (MCP over Streamable HTTP) may change before general availability. We will give connector authors notice before any breaking change.

The specification covers EHR connectors, which implement a fixed set of operations. A tool connector is different. You already have an MCP server (billing, analytics, scheduling, anything) and want Heidi's agent to use its tools as they are. You keep your own tool names and schemas. Heidi reviews them, and once a clinician connects your product, Heidi's agent can call them.

For example, a clinician finishes a consult and says "bill this as a standard consult". Heidi's agent looks up item 23 with your search_billing_items tool, then calls your create_invoice tool. Writes like that always show the clinician an approval card first.

What you need

  • A remote MCP server over Streamable HTTP, HTTPS only.
  • Bearer auth, either a key the clinician gets from your product or OAuth. For OAuth, follow the MCP authorization spec (opens in a new tab): return 401 with WWW-Authenticate: Bearer resource_metadata="...", publish authorization-server metadata, and support PKCE S256. If you don't support dynamic client registration, Heidi registers a client with you during review.
  • No sign-in is only for public reference data. Every tool must carry readOnlyHint, and none of them may return patient or tenant data. A tool that changes data, or that reads clinical or tenant data, needs a per-clinician key or OAuth.
  • Tools with clear descriptions. Mark read-only tools with the MCP readOnlyHint annotation. Anything without it is treated as a write.

Steps

  1. Apply and say you have your own MCP server. Include a sandbox URL and a sandbox key with test data only.
  2. We work closely with you to capture the tools Heidi's agent will see, and to prepare heidi-connector.json and heidi-tools.json.
  3. The review is the same as for EHR connectors (see Submitting), plus a review of every tool.

How Heidi uses your tools

RuleWhat it means for you
Frozen at reviewHeidi's agent sees only the name, description and input schema in your reviewed heidi-tools.json. Before every call, Heidi checks that the live tool still matches its sha256. If you change a tool, Heidi stops calling it until you resubmit. New tools stay hidden until reviewed.
Writes need approvalTools you don't mark readOnlyHint show the clinician an approval card every time. Auto mode can't skip it.
Output is dataHeidi passes your tool output to the agent as untrusted third-party data and ignores instructions inside it. Keep output under 20,000 characters, as Heidi truncates the rest.
Patient dataSet data_handling.receives_phi. If it's false, Heidi's agent is told never to send patient details to your tools. If it's true, a data processing agreement is required (and a BAA in the US).
Per clinicianEach clinician connects with their own key, or signs in with OAuth, in Settings → Connectors. Only connected clinicians' agents see your tools.
NamesYour tools appear as ext.<connector_id>.<tool>, lowercased with other characters turned into _, and must fit in 64 characters. Heidi flags any that don't.
SpecificationTesting your connector