Skip to content
Truto Blog
Back
AI & Agents

Connect Canvas Medical to Claude: Access Clinical Records & Vitals

Learn how to connect Canvas Medical to Claude using a managed MCP server. Execute FHIR-compliant clinical workflows, extract vitals, and schedule appointments.

Sidharth Verma Sidharth Verma · · 9 min read

If you need to connect Canvas Medical to Claude to access clinical records, schedule appointments, or extract patient vitals, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's JSON-RPC tool calls and Canvas Medical's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Canvas Medical to ChatGPT or explore our broader architectural overview on connecting Canvas Medical to AI Agents.

Giving a Large Language Model (LLM) read and write access to an Electronic Health Record (EHR) system is a significant engineering challenge. You must handle complex healthcare data models, manage authentication lifecycles, map massive JSON schemas to MCP tool definitions, and ensure strict adherence to API specifications.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Canvas Medical, connect it natively to Claude Desktop, and execute complex clinical workflows using natural language.

The Engineering Reality of the Canvas Medical API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against a specialized healthcare API is painful. Canvas Medical is not a standard CRUD application - it is a comprehensive clinical platform built entirely around the FHIR (Fast Healthcare Interoperability Resources) standard.

If you decide to build a custom MCP server for Canvas Medical, here are the specific integration challenges you will face:

Deeply Nested FHIR R4 Schemas Canvas Medical strictly adheres to the FHIR R4 specification. This means resources are not flat JSON objects. A simple Patient resource includes deeply nested arrays for name, telecom, address, and highly specific extensions (such as the birthsex extension, which is strictly required for creation). If an LLM tries to guess this payload structure, it will fail 100% of the time. Truto solves this by parsing Canvas Medical's OpenAPI/Swagger documentation into standardized JSON Schemas, explicitly guiding the LLM on exactly how to construct a valid FHIR payload for every single tool.

Form-Encoded Search Endpoints for Privacy Standard REST APIs typically pass search parameters in the URL query string (e.g., ?status=active&patient=123). Because clinical search parameters often contain Protected Health Information (PHI), Canvas Medical implements search tools (like canvas_medical_appointments_search) that use form-encoded POST requests. This keeps sensitive search values out of URL logs. Building an MCP server requires abstracting these HTTP verbs and content-type idiosyncrasies so the LLM simply calls a function with arguments.

Asynchronous Bulk Data Exports (NDJSON) Extracting large cohorts of patient data cannot be done synchronously. Canvas Medical uses FHIR Bulk Data exports. You must initiate a kick-off request (create_a_canvas_medical_patient_export), which runs as a background job. Your client must then poll the bulk_export_jobs resource until the job completes, at which point Canvas returns URLs to NDJSON (Newline Delimited JSON) files. Your LLM needs specific context to handle this async polling pattern.

A Note on Rate Limits: Truto does not absorb rate limit errors, apply automatic backoff, or artificially throttle requests. When Canvas Medical returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller (your agent framework) is responsible for detecting the 429 and executing its own retry or backoff logic.

Step 1: Generating the Canvas Medical MCP Server

Truto dynamically generates MCP tools based on Canvas Medical's resource documentation. There is no hardcoded tool logic - if a Canvas Medical API method is documented in Truto, it becomes available as an AI tool.

You can generate the MCP server URL in two ways: via the UI for rapid prototyping, or via the API for programmatic, multi-tenant deployment.

Method A: Via the Truto UI

For internal testing or single-tenant setups, you can generate an MCP server directly from the dashboard.

  1. Navigate to the Integrated Accounts page in your Truto dashboard.
  2. Select your connected Canvas Medical instance.
  3. Click the MCP Servers tab.
  4. Click Create MCP Server.
  5. Select your desired configuration (e.g., name the server "Clinical Data Agent", filter by specific tags, or limit to read-only methods).
  6. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3d4...).

Method B: Via the API (For Production)

For production workflows where you are deploying AI agents for multiple clinics or customers, you should generate MCP servers programmatically.

Make an authenticated POST request to the /integrated-account/:id/mcp endpoint. You can enforce granular security by filtering the tools the LLM can access.

