insync-mcp

MCP server for an InSync Healthcare (Qualifacts) patient portal — the behavioral-health portals at https://<practice>intouch.insynchcs.com (the owner's is pfbhintouch). It reads appointments, medications, allergies, secure messages, forms, surveys, documents, profile and account balance; downloads portal files; uploads an insurance-card image; and sends secure messages, refill requests, appointment requests and cancellation requests.

This project was developed and is maintained by AI. Use at your own discretion. It reads personal health information, and only ever from the signed-in user's own account.

Not read-only

This server is not read-only. Alongside the reads it:

• downloads message attachments and account documents (a download changes no portal state and has an inverse — not persisting — so the download tools are still annotated readOnly);

• uploads an insurance-card image to your own profile — a real write the practice sees, with no delete/undo through this server, so it is annotated destructive and confirm-gated (see below);

• insync_get_message opening an unread message can mark it read, which the practice can see and which has no inverse. That tool is annotated destructive and gated behind allow_mark_read (default false): until you pass it, the tool returns the list-row metadata and a note, and never fetches the detail;

• sends things to the practice, each one confirm-gated and annotated destructive, because none can be unsent or withdrawn through this server:

  Tool	What it sends	Look up first with
  insync_send_message	a new secure message to a practice group	insync_list_message_recipients
  insync_reply_message	a reply to a message (refuses an unread one unless allow_mark_read)	insync_list_messages
  insync_request_refill	a refill request for current medications	insync_get_refill_options
  insync_request_appointment	an appointment request in an open slot (the practice confirms it)	insync_find_appointment_slots
  insync_cancel_appointment	a cancellation request with a reason (the practice reviews it)	insync_list_appointments

Not built: message attachments and patient signatures on messages, the "flexible window" appointment request, withdrawing a request, payments, and form submission.

Reading a message

insync_get_message returns the body as plain text by default: lines, numbered items and link targets kept. format: "markdown" keeps bold, lists, tables and links with their text as well. Either way, text the sender hid from view (display:none) is dropped. Messages you send are plain text.

Two ways to authenticate

Bridge-less signs in server-side with its own cookie jar — no browser, no extension — which is what makes hosting possible. The password login was live-verified on 2026-10-28 against the owner's practice: a single POST to Login/userLogin, no MFA, no device challenge. A rejected sign-in is never retried automatically, because the portal counts failed attempts toward an account lockout. The cookie jar lives in memory for the life of the process; nothing is written to disk.

Browser bridge relays requests through your own signed-in portal tab via the fetchproxy bridge and the ContextMint Bridge extension, reusing that session. It holds no credentials at all — its one virtue — so prefer it unless you specifically want the hosted, bridge-less path.

Selection is automatic: server when both credentials are set, otherwise fetchproxy. INSYNC_TRANSPORT=server|fetchproxy forces one.

Storage configuration is held, never used directly

The login response carries some object-storage configuration. This server never uses it to talk to object storage directly — all file transfer goes through the portal's own session-authorized endpoints, so every read and write stays under the portal's per-patient authorization. Any such configuration is captured onto the session only, and is scrubbed by value from every tool result, error and log. A download URL is refused unless it stays on *.insynchcs.com.

Writes are unverified on the wire

Every lookup the write tools make — recipients, the reply form, the refill pick lists, facilities, providers, visit types, slots, the cancellation window — was verified live, read-only. The sends are derived from the portal's own JavaScript and partial views. A new message (insync_send_message) and a reply (insync_reply_message) were verified live on 2026-10-28 in owner-supervised tests; the refill, appointment and cancellation sends have not been exercised yet, because each one creates a request the practice acts on. A send that the portal answers with a 5xx, or whose connection drops, is reported as status: "unknown" rather than as an error, so a model checks the matching list before trying again instead of sending twice. See docs/INSYNC-API.md.

Insurance-card upload

