MCP Apps · demos

CHOIR Provider MCP

Demo only, no PHIs

This server gives demo pain calculators to AI clients through the Model Context Protocol (MCP) and interactive MCP Apps.

1. About this MCP

CHOIR Provider MCP is an MCP server for demos. The server exposes tools that score or convert clinical demo values. Many tools open an interactive calculator App in the client.

The server supports:

Demo only, no PHIs. Factors and cut-points are simplified.

Use this server with Claude Desktop, Claude.ai connectors, or the companion choirprovider-web host. See §6 MCP features for how each feature works and how to try it.

2. Endpoints

Public demo host: choirprovider-mcp.onrender.com. Replace the host if you run a local instance.

MCP https://choirprovider-mcp.onrender.com/mcp
Health https://choirprovider-mcp.onrender.com/api/health
Catalog https://choirprovider-mcp.onrender.com/api/calculators
Admin https://choirprovider-mcp.onrender.com/admin
OAuth https://choirprovider-mcp.onrender.com/.well-known/oauth-authorization-server
Open health JSON Open calculator list Open admin

3. How to install

MCP access is authenticated. Use OAuth for Claude Desktop / Claude.ai connectors, or an API key for programmatic hosts such as choirprovider-web. Anonymous /mcp access is off by default.

3.1 Claude Desktop or Claude.ai (OAuth)

Do these steps:

  1. Open Claude settings for connectors or custom MCP servers.
  2. Add a remote MCP server. Use the MCP URL: https://choirprovider-mcp.onrender.com/mcp
  3. Complete OAuth when the client requests authorization. Sign in with a seeded or admin-created account (manage users at /admin).
  4. Approve the requested scope mcp:tools when the client shows it.
  5. Confirm that tools appear (for example list_calculators, open_calculator, score_audit_c).

3.2 choirprovider-web (API key)

The chat demo host calls MCP with a Bearer API key. Use one shared secret for both services:

  1. Choose a long random secret and set MCP_SERVER_API_KEY on both the MCP server and choirprovider-web (same value).
  2. Confirm MCP_SERVER_URL on the web service points at this MCP origin (the host appends /mcp if needed).
  3. Open choirprovider-web and run a calculator prompt.
  4. Optional: create extra cpk_… keys in /admin for other clients.
Requests without a valid OAuth token or matching MCP_SERVER_API_KEY receive 401.

4. Tools and calculators

Call list_calculators to read the live catalog. The table below lists the main demo modules.

Id Name Primary tools
local-anesthetic Local anesthetic max dose calculate_local_anesthetic_max
steroid Steroid conversion convert_steroid
fibromyalgia Fibromyalgia 2016 (WPI + SSS) score_fibromyalgia_2016, open_calculator
budapest Budapest CRPS criteria score_budapest, open_calculator
opioid Opioid MME conversion open_opioid_calculator, convert_opioid
audit-c AUDIT-C alcohol screen score_audit_c
pcs Pain Catastrophizing Scale score_pcs
ort / riosord Opioid risk tools score_ort, score_riosord
taps / kinesiophobia TAPS and F-TSK-6 score_taps_oud, score_kinesiophobia
periop / rems / pt-referral Guidance modules periop_hold_guidance, REMS tools, generate_pt_referral
choir-parser / compose Parse and note tools parse_choir_survey, compose_educational_note

Rule for interactive UIs: open one App tool per user request. Do not call the same calculator tool twice in one turn (for example two convert_steroid calls for “A vs B”).

6. How to test features

5.1 Health and catalog

  1. Open /api/health in a browser.
  2. Confirm that the JSON field ok is true.
  3. Open /api/calculators and confirm that the calculator list is not empty.

5.2 REST smoke tests (no MCP client)

Send HTTP POST requests to the REST helpers:

# Local anesthetic (example)
curl -s -X POST "$ORIGIN/api/local-anesthetic" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"lidocaine","weightKg":70,"withEpinephrine":false,"concentrationPercent":1}'

# Steroid conversion (example)
curl -s -X POST "$ORIGIN/api/steroid" \
  -H "Content-Type: application/json" \
  -d '{"fromSteroidId":"dexamethasone","fromDoseMg":10,"toSteroidId":"triamcinolone"}'

5.3 MCP tools in a chat client

  1. Connect the client to the MCP URL (section 3).
  2. Ask the model to call list_calculators.
  3. Ask for a single calculator. Examples:
    • “Open AUDIT-C for a male patient who drinks a few times a week.”
    • “Convert Decadron 10 mg to Kenalog (one conversion only).”
    • “Open the PCS calculator.”
    • “Max lidocaine dose for 50 kg without epinephrine.”
  4. Confirm that one App UI opens (when the client supports MCP Apps).
  5. Change a form field. Confirm that the live score updates. Ask the model to interpret the current result.