curl -X POST https://api.truto.one/integrated-account/<integrated_account_id>/mcp \
  -H "Authorization: Bearer <your_truto_api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Canvas Medical - Vitals and Scheduling",
    "config": {
      "methods": ["read", "create", "search"],
      "require_api_token_auth": false
    },
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Truto returns a secure JSON-RPC 2.0 endpoint:

{
  "id": "mcp_srv_9x8y7z6",
  "name": "Canvas Medical - Vitals and Scheduling",
  "config": {
    "methods": ["read", "create", "search"]
  },
  "expires_at": "2025-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/f7e8d9c0b1a2..."
}

This single URL contains a cryptographic token that authenticates the connection and routes the tool calls to the correct Canvas Medical tenant.

Step 2: Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you can plug it into any MCP-compliant client.

Method A: Via the Claude UI (or ChatGPT)

If you are using the Claude desktop app or web interface, or ChatGPT with developer features enabled:

  1. In Claude: Navigate to Settings -> Integrations -> Add MCP Server. (For ChatGPT: Settings -> Apps -> Advanced settings -> Enable Developer mode -> Add a custom connector).
  2. Name the integration "Canvas Medical AI".
  3. Paste the Truto MCP URL you generated in Step 1.
  4. Click Add or Save.

The LLM will immediately execute an MCP initialize handshake and request the tools/list, populating its context with Canvas Medical capabilities.

Method B: Via the Manual Configuration File

If you are running Claude Desktop locally and prefer file-based configuration, you can update your claude_desktop_config.json file. Truto's MCP servers communicate via Server-Sent Events (SSE), so you will use the official @modelcontextprotocol/server-sse package as the command transport.

{
  "mcpServers": {
    "canvas_medical": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/f7e8d9c0b1a2..."
      ]
    }
  }
}

Restart Claude Desktop, and the model will now have secure access to the EHR.

Canvas Medical Hero Tools

Truto exposes Canvas Medical's entire FHIR surface area as tools. Here are 7 high-leverage tools for clinical workflows.

get_single_canvas_medical_patient_by_id

Retrieves a single FHIR R4 Patient resource. Crucial for establishing context before querying clinical data. Includes demographic details and the birthsex extension.

"Fetch the patient record for patient ID 'Pat-456' and summarize their demographics."

Searches for Observation resources (vitals, lab values, social history) using a form-encoded POST request, keeping search parameters out of URL logs. Returns paginated FHIR R4 Observation resources.

"Search the observation records for patient 'Pat-456' to find their latest blood pressure readings."

create_a_canvas_medical_appointment

Creates an Appointment in Canvas. Requires strict adherence to FHIR mapping for the status, start, end, and participant arrays.

"Schedule an appointment for patient 'Pat-456' with practitioner 'Prac-123' on Monday at 10:00 AM for a routine follow-up. Set the status to 'proposed'."

list_all_canvas_medical_medication_statements

Searches MedicationStatement resources to retrieve a patient's medication history. Requires FHIR search parameters and returns effectivePeriod and medicationCodeableConcept.

"List all active medication statements for patient 'Pat-456'."

create_a_canvas_medical_diagnostic_report_lab_report

Creates a comprehensive lab report, specific lab tests, values, and a stored PDF in a single complex request. Requires a Parameters resource with labReport and labTestCollection arrays.

"Create a new diagnostic lab report for patient 'Pat-456' including a complete blood count panel and the attached PDF summary."

create_a_canvas_medical_patient_export

Initiates an asynchronous FHIR Bulk Data export for a specific patient's complete electronic health information.

"Start a bulk data export for patient 'Pat-456'. Note the job ID so we can poll its status later."

Searches CarePlan resources using form-encoded POST. Returns the FHIR R4 CarePlan resource detailing intent, status, and category.

"Search for any active care plans related to diabetes management for patient 'Pat-456'."

Note: This is just a fraction of the available tools. For the complete tool inventory and granular JSON Schema details, visit the Canvas Medical integration page.

Workflows in Action

When Claude is equipped with Truto's Canvas Medical tools, it can orchestrate multi-step clinical and administrative operations without writing custom integration logic.

Scenario 1: Generating a Pre-Visit Clinical Summary

A care coordinator needs a comprehensive summary of a patient's status before an upcoming telehealth visit.

"Generate a pre-visit clinical summary for patient 'Pat-789'. I need their basic demographics, all active medication statements, their latest vitals (observations), and any active care plans."

