therapyportal-mcp

MCP server for TherapyPortal, the client portal of TherapyNotes (https://www.therapyportal.com/p/<practice>/). It reads upcoming therapy appointments, paperwork the practice sent, the practice's standing forms, balances due, payment receipts and secure messages, and downloads completed documents and receipts as PDFs. It can also send secure messages and upload a file in answer to a document request, each behind a confirm gate.

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

Not read-only

Most tools are reads. Three are writes, and each one reaches the practice and cannot be undone through this server:

All three are annotated destructive and confirm-gated (see below). The server signs no form, fills in no form and makes no payment. Anything that needs a signature (PatientSignatureRequired) is refused, with a pointer to the portal. A download is logged by the practice, the same way the portal logs the click.

On the privacy side, therapyportal_list_clients returns names and date of birth only. The portal's client record also carries the address, phones, email, an SSN field, billing notes and free-text comments, and none of those are ever passed through, on any view.

Tools

Read tools take view. The default is compact (projected to the useful fields); full and raw return more. Text the practice wrote (document titles, instructions, messages) comes back inside an untrusted-content envelope.

Message tools are not verified against real messages. The account this was built against had none, so the thread and message reads return the portal's payload exactly as sent rather than a projection.

Writes

The three writes are derived from the portal's own JavaScript (SecureMessagingDataService, CreateMessageViewV2, ThreadViewV2, DocumentsDataService, the document view controllers and xhrfileuploader) and are UNVERIFIED on the wire: no automated run sends a message or uploads a file, because each one reaches the practice. An owner-supervised live test confirms them later. The lookups they make first (messaging settings, topics, the assigned-clinician check, the document and form lists) were verified live, read-only.

Before showing a preview, each write checks against live reads: the client is one of yours (therapyportal_list_clients), the practice has secure messaging turned on, the topic exists for that client, and, for an upload, that the document or form exists, is not completed, asks for an upload and needs no signature.

• Messages. 1 to 5000 characters. Plain text by default, sent as the portal's editor sends it (one HTML paragraph per line). With format: "markdown", bold, italic, lists, headings and quotes are sent formatted, limited to what the portal's editor offers a client; a link is sent as its text and address, since clients get no link tool. A practice may refuse new messages after several unanswered ones; a refusal says so. Archived conversations cannot be replied to.

• Uploads. Give exactly one source:

  • file_path (local installs): the file must be inside THERAPYPORTAL_UPLOAD_DIR (default ~/Downloads, ~/Documents or ~/Desktop) and be a regular file (no symlinks). A hosted server refuses file_path with a "this server is remote" error: it cannot see the caller's files.
  • inline ({filename, content_base64, mime_type?}): the bytes as base64, strictly decoded (a truncated or mangled payload is refused, not sent). Works anywhere, but every byte rides in one request; keep it small.
  • blob_key (hosted): call therapyportal_upload_slot with the filename, PUT the file to the returned uploadUrl (its curl does exactly that), then pass the blobKey. The preview reads the uploaded copy and binds its SHA-256; the confirmed call re-reads it (a changed file is refused) and deletes it only once the portal accepted the upload. A failed or unconfirmed upload keeps it; a failed delete is reported, not thrown.

  Every source gets the same checks: an allowlisted extension, contents that match it, at most 25 MB, and the SHA-256 in the preview. Legacy .doc is refused (its format cannot be checked before upload); save it as PDF or .docx. The file is staged in 100 KB segments, validated by the portal, and only then submitted. Only the submit reaches the practice.

• Sent once. A write is posted exactly once. It is never replayed after a re-sign-in, on either transport. A send 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.

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 exact request (for an upload, the file's name, type, size and SHA-256) and the shown preview are bound into the token, so an argument, file or portal state that changed since the preview is refused as DRAFT_CHANGED. Values that change on every send (the upload guid, the document date) are made at send time and are not bound. Practice-written text in a preview or a result (topic names, document titles, the returned conversation) is wrapped as untrusted content. MCP_CONFIRM_MODE / MCP_CONFIRM_ELICITATION tune the gate (see Configuration).

Transports

The two can run side by side. A server-side sign-in does not end your browser's portal session (checked live), and the portal signs out an idle browser tab on its own after a while; that is the usual reason the bridge reports "not signed in".

A rejected password or date of birth is never retried. The date-of-birth check locks after a few wrong dates, so the server tries it once.

Configuration

Copy .env.example to .env for a local install.

{
  "mcpServers": {
    "therapyportal": {
      "command": "npx",
      "args": ["-y", "@chrischall/therapyportal-mcp"],
      "env": { "THERAPYPORTAL_PRACTICE": "<code>" }
    }
  }
}

Without the server

skills/therapyportal-fpx does the same reads (not the writes) from a shell with the fpx CLI, through the signed-in tab. See its SKILL.md.

Development

npm install
npm run build
npm test                 # typecheck + vitest, all mocked
npm run test:coverage    # 100% threshold

The wire protocol (tokens, sign-in, download jobs, the write shapes) is in docs/THERAPYPORTAL-API.md.