clinic-mcp
clinic-mcp
診療予約およびインテークのためのリファレンスModel Context Protocolサーバーです。厳密な型定義、構造化されたエラー処理、データ層で強制されるテナント分離を備えたTypeScriptで構築されています。データは合成されたものであり、これは臨床用ソフトウェアではありません。
この目的は、データ分離と根拠のある出力を必要とする業種において、本番環境向けのMCPサーバーがどのような形をしているかを示すことです。これは私がRentiveで書いているコードと同じ形状であり、機密情報を漏洩させることなくパターンをレビューできるように、モックデータと異なるドメインを使用しています。
MCPの理由
LLMアプリケーションは、プロバイダーごとのアドホックな関数定義、独自の引数解析、共有トランスポートの欠如、一貫性のないエラーモデルなど、同じ配線を何度も作り直しています。MCPは、この配線層を修正するための小さなオープンプロトコルです。サーバーは型定義されたツールのリストをstdio(またはHTTP)経由で公開し、MCP対応のクライアント(Claude Desktop、IDE統合、カスタムエージェント)は同じ仕組みでそれらを発見し、呼び出すことができます。
ドメインバックエンドにとって、これはツールを一度書けばどこでも動作することを意味します。エージェントビルダーにとっては、ツールスキーマを手作業で作成するのをやめ、サーバーを構成し始めることを意味します。
Related MCP server: tenant-scoped-crm
アーキテクチャ
flowchart LR
Client["MCP client<br/>(Claude Desktop, custom agent)"]
Server["clinic-mcp server"]
Tools["Tools<br/>find_available_slot<br/>book_appointment<br/>record_intake<br/>search_protocols<br/>escalate_to_oncall"]
Store["ClinicStore<br/>tenant-scoped accessors"]
Seed[("seed.json<br/>synthetic clinics, providers,<br/>patients, protocols")]
Client -->|stdio JSON-RPC| Server
Server --> Tools
Tools --> Store
Store --> Seedすべてのツールは clinic_id を受け取り、ストアはすべての読み取りと書き込みがそのクリニックにスコープされることを強制します。テナント間アクセスは、誤った行を黙って返すのではなく、TenantMismatchError をスローします。これは、本番環境のPostgresで強制される行レベルセキュリティのパターンを反映しており、ここではアプリケーションコード内で表面化させることで、1つのファイル(src/store/index.ts)で保証をレビューできるようにしています。
ローカルでの実行
Node 20以上とpnpmが必要です。
git clone https://github.com/dominikstefanski/clinic-mcp.git
cd clinic-mcp
pnpm install
pnpm test # 29 tests
pnpm typecheck
pnpm dev # boots the server on stdioサーバーは起動時に src/store/seed.json を読み込み、clinic_north(一般診療、循環器科、皮膚科)と clinic_west(小児科、一般診療)の2つの合成クリニックを提供します。
Claude Desktopへの接続
Claude Desktopの設定(macOS: ~/Library/Application Support/Claude/claude_desktop_config.json)に以下を追加します。パスはローカルのクローン先に置き換えてください。
{
"mcpServers": {
"clinic-mcp": {
"command": "npx",
"args": ["-y", "tsx", "/absolute/path/to/clinic-mcp/src/server.ts"]
}
}
}Claude Desktopを再起動します。接続メニューの下に5つのツールが表示されます。*「来週の月曜日の午前にclinic_northで一般診療の空きを見つけて」*のようなプロンプトを試してみてください。
ツールリファレンス
すべてのツールは、成功時に { ok: true, ...result } を、失敗時に { ok: false, error: { code, message } } を返します。入力はzodで検証されます。MCPレベルの引数エラーは、フィールドの詳細を含む validation エラーとして返されます。
find_available_slot
指定された期間内の専門分野の空き予約枠を検索し、競合をスキップします。
フィールド | 型 | 備考 | |||
| string | 必須 | |||
| enum |
|
|
|
|
| string | ISO 8601 開始(含む) | |||
| string | ISO 8601 終了(含まない) | |||
| int | 15〜120、デフォルト30 | |||
| int | 1〜50、デフォルト10 |
book_appointment
予約を作成します。呼び出し元が提供する idempotency_key が必要です。リプレイが発生した場合は、二重予約を防ぐために元の予約を返します。音声エージェントは再試行を行うため、これは必須です。
フィールド | 型 | 備考 |
| string | 必須 |
| string |
|
| string |
|
| string | ISO 8601 |
| int | 15〜120、デフォルト30 |
| string | 1〜500文字 |
| string | 8〜128文字、呼び出し元が提供 |
{ appointment, idempotent_replay } を返します。
record_intake
構造化されたインテークメモを保存し、トリアージレベルを割り当てます。
フィールド | 型 | 備考 |
| string | 必須 |
| string |
|
| string[] | 1〜20エントリ |
| int | 1〜10、患者申告 |
| string | ISO 8601 |
| string | オプション、最大2000文字 |
トリアージルール: 重症度 >= 8 は urgent、>= 5 は elevated、それ以外は routine。
search_protocols
クリニックのプロトコルライブラリをキーワード検索します。モデルが回答時に引用できるランク付けされたスニペットを返します。
フィールド | 型 | 備考 |
| string | 必須 |
| string | 1〜500文字 |
| int | 1〜20、デフォルト5 |
現在の実装は、タイトル重み付け(3倍)を伴う単純なTFスコアです。これは検索ツールのインターフェースを実証するために存在します。本番環境では、バックエンドをベクトル検索に置き換えます(設計ノートを参照)。
escalate_to_oncall
既存の予約を緊急としてマークし、クリニックのオンコール担当プロバイダーに再割り当てします。
フィールド | 型 | 備考 |
| string | 必須 |
| string |
|
| string | 1〜500文字、予約の理由に追加 |
{ appointment, on_call_provider, reassigned } を返します。
設計ノート
テナント分離はツールではなくストアで強制されます。 ツールは clinic_id を受け取り、それを下位に渡します。ストアはすべてのアクセサーで所有権を検証し、不一致の場合は TenantMismatchError をスローします。明日新しいツールを追加しても、誤ってクリニック間でデータが漏洩することはありません。ストアがそれを許可しないからです。
書き込み時の冪等性。 book_appointment は idempotency_key を必要とします。実際の呼び出し元(音声エージェント、再試行ループ、ネットワークの不具合)はリクエストを繰り返すため、再試行に対して重複予約を作成する医療システムは、初日から信頼を失うシステムです。
スローされる文字列よりも構造化されたエラー。 すべてのドメイン障害は、安定した code を持つ型付きの DomainError サブクラスです。MCPラッパーはそれらを { ok: false, error: { code, message } } に変換します。クライアントは message を正規表現で解析する代わりに、code で分岐できます。
検索ツールは代用品です。 search_protocols はインメモリのTFスコアを使用しているため、外部サービスなしでリポジトリを実行できます。本番環境では、これはPinecone、pgvector、または選択した検索バックエンドを接続する継ぎ目となります。ツールの入出力コントラクトは変わりません。
時間処理は簡略化されています。 プロバイダーの勤務時間は、明確にするためにUTCで解釈されます。実際のデプロイメントでは、各クリニックのタイムゾーン(スキーマに既に存在)を尊重します。これは見落としではなく意図的なものであることをレビュー担当者に伝えるために明記しています。
これがそうではないもの
臨床用ソフトウェアではありません。トリアージルールは玩具であり、プロトコルコーパスは手書きの文章です。実際の患者に触れるものには使用しないでください。
HIPAA準拠ではありません。データは偽物であり、ストレージはインメモリであり、監査ログもありません。本番環境では、それらすべてとそれ以上のものが必要になります。
完全なEMRや予約バックエンドではありません。ポイントはMCPサーバーの形状を示すことであり、クリニックシステムを出荷することではありません。
ライセンス
MIT。LICENSEを参照してください。
Available Tools
5 toolsbook_appointmentBook an appointmentB
Create an appointment for a patient with a provider. Requires an idempotency_key; repeated calls with the same key return the original appointment instead of double-booking.
Inputs: clinic_id (required), provider_id (required), patient_id (required), start_iso (required), +3 more.
escalate_to_oncallEscalate an appointment to the on-call providerC
Mark an existing appointment as urgent and reassign it to the clinic's on-call provider.
Inputs: clinic_id (required), appointment_id (required), reason (required).
find_available_slotFind available appointment slotsB
Return open appointment slots for a given specialty in a date range. Filters by clinic_id and skips conflicts with existing appointments.
Inputs: clinic_id (required), specialty (required), from_iso (required), to_iso (required), +2 more.
record_intakeRecord patient intakeB
Persist a structured intake note (symptoms, severity, onset) for a patient and assign a triage level (routine / elevated / urgent).
Inputs: clinic_id (required), patient_id (required), symptoms (required), severity (required), +2 more.
search_protocolsSearch clinic protocol documentsB
Keyword search over the clinic's protocol library. Returns ranked snippets the model can cite when answering.
Inputs: clinic_id (required), query (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: booking appointments, escalating to on-call, finding slots, recording intake, and searching protocols. No two tools overlap in functionality.
All tool names follow a consistent verb_noun pattern in snake_case, making it easy to predict the action and resource for each tool.
With exactly 5 tools, the server is well-scoped for a clinic domain, covering core patient-facing and administrative workflows without being overly heavy or thin.
The set covers appointment creation, urgent escalation, slot availability, intake recording, and protocol search. However, it lacks read/update/delete for appointments and any patient or provider management, which are notable gaps.
Maintenance
Related MCP Connectors
Hosted MCP server for the Healthie EHR & telehealth API: patients, appointments, charting, tasks.
Hosted MCP server for Cliniko — patients, appointments, availability, and invoices for AI agents.
MCP server for Modern Treasury — payment orders, transactions, counterparties and ledgers.
The Stytch MCP server is a reference implementation that demonstrates remote MCP server authentication and authorization using Stytch Connected Apps. It provides OAuth 2.1-compliant authorization (including PKCE), Dynamic Client Registration, and validates Stytch-issued access tokens to enable AI agents to securely interact with external services through permissioned access, supporting scopes like openid, email, profile, and manage:project_data.
Related MCP Servers
- FlicenseAqualityDmaintenanceA learning MCP server providing synthetic FHIR patient data with read tools and a gated write workflow (propose → human approve → commit) with structured audit logging.10-
- AlicenseNot gradedqualityDmaintenanceA reference MCP server demonstrating safe agent access to multi-tenant CRM data with tenant isolation enforced in the data layer, role-based permissions, and human confirmation on writes.MIT
- AlicenseAqualityDmaintenanceA Claude-compatible MCP server that exposes health-domain tools over 100% synthetic data, built with security and compliance in mind.4MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server reference implementation adding enterprise layers (identity, authorization, audit) around MCP, with sample shipment status and delayed shipment tools over a stateless transport.Apache 2.0