5.4 Live panel state (Apps + host)

Do these checks when the client shows the calculator App:

  1. Open a calculator (for example PCS or AUDIT-C).
  2. Do not edit the form. Ask “What is the current score?”
  3. Confirm that the model uses the panel values (including defaults after open).
  4. Edit the form. Ask the same question again.
  5. Confirm that the model uses the new values. Prefer model context over an old tool result.

5.5 Export and references (App footer)

  1. Open a calculator App that shows a result.
  2. Select Export result to download or copy text.
  3. Select Demo references to open documentation links in the host browser.

5.6 OAuth, API keys, and admin

  1. Open /admin and sign in as an admin.
  2. Confirm that the user list and API keys section load.
  3. Create an API key for choirprovider-web and set MCP_SERVER_API_KEY on the web service.
  4. From Claude, start OAuth and complete the authorize flow with a user account.
  5. Confirm that the client can call tools after token issue.

6. MCP features

This section lists the main MCP capabilities used in this demo, how the server or App uses each one, and how you can try it. Prefer the companion web host for App UI features (sync, expand, export). Prefer Claude Desktop / Claude.ai for remote connector, OAuth, prompts, and resources.

Best place to try Apps: choirprovider-web (uses an API key against this MCP server).
tools · Streamable HTTP

Tools over Streamable HTTP

What it is

Standard MCP tools at /mcp (for example list_calculators, score_audit_c, convert_steroid).

How we use it

Every calculator is a tool. Many tools also open an MCP App when the client supports the Apps extension. Tool results include text plus structured content the model can reuse.

How to try it

Connect a client to the MCP URL in §2. Ask for a catalog: “list calculators”. Or call list_calculators from the client tools UI. REST smoke: open health or the catalog API.

MCP Apps · ui:// resources

Interactive MCP Apps

What it is

