Developers building on Healthie's GraphQL API now use AI coding agents (Claude Code, Cursor, and others) to scaffold integrations, generate queries, and automate workflows. This guide covers how to connect your agent to Healthie, test safely in sandbox, and get productive fast.

Connect your agent to Healthie via Dev Assist

Healthie Dev Assist is our MCP server for AI-powered development on Healthie's GraphQL API. It connects coding agents like Claude and Cursor directly to Healthie's infrastructure, giving your agent live schema access, query execution, and read/write capability in your sandbox environment.

Classic MCP servers expose one operation per tool call. Dev Assist 2.0 uses a code execution model: your AI writes a small TypeScript program that performs all steps in a single turn, cutting schema exploration from 5–10 tool calls down to 1–2.

const mutations = await healthie.search("appointment", { kind: "mutation" });
const details = await healthie.introspect("createAppointmentInput");
return { mutations, details };

Set up Dev Assist

You need a Healthie sandbox account to get started. The full Quick Start Guide is on GitHub.

git clone https://github.com/healthie/healthie-dev-assist.git
cd healthie-dev-assist
npm install
npm run setup

Connect to Claude Code

claude mcp add healthie -- npx tsx /path/to/healthie-dev-assist/src/server.ts

Verify the connection:

claude mcp list

Connect to Cursor

Add to Cursor’s MCP settings:

{
  "mcp": {
    "servers": {
      "healthie-dev-assist": {
        "command": "npx",
        "args": ["tsx", "/path/to/healthie-dev-assist/src/server.ts"]
      }
    }
  }
}

Add your API key for read/write access

Add your sandbox API key to a .env file in the project directory:

HEALTHIE_API_KEY=<your-sandbox-api-key>

Schema search and introspection work without a key. Queries and mutations require one. With a key connected, your agent can create patients, schedule appointments, query records, and write chart notes across the full Healthie workflow in sandbox.

What your agent can do with Dev Assist connected

Your AI assistant gets access to a healthie object inside a sandboxed Node.js environment:

Method	What it does
healthie.search(query, options?)	Search the schema by keyword
healthie.introspect(typeName, options?)	Get full details on any type, query, or mutation
healthie.query(graphql, variables?)	Execute a GraphQL query
healthie.mutate(graphql, variables?)	Execute a GraphQL mutation

Here’s what a real development session looks like. A developer wants to build an intake flow: create a patient, schedule an appointment, and send a welcome message. With Dev Assist connected, that whole workflow gets built in a single agent session.

“I need to build an intake flow that creates a new patient, schedules their first appointment with a specific provider, and sends them a welcome message. Walk me through the mutations I need and show me the required fields for each.”

Dev Assist finds the right mutations in one turn:

const patientMutation = await healthie.search("createClient", { kind: "mutation" });
const appointmentMutation = await healthie.search("createAppointment", { kind: "mutation" });
const messageMutation = await healthie.search("createConversation", { kind: "mutation" });

const patientFields = await healthie.introspect("createClientInput");
const appointmentFields = await healthie.introspect("createAppointmentInput");
const messageFields = await healthie.introspect("createConversationInput");

return { patientMutation, appointmentMutation, messageMutation, patientFields, appointmentFields, messageFields };

Dev Assist returns the full schema for all three operations. The agent then scaffolds the complete intake flow:

const newPatient = await healthie.mutate(`
  mutation createClient($input: createClientInput!) {
    createClient(input: $input) {
      client {
        id
        full_name
        email
      }
      messages { field  message }
    }
  }
`, {
  input: {
    email: "patient@example.com",
    first_name: "Jane",
    last_name: "Doe",
    dietitian_id: "<your-provider-id>"
  }
});

const appointment = await healthie.mutate(`
  mutation createAppointment($input: createAppointmentInput!) {
    createAppointment(input: $input) {
      appointment {
        id
        date
        appointment_type { name }
      }
      messages { field  message }
    }
  }
`, {
  input: {
    user_id: newPatient.createClient.client.id,
    provider_id: "<your-provider-id>",
    appointment_type_id: "<your-appointment-type-id>",
    date: "2026-05-01T10:00:00-05:00"
  }
});

const conversation = await healthie.mutate(`
  mutation createConversation($input: createConversationInput!) {
    createConversation(input: $input) {
      conversation { id }
      messages { field  message }
    }
  }
`, {
  input: {
    owner_id: newPatient.createClient.client.id,
    simple_added_users_ids: ["<your-provider-id>"],
    note: "Welcome to the practice! We're looking forward to your first appointment."
  }
});

Without Dev Assist, getting to this point means reading through the full API docs, identifying the right mutations across multiple pages, inferring required fields from schema documentation, and manually testing each call.

With Dev Assist, the agent handles schema discovery and scaffolding in the same session where you describe what you want to build.

Understand Healthie’s two environments

Healthie runs two independent environments. Data and settings cannot transfer between them.

Environment	API URL	Use for
Sandbox	https://staging-api.gethealthie.com/graphql	Development, testing, agent exploration
Production	https://api.gethealthie.com/graphql	Live data, real workflows

Generate a sandbox API key

Create a Healthie Sandbox account and select “Digital Health Startup” when prompted. Once you have a sandbox account:

1. Go to Organization > Members and add your team member
2. Edit member permissions to enable “Can view and manage developer features (webhooks, API keys, etc).”
3. Navigate to Developer Settings and generate a sandbox API key
4. Store your API key as an environment variable. Never put it in a prompt or config file that your agent can read.

export HEALTHIE_API_KEY=<your-sandbox-api-key>

Give your agent Healthie’s docs

Healthie’s API documentation is at docs.gethealthie.com. It covers every query, mutation, and data model across the platform: scheduling, charting, billing, telehealth, provider management, patient engagement, and more. The docs ship with a GraphiQL API Explorer so you can run queries and inspect types interactively before writing any code.

• Full API/UI parity. Every feature in Healthie’s product is accessible via the API. Our internal engineers use the same GraphQL API we give to developers — no feature gaps, no reduced surface.
• Weekly schema changelog. Every Friday, Healthie publishes a changelog entry capturing all GraphQL schema changes from the prior week, backfilled 12 months. Your agent stays current without manual tracking.
• Additive changes only. Schema changes are backwards-compatible wherever possible. Queries your agent writes today keep working as Healthie ships new features.

PHI, BAAs, and keeping patient data safe

Dev Assist is built to connect to Healthie’s staging environment, which is not certified to house any PHI. Keep all real patient data out of your development workflow entirely: use synthetic records and test fixtures from the start.

For production integrations that touch real patient data, check your AI tool’s compliance documentation and confirm a BAA is in place before connecting it to a production Healthie environment.

Get started

Dev Assist is free. All you need is a Healthie sandbox account. To request access, reach out to hello@gethealthie.com. Marketplace partners building integrations can contact marketplace@gethealthie.com.