The insurance-card upload shape is derived from the portal's own JavaScript and is UNVERIFIED on a live POST: no automated run performs a real upload, because it mutates practice-visible state. An owner-supervised live test confirms it later. The confirm gate, the file vetting and the re-read-after-write guidance are all in place; only the on-the-wire success signal is pending confirmation. See docs/INSYNC-API.md.

Each side of the card arrives by exactly one route: front_path/back_path (a file on this machine — local installs only, refused on a hosted server), front_inline/back_inline ({filename, contentBase64}, for a small image), or front_blob_key/back_blob_key — on a hosted server, call insync_upload_slots for a signed upload URL, PUT the image to it, and pass the returned blobKey. The uploaded copy is deleted only after the portal accepts the card; a rejection or an unconfirmed outcome keeps it.

Downloads

On a local install a download is written to a private (0600) file and the path returned. On a hosted server an image comes back inline when it fits (10 MiB); any other file, and an image over that size, comes back as a short-lived signed download link from the host's blob store — never a path on the runner's disk.

Confirm gate

Every write is gated by @chrischall/mcp-utils' confirmWrite, through its defineWrite / registerWrite. The first call sends nothing and returns a preview + a confirmToken; only a second call carrying that token — after you approve the preview — sends. The send/request tools may read the portal while previewing (to resolve names and check the slot or recipient); the upload preview reads nothing from the portal. The exact request body (for the upload, the image bytes) and the shown preview (including each image's SHA-256) are bound into the token, so an argument, file or portal state that changed since the preview is refused as DRAFT_CHANGED. MCP_CONFIRM_MODE / MCP_CONFIRM_ELICITATION tune this (see the env table).

Install

{
  "mcpServers": {
    "insync": {
      "command": "npx",
      "args": ["-y", "@chrischall/insync-mcp"],
      "env": {
        "INSYNC_PORTAL": "https://<practice>intouch.insynchcs.com",
        "INSYNC_USERNAME": "your-portal-username",
        "INSYNC_PASSWORD": "your-portal-password"
      }
    }
  }
}

Leave INSYNC_USERNAME / INSYNC_PASSWORD out to use the browser bridge instead; that path needs ContextMint Bridge, the fetchproxy browser extension, installed from its releases page, and your portal open and signed in. Then call insync_healthcheck; the first call prints a pair code to approve once in the extension popup.

Configuration

A .env is read for local development; real environment values always win. See .env.example.

The fpx skill

Bundled under skills/insync-fpx/ is a lightweight alternative to running this server: the insync-fpx skill reads the same portal from a shell through your signed-in browser tab with the fpx CLI (capture the session once, then curl the endpoints). Use it when you want portal data in a script or without the MCP installed. The MCP is the richer surface; the skill is the quick path.

Context groups

Every tool except insync_healthcheck publishes a _meta.mint hint (group health) for mcp-host's context groups: inert data to any other client. The three canonical reads — insync_list_appointments (what's on), insync_list_messages (what's new) and insync_list_forms (what's due) — also take view: "brief", one line per item, title — <ISO date | no date> — <status>, inside the untrusted-data envelope. The other view values are unchanged.

How it works

The portal is ASP.NET MVC. A signed-out session is never a 401: it is the login page served 200 (<title>Portal :: Login), an {"isTimeout":true} body, or a 302 to /Login. This server detects that by content and surfaces an actionable "not signed in" error naming the live transport. Every endpoint shape — reads, file transfer and the upload — is documented, keys only (no values, which are PHI), in docs/INSYNC-API.md.

Upgrading

0.4.0 — download output. insync_download_attachment and insync_download_document no longer return a base64 field. Inline bytes now arrive as MCP content blocks after the JSON block (an image block for PNG/JPEG/GIF/WebP, otherwise an embedded resource), and the JSON says how the file was delivered: delivered_via (image, resource, link or disk), plus saved_to, or url + expires_at for a signed link on a hosted server. A file too large to inline is now delivered by link or to disk instead of being replaced by a note. A caller that read base64 should read the content block instead.

License

MIT