HTML UIs registered as resources (ui://choirprovider/mcp-app.html, ui://opioid-equivalence/mcp-app.html) and opened when an App tool runs.

How we use it

The model calls a scoring or open tool once. The host shows a sandboxed calculator form (FT-style shell). You edit fields and see live demo scores without a new chat turn for every keystroke.

How to try it

In the web host or Claude, ask something concrete: “AUDIT-C for a male who drinks a few times a week, 3–4 drinks, binge monthly.” Confirm one iframe opens. Edit a field and watch the score update. Edge bookmarks on the web host jump back to scrolled-away Apps.

ui/update-model-context · sendMessage

Panel → model sync

What it is

After you change the App form, the live panel state is pushed into the host model context so later answers use the UI score, not only the first tool result.

How we use it

The App prefers updateModelContext when the host advertises it (this CopilotKit host is patched). Otherwise it falls back to a quiet context message. Debounce and dedupe avoid spam. The header chip shows Synced to model or Synced to chat; you can force Sync to chat.

How to try it

Open AUDIT-C from a tool call. Change gender or item scores. Wait about 1–4 seconds (or click Sync). Ask: “based on the panel, is the screen positive?” The model should follow the live form, not the original tool bubble. On the web host, panel updates appear as quiet footnotes, not large chat bubbles.

App.callServerTool

Live recompute via the server

What it is

From inside the App iframe, callServerTool runs the real MCP tool (proxied by the host) so client UI and server share one scoring path.

How we use it

On each form change the App paints a pure client score first (fast), then debounced tools/call confirms the same tool on the server (LA, steroid, fibro, Budapest, ME/CFS, ORT, RIOSORD, AUDIT-C, PCS, TSK, opioid, periop, PT, REMS, TAPS, CHOIR, compose). If the host cannot proxy, the client score still works.

How to try it

In the web host, open steroid conversion and change dose or drug. The result should update immediately. Network tools in DevTools may show proxied tools/call traffic. On hosts without proxy, scores still update from local math.

prompts/list · prompts/get

Named MCP prompts

What it is

Server-registered demo vignettes. Clients load them as named prompts instead of free-typing a scenario.

How we use it

Each prompt returns one user message that steers the model to call one tool and open one App (for example steroid_vs_convert forces a single convert_steroid call).

How to try it

In Claude Desktop or any client with prompt support: open prompts, pick la_max_dose or audit_c_screen, run it, confirm one App opens. See §7 for the full list. Web host sample chips are separate demo shortcuts with the same scenarios.

resources/list · resources/read

Teaching resources

What it is

Non-UI MCP resources for shared tables, cutoffs, and the demo disclaimer (plus App HTML resources under ui://).

How we use it

URIs under choirprovider://demo/* expose the same catalog, MME/steroid/LA tables, and cutoffs the tools use, so the model can read reference material without hard-coding it.

How to try it

In a client that supports resources: resources/list, then resources/read on choirprovider://demo/index or choirprovider://demo/cutoffs. Full URI list in §8.

completions

Argument completions

What it is

MCP completion callbacks on tool arguments so clients can autocomplete ids as you type.

How we use it

Calculator ids, LA agents, steroids, opioid ids/aliases, periop meds, PT diagnoses, REMS task/aberrant ids, and gender fields use completable() filters.

How to try it

In a client that shows argument autocomplete (for example some Claude Desktop or IDE UIs), start a tool call such as convert_opioid and type dil or oxy in the opioid id field. Suggestions should include table ids and aliases like dilaudid.

downloadFile · openLink

Export result and demo references

What it is

Host APIs to download a text export from the App and to open external teaching URLs safely.

How we use it

Footer Export result uses downloadFile when available (this host is patched), else clipboard. Demo references uses openLink (or a new tab fallback) for criteria and guideline pages.

How to try it

Open any calculator App with a filled result. Click Export result — a .txt download or clipboard copy. Click Demo references — a new tab with a related paper or agency page. See also §5.5.

ui/request-display-mode

Expand / fullscreen App

What it is

The App can request inline or fullscreen layout from the host.

How we use it

Footer Expand / Exit expand calls requestDisplayMode. The CopilotKit host patch grows the iframe (taller panel, accent border) for body maps and long checklists.

How to try it

Open fibromyalgia or Budapest in the web host. Click Expand in the App footer. The frame should grow; click Exit expand to return to inline.

structuredContent · reverseNote

One App for steroid “A vs B”

What it is

Tool design that avoids two parallel converter UIs for a simple comparison.

How we use it

convert_steroid and the steroid_vs_convert prompt open one direction. The result text includes a reverse equipotency line (reverseNote). The form Swap button flips direction without a second tool call.

How to try it

Ask: “Decadron 10 mg vs Kenalog” or run prompt steroid_vs_convert. Confirm a single steroid App. Read the reverse line in the narrative; use Swap for the other direction.

OAuth 2.1 · DCR

Remote connector auth (Claude)

What it is

OAuth 2.1 with Dynamic Client Registration so remote clients (Claude connectors) can authorize without a pre-shared client id.

How we use it

MCP URL + authorize/token endpoints. Seeded users and /admin for user management. Scope mcp:tools. Anonymous MCP is off by default.

How to try it

Follow §3.1: add custom connector with https://choirprovider-mcp.onrender.com/mcp, complete browser sign-in (seed password in README), then call a tool. Open /admin as admin to list users.

API keys · Bearer

Programmatic access (choirprovider-web)

What it is

Admin-issued API keys accepted as Authorization: Bearer cpk_… on /mcp, alongside OAuth tokens.

How we use it

Keys are created in /admin, stored hashed, and shown once. choirprovider-web sends the key via MCP_SERVER_API_KEY on every tools/list and tools/call (including App proxy calls).

How to try it

Follow §3.2: create a key in admin, set it on the web service, open choirprovider-web. Revoke a key in admin to cut off that host.

7. MCP prompts (catalog)

Named demos for clients that support prompts/list and prompts/get. How they work and how to try them: §6 · Named MCP prompts.

Examples

  • la_max_dose
  • steroid_vs_convert
  • fibro_sparing_head_neck
  • audit_c_screen
  • pcs_catastrophizing
  • opioid_mme_rotation

More

  • ort_risk
  • riosord_overdose_risk
  • periop_holds
  • rems_monthly
  • pt_referral_fibro
  • list_demo_scenarios
  • teaching_disclaimer
  • budapest_crps_leg

Each prompt returns a short user message that directs the model to call one tool and open one App UI.

8. Teaching resources (catalog)

Non-UI content through resources/list and resources/read. See §6 · Teaching resources for usage.

Index choirprovider://demo/index
Disclaimer choirprovider://demo/disclaimer
Cutoffs choirprovider://demo/cutoffs
Tables choirprovider://demo/opioids · choirprovider://demo/steroids · choirprovider://demo/local-anesthetics
Catalog choirprovider://demo/catalog
Prompts list choirprovider://demo/prompts
App HTML ui://choirprovider/mcp-app.html

These resources share the same demo tables and cutoffs the tools use. They do not replace professional guidelines.

9. MCP Apps UI (controls)

Interactive calculators use the Financial Times–style shell: paper background, claret accent, and clear form labels. Multi-calculator App: ui://choirprovider/mcp-app.html. Opioid App: ui://opioid-equivalence/mcp-app.html.

After an App opens in a host that supports MCP Apps:

Full chat demo with iframes and bookmarks: run the companion web/ package against this MCP URL.