Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to SMART App on FHIR

Scalekit connector
Open markdown

The SMART App on FHIR connector lets your AI agent act in each user's SMART App on FHIR account. Each user signs in to SMART App on FHIR once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 81 tools.

Tools
81
What they doRead · write · destructive
33 · 32 · 1633 read32 write16 destructive
Users sign in with

What you can do

  • Manage patients: search, create, update, and delete patient demographics, or pull everything on file for a patient
  • Book appointments and encounters: schedule, reschedule, cancel, and look up appointments and patient visits
  • Record clinical data: create and update conditions, observations, allergies, immunizations, and procedures
  • Manage prescriptions and reports: read and write medication requests, diagnostic reports, and document references
  • Coordinate care: create and update care plans, care teams, and patient goals
  • Look up providers: search and manage practitioners and organizations such as hospitals and clinics

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the SMART App on FHIR connection

    In AgentKit > Connections, create a SMART App on FHIR connection. The name you give it is the connection_name your code passes. See Configure connections.

    Console steps with screenshots

    SMART App on FHIR uses an OAuth 2.0 authorization code flow with PKCE. Because every FHIR server exposes its own endpoints, you supply the authorization and token endpoints, the audience (aud), and the FHIR server domain when you create the connection. You also register a client with your FHIR server to obtain a client ID, and a client secret if the server issues one.

    1. Discover your FHIR server’s SMART configuration

      Every SMART on FHIR server publishes its OAuth endpoints at a well-known discovery URL:

      <fhir-base-url>/.well-known/smart-configuration

      Fetch that URL and note these values:

      • authorization_endpoint — the Authorization endpoint
      • token_endpoint — the Token endpoint
      • the FHIR server base URL, for example https://fhir.example.com/r4 — this gives you both the Audience (aud) value and the FHIR server domain (the same URL without the https:// scheme, for example fhir.example.com)

    2. Register an app with your FHIR server

      • Register a new app in your FHIR server’s developer portal or app-registration console to obtain a client ID. Scalekit uses PKCE, so a public client works; if your FHIR server issues a client secret, note it as well and add it in the next step.

      • When prompted for a redirect URI, leave the field open for now — you’ll copy the exact value from Scalekit in the next step.

    3. Copy the redirect URI from Scalekit

      In the Scalekit dashboard, go to AgentKit > Connections > Create Connection. Find SMART App on FHIR and click Create. Copy the redirect URI — it looks like https://<SCALEKIT_ENVIRONMENT_URL>/sso/v1/oauth/<CONNECTION_ID>/callback.

      Return to your FHIR server’s app registration and paste this redirect URI into the app’s allowed redirect URIs.

    4. Create the connection in Scalekit

      Back in the Scalekit dashboard, finish creating the connection with the values you gathered:

      • Client ID — the client ID from your FHIR server app registration
      • Client Secret — the client secret from your FHIR server app registration, if one was issued; leave blank for a public PKCE client
      • Authorization Endpoint — the authorization_endpoint from .well-known/smart-configuration
      • Token Endpoint — the token_endpoint from .well-known/smart-configuration
      • Audience (aud) — the FHIR server base URL, sent as the required aud parameter on the authorization request
      • FHIR Server Domain — the FHIR server domain without the https:// scheme, for example fhir.example.com. Scalekit routes every tool call to this host

      Under Scopes, select the SMART on FHIR scopes your agent needs. Start with openid and offline_access for identity and refresh tokens, then add resource-specific scopes such as patient/Patient.read, patient/Observation.read, or the broader patient/*.read and patient/*.rs scopes. The scopes you select here must match what’s enabled on your FHIR server app registration.

      Click Save.

    5. Verify the connection is active

      Go to Connected Accounts for your SMART App on FHIR connection and confirm the status shows Active after a user completes authorization.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • customsmartfhir_allergy_intolerance_readRetrieve a single FHIR AllergyIntolerance resource by its logical ID.Read-only

    Get Allergy Intolerance

    Retrieve a single FHIR AllergyIntolerance resource by its logical ID. Represents a patient's allergy or intolerance to a substance.

    Inputs

    allergy_intolerance_idstringrequired
    The logical ID of the AllergyIntolerance resource
  • customsmartfhir_appointment_readRetrieve a single FHIR Appointment resource by its logical ID.Read-only

    Get Appointment

    Retrieve a single FHIR Appointment resource by its logical ID. Appointments represent bookings for a patient, practitioner, or location at a specific time.

    Inputs

    appointment_idstringrequired
    The logical ID of the Appointment resource
  • customsmartfhir_care_plan_readRetrieve a single FHIR CarePlan resource by its logical ID.Read-only

    Get Care Plan

    Retrieve a single FHIR CarePlan resource by its logical ID.

    Inputs

    care_plan_idstringrequired
    The logical ID of the CarePlan resource
  • customsmartfhir_care_team_readRetrieve a single FHIR CareTeam resource by its logical ID.Read-only

    Get Care Team

    Retrieve a single FHIR CareTeam resource by its logical ID.

    Inputs

    care_team_idstringrequired
    The logical ID of the CareTeam resource

Workflows

Proxy API call

Call the FHIR server’s REST API directly through the Scalekit proxy. Use standard FHIR search paths such as /Patient or /Observation.

const result = await actions.request({
  connectionName: 'customsmartfhir',
  identifier: 'user_123',
  path: '/Patient?family=Smith&_count=10',
  method: 'GET',
});
console.log(result);
Search for patients
const patients = await actions.executeTool({
  connector: 'customsmartfhir',
  identifier: 'user_123',
  toolName: 'customsmartfhir_patient_search',
  toolInput: {
    family: 'Smith',
    given: 'Jane',
    birthdate: '1985-04-12',
    _count: 10,
  },
});
console.log('Matching patients:', patients);
Retrieve everything for a patient

Invoke the FHIR $everything operation to pull all clinical resources for one patient in a single Bundle. Pass _type to limit the response to specific resource types.

const bundle = await actions.executeTool({
  connector: 'customsmartfhir',
  identifier: 'user_123',
  toolName: 'customsmartfhir_patient_everything',
  toolInput: {
    patient_id: 'a1b2c3d4-0000-1111-2222-333344445555',
    _type: 'Condition,Observation,MedicationRequest',
    _count: 50,
  },
});
console.log('Bundle entries:', bundle);
Search a patient’s observations
const observations = await actions.executeTool({
  connector: 'customsmartfhir',
  identifier: 'user_123',
  toolName: 'customsmartfhir_observation_search',
  toolInput: {
    patient: 'a1b2c3d4-0000-1111-2222-333344445555',
    category: 'vital-signs',
    date: 'ge2026-01-01',
    _count: 25,
  },
});
console.log('Observations:', observations);
Record a vital-sign observation

Create an Observation such as a heart-rate reading. The code and code_system identify the measurement — this example uses the LOINC code 8867-4 (Heart rate).

const observation = await actions.executeTool({
  connector: 'customsmartfhir',
  identifier: 'user_123',
  toolName: 'customsmartfhir_observation_create',
  toolInput: {
    patient_id: 'a1b2c3d4-0000-1111-2222-333344445555',
    status: 'final',
    code: '8867-4',
    code_system: 'http://loinc.org',
    code_display: 'Heart rate',
    category: 'vital-signs',
    effective_date_time: new Date().toISOString(),
    value: 72,
    unit: '/min',
  },
});
console.log('Created observation:', observation);
All 4 in Healthcare & life sciences