Canairy Intelligence

The Canairy Intelligence tab lets trusted provider agents submit structured referrals directly into your Referral Inbox through Canairy’s MCP endpoint. It is for practices that work with external providers or health systems running AI agents under a signed BAA.

Submissions from connected agents still require staff review. They land in the inbox as Pending review and do not create patient records or referrals until someone approves them.

What you see

• Endpoint — your MCP server URL, usually https://app.canairy.co/api/mcp
• Connect a client — setup snippets for Claude Code, Codex, or a generic JSON MCP client
• API keys — active, expiring, expired, and revoked keys for your practice
• Agent activity — recent submit_referral submissions created through your keys
• MCP tool reference — the read and write tools available to connected agents

Create an API key

Only admins can create API keys.

1. Open Organization Settings → Canairy Intelligence.
2. Click Create API key.
3. Choose when the key expires: 30, 90, or 180 days. The default is 90 days.
4. Click Generate key.
5. Copy the full key and store it in the provider agent’s secret store.

Canairy shows the full key only once. After the dialog closes, the table shows only the key prefix, status, expiration, and last-used time. If the full key is lost, rotate it.

Connect a client

Use the setup panel to copy the endpoint or a ready-made client configuration.

For Claude Code, the setup command looks like:

claude mcp add --transport http canairy https://app.canairy.co/api/mcp \
  --header "Authorization: Bearer cnry_live_..."

For Codex, the configuration looks like:

[mcp_servers.canairy]
url = "https://app.canairy.co/api/mcp"
http_headers = { Authorization = "Bearer cnry_live_..." }

The key is sent as a bearer token. The key determines which practice receives the referral, so the agent does not choose a tenant in its request.

For a generic HTTP MCP client, the configuration looks like:

{
  "type": "http",
  "url": "https://app.canairy.co/api/mcp",
  "headers": {
    "Authorization": "Bearer cnry_live_..."
  }
}

Rotate or revoke a key

Use the row menu in the API keys table.

• Copy setup command — copies the current setup snippet for that key prefix
• Rotate key — creates a new key, reveals it once, then revokes the old key
• Revoke key — disables the key immediately

Expired and revoked keys can no longer submit referrals. Historical submissions keep their original key provenance for audit and review.

Available tools

Connected MCP clients can use six tools:

The expected agent workflow is:

1. Call get_referral_options.
2. Upload supporting documents with request_document_upload when needed.
3. Call submit_referral with patient, provider, diagnosis, urgency, and attachment details.
4. Poll get_submission_status until staff approve or reject the submission.

Agents should include an idempotency key when submitting referrals so retries do not create duplicate submissions.

Example agent workflow

A provider-side agent might receive a referral request from an EHR, normalize the fields, then submit it to the receiving practice through the MCP server.

Example instruction to the agent:

Use the Canairy MCP server to submit a referral for Jane Doe, born 1985-04-12.
She needs an urgent orthopedic consult for persistent lumbar radiculopathy.
The referring provider is Dr. Maya Patel at Westside Primary Care.
Include ICD-10-CM code M54.16 and use idempotency key ehr-74291-2026-07-03.
After submitting, return the Canairy submission ID and current review status.

The agent should first call get_referral_options, then call submit_referral with a payload like:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "dateOfBirth": "1985-04-12",
  "gender": "Female",
  "patientPhone": "+1-415-555-0198",
  "specialty": "Orthopedics",
  "urgency": "Urgent",
  "reasonForReferral": "Persistent lumbar radiculopathy with worsening pain despite conservative therapy.",
  "note": "Please evaluate for imaging and treatment options.",
  "practiceName": "Westside Primary Care",
  "sendingProviderName": "Dr. Maya Patel",
  "senderPhone": "+1-415-555-0120",
  "icdCodes": [
    {
      "code": "M54.16",
      "description": "Radiculopathy, lumbar region",
      "confidence": 1
    }
  ],
  "idempotencyKey": "ehr-74291-2026-07-03"
}

If supporting documents are needed, the agent should call request_document_upload first, upload the file bytes to the returned uploadUrl with the same Content-Type, then include the returned s3Key in attachmentKeys.

Security notes

• Keys are scoped to your practice.
• A key can only read submissions it created.
• The full key is never shown again after creation.
• API submissions appear in the inbox with the API source.
• A signed BAA is required before handling PHI through this workflow. See Legal Documents.