Developer guide

Claude connector (MCP)

The Sapyyn MCP server lets Claude answer questions like "which referrals from Dr. Washington aren't booked yet?" or "how fast did we respond to referrals this month?", and, if you allow it, book appointments and add notes.

In Sapyyn, open Integrations and create an API key with Claude (MCP): read. Add Claude (MCP): update if Claude should record appointments, move statuses or add notes.
Add the server to Claude using the address https://sapyyn.com/mcp and the key as a bearer token.

Claude Code

claude mcp add --transport http sapyyn https://sapyyn.com/mcp \
  --header "Authorization: Bearer $SAPYYN_API_KEY"

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "sapyyn": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://sapyyn.com/mcp",
               "--header", "Authorization:Bearer ${SAPYYN_API_KEY}"],
      "env": { "SAPYYN_API_KEY": "spk_live_..." }
    }
  }
}

Adding Sapyyn as a custom connector on claude.ai needs a sign-in flow (OAuth), which is not available yet. Use Claude Code or Claude Desktop for now.

Tools

Tool	What it does	Needs
`list_referrals`	List referrals this practice sent or received, newest first. Use needs_action=true to find referrals waiting for a response or a booking.	read
`get_referral`	Status timeline, open follow-up tasks, appointments and the statuses this connection may set next.	read
`referral_metrics`	Median time to first response, share scheduled within 7 days, median days to completion, and the same by staff member.	read
`find_providers`	Search the Sapyyn provider directory by name, practice, specialty or provider code.	read
`record_appointment`	Receiving office only. booked needs scheduled_for (ISO date and time, office local time) and marks the referral scheduled. completed means the patient was seen. cancelled and no_show open a follow-up task.	update
`update_referral_status`	Move a referral one step along its lifecycle. get_referral lists the allowed next statuses.	update
`add_referral_note`	Add a note to a referral. care_team notes are visible to both offices.	update

API keys and scopes

Practice owners and admins create keys on the Integrations page. A key belongs to one practice and only sees referrals that practice sent or received. Sapyyn stores a hash, so copy the key when it is shown. Send it as Authorization: Bearer <key> or X-API-Key: <key>.

referrals:read: Read referrals
referrals:write: Create referrals
practices:read: Read this practice
appointments:write: Record appointments (scheduling tools)
mcp:read: Claude (MCP): read referral status and metrics
mcp:write: Claude (MCP): update status, add notes, record appointments
mcp:phi: Claude (MCP): include patient details (only when MCP_PHI_ALLOWED is on under a BAA)

Recording appointments

When the receiving office books, sees, cancels or misses a referred patient, any scheduling tool can tell Sapyyn. A booking marks the referral scheduled and notifies the referring office. Sending the same external_id again updates the same appointment, so retries are safe.

curl -X POST https://sapyyn.com/api/v1/appointments \
  -H "Authorization: Bearer $SAPYYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"referral_code": "9887fe00",
       "status": "booked",
       "scheduled_for": "2026-11-12T09:30",
       "location": "South County",
       "source": "zapier",
       "external_id": "appt-88231"}'

status: booked, completed (patient seen), cancelled or no_show. Cancelled and no-show open a follow-up task.
scheduled_for: the office's local date and time.
complete_referral: with completed, also closes the referral.
source: one of api, weave, sensei, teamcare, zapier, make, n8n.
Needs the appointments:write scope, and the key's practice must be the receiving office.

REST API

Method and path	Scope	Purpose
`POST /api/v1/referrals`	`referrals:write`	Create a referral. Requires an `Idempotency-Key` header.
`GET /api/v1/referrals`	`referrals:read`	The newest 100 referrals for the key's practice.
`GET /api/v1/referrals/<id>`	`referrals:read`	One referral.
`GET /api/v1/referrals/<id>/appointments`	`referrals:read`	Appointments on a referral.
`POST /api/v1/appointments`	`appointments:write`	Record a booking or outcome.
`GET /api/v1/practices`	`practices:read`	The key's practice.

Webhooks

Sapyyn posts signed JSON to the HTTPS endpoints you add on the Integrations page. Verify each delivery with the X-Sapyyn-Signature header, which is sha256= followed by the HMAC-SHA256 of the raw body using your endpoint secret.

Events:

referral.created
referral.status_changed
referral.completed
provider.invited
practice.created
note.added
appointment.updated

Patient information

By default the Claude connector and webhooks identify referrals by reference code and leave out patient names, contact details, clinical reasons and appointment locations. They are included only when your practice has a business associate agreement with the receiving service and Sapyyn has turned that option on for your account.

Claude connector patient details are currently off for every account.