Canairy Intelligence

Canairy Intelligence connects trusted agents to referral intake and provider discovery through Canairy’s MCP endpoint. Agents can submit structured fields or documents and search for providers using a specialty, taxonomy, or an existing submission.

API keys scope intake and discovery to an organization. Routing through MCP requires an interactive OAuth user with referrals:route; API keys cannot route referrals.

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 the organization whose workspace and network the agent uses. It does not select the provider who will receive an outbound referral. The agent cannot 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

Use the endpoint shown in your Canairy Intelligence settings. For development testing, use https://app.canairy.dev/api/mcp with development credentials. Feature availability may differ between environments.

Organization and submission scope

The server derives the organization from authentication. Intake stores work in that organization; the structured submission response includes a review URL for its staff. An agent can check submissions created by its own authenticated principal. An API key and an OAuth user are different principals; do not assume switching credentials grants access to the same submission or search.

Discovery searches from the authenticated organization’s context. A candidate is a possible destination, not a request to transfer the referral.

Discover from a specialty or submission

Call find_referral_opportunities with at least one of:

• specialty: a requested specialty.
• taxonomy: one to three exact active Canairy Signal taxonomy codes.
• submissionId: one of the authenticated principal’s MCP-created submissions.

Optional fields include urgency, insurancePlan, language, and radiusMiles. The radius defaults to 25 miles and cannot exceed 100. Explicit taxonomy takes precedence over specialty; explicit criteria override values derived from a submission.

{
  "specialty": "Cardiology",
  "radiusMiles": 25
}

The current MCP schema does not accept symptoms, signals, clinicalContext, zipCode, city, or state. Read the returned distance information and notices; distance may be unavailable when there is no usable location anchor.

Results include searchId, candidates, distance, notices, and guidance. Review destination eligibility and the returned guidance. routableViaMcp describes a candidate’s eligibility; it does not give an API key routing permission. Discovery alone does not create a referral.

Empty results

If the requested specialty is unresolved, clarify it or provide a supported taxonomy code. Follow notices about unavailable distance, expanded radius, or a more specific search. An empty result does not prove that no providers exist.

Submit documents or structured fields

1. Call get_referral_options for current limits.
2. For supporting files, call request_document_upload, then PUT the bytes to uploadUrl using the matching content type.
3. If structured fields are available, call submit_referral with any attachmentKeys. Otherwise, call upload_document with the returned s3Keys to start extraction.
4. Poll get_submission_status. Follow the returned review link and submission state. PENDING_REVIEW does not mean the referral has been sent.
5. Discover destinations with find_referral_opportunities, present the options, and ask the user to confirm a provider. An authorized OAuth user can then call route_referral for their own submission and search. ROUTED confirms placement with the receiving organization; it does not mean the provider has accepted or scheduled the patient.

Include an idempotency key on supported intake and routing calls so retries do not create duplicates. Do not submit the same document through both structured and document-first paths.

Route a reviewed selection

Routing requires an interactive OAuth user with referrals:route and one unambiguous active organization. Use a submission and submission-bound search owned by that same principal. Present the options and obtain the user’s provider selection before routing.

{
  "submissionId": "<submission UUID>",
  "searchId": "<submission-bound search UUID>",
  "candidateId": "<selected provider UUID>",
  "idempotencyKey": "report-74291-selected-route"
}

The current schema requires all three identifiers. It accepts an optional note and idempotency key, but no confirmed or routingMode field. There is no automatic-selection MCP mode or API-key routing toggle in the verified implementation.

A successful route returns the leg and receiving organization. It can trigger referral notifications. ROUTED means placement with the destination, not acceptance, scheduling, or treatment completion. Safe retries with the same route identity return the existing route.

Example agent workflows

Submit structured referral fields

A provider-side agent might receive a referral request from an EHR, normalize the fields, then save it in the authenticated organization’s review workflow 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.

Submit an attached referral document

For a fictional sample referral document:

1. Call request_document_upload, then PUT its bytes to the returned uploadUrl with the specified content type.
2. Call upload_document using the returned s3Key in s3Keys, with an idempotency key.
3. Poll get_submission_status using the returned handle. The initial ACCEPTED response means the documents are queued, not that a provider has accepted the referral.
4. Once a submission exists, use its UUID with find_referral_opportunities. If the document does not establish a specialty, ask for clarification and supply an explicit specialty or taxonomy.
5. Present the returned candidates and guidance. API-key clients stop at intake and discovery. An OAuth routing workflow must use submissions and searches owned by that OAuth principal.

A standalone specialty search is not bound to a submission and cannot be passed directly into a submission-routing workflow. Run a submission-bound search before routing.

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.
• Intake and discovery use the authenticated organization; submission access is also scoped to the creating principal.
• A signed BAA is required before handling PHI through this workflow. See Legal Documents.