Execution Steps:

  1. Claude calls get_single_canvas_medical_patient_by_id with id: "Pat-789" to retrieve demographics and sex assigned at birth.
  2. Claude calls list_all_canvas_medical_medication_statements with the patient parameter to retrieve current prescriptions.
  3. Claude calls canvas_medical_observations_search to find recent vitals.
  4. Claude calls canvas_medical_care_plans_search with status: "active".

Result: The user receives a synthesized, human-readable pre-visit brief containing up-to-date medications, latest blood pressure/weight, and active care pathways, derived directly from live FHIR records.

Scenario 2: Asynchronous Bulk Data Extraction

A clinic administrator needs to export full patient histories to migrate to a specialized analytics data warehouse.

"Kick off a full bulk data export for patient 'Pat-102'. Once started, check the status of the export job."

sequenceDiagram
    participant User as User / Prompt
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Router
    participant Upstream as Canvas Medical API

    User->>Claude: "Start bulk export for Pat-102"
    Claude->>Truto: call tool: create_a_canvas_medical_patient_export
    Truto->>Upstream: POST /Patient/Pat-102/$export
    Upstream-->>Truto: 202 Accepted (Location: /jobs/Job-555)
    Truto-->>Claude: Result: Job ID Job-555 started
    Claude->>Truto: call tool: get_single_canvas_medical_bulk_export_job_by_id
    Truto->>Upstream: GET /jobs/Job-555
    Upstream-->>Truto: 200 OK (Status: in-progress)
    Truto-->>Claude: Result: Job is still running
    Claude-->>User: "Export started with ID Job-555. Currently in-progress. I will wait and poll again."

Execution Steps:

  1. Claude calls create_a_canvas_medical_patient_export to initiate the background job.
  2. Canvas Medical returns an empty body with the new job ID in the Location header, which Truto parses and returns to the model.
  3. Claude uses the returned ID to call get_single_canvas_medical_bulk_export_job_by_id.
  4. Claude observes the status and informs the user of the progress, ready to retrieve the NDJSON file URLs once complete.

Security and Access Control

Exposing clinical FHIR data to AI models requires strict governance. Truto's MCP tokens include embedded security controls to restrict what an agent can do:

  • Method Filtering: By defining methods: ["read"] during server creation, you completely disable the agent's ability to mutate clinical records. It will only see get, list, and search tools.
  • Tag Filtering: You can restrict the MCP server to specific resource domains by applying tags. For example, tags: ["scheduling"] might expose only appointments, schedules, and slots, completely hiding clinical records like conditions and medications.
  • Expiration (expires_at): You can generate ephemeral MCP servers for temporary agent workflows. Once the timestamp passes, Truto automatically destroys the token in its database and KV edge storage.
  • Dual Authentication (require_api_token_auth): For maximum security, you can configure the MCP server to require a valid Truto API token in addition to the unique URL hash. This ensures that even if an MCP URL is leaked, the caller must still possess valid team credentials to execute a tool.

Moving Beyond Point-to-Point Integrations

Connecting Canvas Medical to Claude requires more than just mapping standard JSON. It demands deep understanding of the FHIR R4 specification, asynchronous bulk data paradigms, and secure form-encoded search endpoints.

Instead of wasting engineering cycles managing OAuth lifecycles and writing boilerplate JSON-RPC handlers for complex healthcare APIs, use Truto to dynamically expose Canvas Medical as secure, agent-ready MCP tools.

FAQ

How does Truto handle Canvas Medical API rate limits?
Truto does not absorb rate limit errors, apply backoff, or automatically retry requests. If Canvas Medical returns an HTTP 429, Truto passes that error directly to the MCP client, while normalizing the upstream rate limit data into standard IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller is responsible for implementing retry and backoff logic.
Does this integration support FHIR R4 standards?
Yes. Canvas Medical's API is built on the FHIR R4 standard, and Truto's dynamically generated MCP tools map directly to these FHIR resource schemas (e.g., Patient, Observation, CarePlan), ensuring the LLM constructs valid FHIR payloads.
How do I extract large amounts of patient data?
For large datasets, you should use Canvas Medical's async bulk data export tools (like create_a_canvas_medical_patient_export), which write data to NDJSON files in the background. The LLM can then poll the bulk_export_jobs resource to retrieve the output URLs when finished.

More from our Blog