Specification

Heidi Connector Spec v0.1.

Transport and auth

OAuth 2.1 (MCP authorization) is planned for v0.2. In v0.1 every connector uses per-practice keys.

Tools

Names are fixed. Every tool returns MCP structuredContent that matches the shapes below. Over REST, each tool is one endpoint returning the same JSON (see REST binding).

Required

Optional

Shapes

// ConnectorInfo
{ "connector_id": "riverbend-clinic-emr", "name": "Riverbend Clinic EMR", "vendor": "Riverbend",
  "spec_version": "0.1", "timezone": "Australia/Sydney", "practice_name": "Riverbend Family Clinic",
  "capabilities": ["practitioners","appointments","patient_search","patient_read","note_push"] }
 
// Practitioner
{ "id": "dr-chen", "display_name": "Dr Maya Chen", "role": "GP", "provider_number": null, "active": true }
 
// Appointment: start/end MUST carry a UTC offset
{ "id": "a-0001", "practitioner_id": "dr-chen", "start": "2026-10-05T09:00:00+11:00",
  "end": "2026-10-05T09:15:00+11:00", "status": "booked", "type": "Standard consult",
  "reason": "Diabetes review",
  "patient": { "id": "p-1001", "display_name": "Margaret Hughes", "date_of_birth": "1948-03-12" } }
 
// Patient
{ "id": "p-1001", "first_name": "Margaret", "last_name": "Hughes", "display_name": "Margaret Hughes",
  "date_of_birth": "1948-03-12", "sex": "F", "email": null, "phone": null, "address": null,
  "identifiers": { "medicare": "2100156789" } }
 
// NotePush (argument to heidi_push_note)
{ "patient_id": "p-1001", "practitioner_id": "dr-chen", "appointment_id": "a-0001",
  "title": "Consult note - Diabetes review", "content": "S: ...\nO: ...\nA: ...\nP: ...",
  "content_format": "text", "idempotency_key": "heidi-7f1c2a9e..." }
 
// NotePushResult
{ "note_id": "n-00042", "url": "https://emr.example.com/patients/p-1001#n-00042" }

status is one of booked, arrived, fulfilled, cancelled, noshow. Map your own states onto these.

Behaviour you must guarantee

1. Practitioner scoping. heidi_list_appointments returns only the requested practitioner's appointments.
2. Timezones. Appointment times include an offset. ConnectorInfo.timezone is the practice's IANA zone.
3. Idempotent writes. If heidi_push_note (or heidi_upload_document) is called twice with the same idempotency_key, the second call returns the first result and creates nothing new. Heidi retries on network errors.
4. Not found. An unknown patient_id returns the not_found error, not an empty patient.
5. No PHI in logs or errors. Error messages must not contain patient data.
6. Read-only reads. Read tools never modify your system.

Errors

Over MCP, return a tool error (isError: true) whose text content is the body below. Over REST, return it as the JSON body with the HTTP status in the table.

{ "error": { "code": "not_found", "message": "patient p-9 not found" } }

REST binding

All paths are relative to your base URL. Every request carries Authorization: Bearer <connector key>. Responses are application/json with exactly the shapes above. Lists are bare JSON arrays.

curl -H "Authorization: Bearer $KEY" \
  "https://emr.example.com/heidi/appointments?practitioner_id=dr-chen&start_date=2026-10-05&end_date=2026-10-05"

Optional endpoints you don't implement return 501 with code unsupported, or 404.

Versioning

spec_version is 0.1. Additive changes (new optional tools or fields) stay within 0.x. Breaking changes get a new version and at least 6 months of overlap.