myatriumhealth-mcp

myatriumhealth-mcp

MyAtriumHealth 向け MCP サーバーです。my.atriumhealth.org にある Atrium Health の Epic MyChart患者ポータルから、検査結果、服薬、アレルギー、予防接種、健康上の問題、目標、受診情報を読み取ります。

このプロジェクトは AI によって開発・保守されています。ご自身の判断でご利用ください。 個人の健康情報を読み取りますが、読み取るのはサインイン中のユーザー自身のアカウントからのみです。

認証方法は 2 つあります

モード	利用条件	保持される認証情報
ブラウザーブリッジ（デフォルト）	認証情報が設定されていない	なし
ブリッジレス	MAH_USERNAME + MAH_PASSWORD が設定されている	ポータルのパスワード（ディスク上）

ブリッジレスではサーバー側でログインします。ブラウザーも拡張機能も不要なため、ホスティングが可能になります。認証確認は人間が介在する方式です。ポータルが認証を求めると、mah_sign_in がアカウントで利用可能な方法を報告し、ポータルからユーザー本人にコードが送信されます。その後、mah_verify_code はユーザーが提供したコードのみを送信します。ここで二要素認証を回避することはありません。

セッションが期限切れになっても、MCP に再接続したり、何かを再起動したりする必要はありません。次のツール呼び出しで、利用可能な方法とマスキングされた送信先を示す、対処可能なエラーが返されます。方法を選ぶと、ポータルからユーザー本人に SMS またはメールが送信され、mah_verify_code によってセッションがそのまま再開されます。保留中の認証要求は記憶されるため、それ以降のツール呼び出しでは、毎回パスワードを再送信する代わりに、その要求について報告します。

認証情報の読み込み元。 環境変数に実際の MAH_USERNAME / MAH_PASSWORD がある場合は、常にそれが優先されます。ない場合、サーバーは次の順序で、最初に見つかった .env を読み込みます。MAH_DOTENV、次に ~/.myatriumhealth-mcp/.env、最後に ./.env です。

2 番目の場所があるのは、MCP クライアントがそのときの作業ディレクトリからサーバーを起動するため、チェックアウト内にある .env が認識されないことがあるからです。また、その失敗は気づきにくいものです。認証情報がない場合、サーバーはブラウザーブリッジにフォールバックし、ポートをバインドして、サインイン済みのタブを待機します。ブリッジレスで実行するつもりなのにブリッジが起動した場合、これが原因です。現在は起動時のログ行でその旨が示されます。

セッションの保持方法。 認証確認を一度行うと、Cookie jar が保存され（0600、アカウントに紐付け）、再利用されます。そのため、再起動後も再度サインインせずに既存のセッションが再開されます。セッションが期限切れになるまでは、ブラウザーも追加のコードも必要ありません。

セッションの有効期間は、推測ではなく実測に基づいています。 MyChart が設定する 10 個の Cookie はすべてセッション Cookie であり、expires も max-age も含まれていません。そのため、有効期間はサーバー側でのみ管理され、Cookie jar からは読み取れません。219 分間アイドル状態だった Cookie jar は、認証済みではなくなっていました。次の呼び出しでは新たなサインインに進み、すぐにコードの入力を求められました。

この結果から分かることと、分からないことがあります。これはアイドル状態のセッションの上限を示すもので、アクティブなセッションについては何も示していません。この測定では、アイドルタイムアウトと絶対タイムアウトを区別できません。また、この種のポータルでは一般に非アクティブ状態になると期限切れになるため、継続的に使用しているセッションは 3.6 時間を超えても問題なく維持される一方、放置されたセッションは維持されません。再認証の計画は、経過時間ではなく使用の中断時間に基づいて立ててください。

セッション中に Cookie jar を書き戻す理由。 各レスポンスの Set-Cookie を取り込み、値に実際の変更があった場合は Cookie jar を再保存します（transport-server.ts では各リクエストの後に行い、値が更新されていない場合は何も書き込みません）。これは単なる記録ではありません。ポータルがセッションの使用中にチケットを更新した場合、更新後のチケットを再起動後も使えるようにするには、ディスクに書き込む必要があります。スケール・トゥ・ゼロのホストでは、ツール呼び出しの間に子プロセスが終了します。この書き戻しがあるからこそ、次の呼び出しでもセッションが維持され、サインイン時の状態で凍結されたコピーに戻らずに済みます。

ここで説明した仕組みでも、変わらないことが 2 つあります。セッションが期限切れになった場合でも、必要なのは再接続ではなくコード 1 つです。また、期限切れの検出だけでは何も送信されません。ポータルへの送信を要求するのは mah_sign_in のみです。

測定によって判明した、想定とは異なる動作： ポータルが返す RememberDeviceId は、ポータルが受け付けるデバイス追跡 ID ではありません。これを送信しても認証をスキップできず、無害でもありません。チャレンジが壊れ、SecondaryValidation ページに templateContext がないため、アンチフォージェリトークンを読み取れず、SendCode は 500 を返します。アカウントでは RememberMeSettings.EnrollDeviceTracking: False と報告されており、この動作と一致しています。そのため、トークンは保存されますが、意図的に送信されることはありません。

ブリッジモードの真の利点は、認証情報を一切保持しないことです。ブリッジなしの構成がどうしても必要な場合を除き、こちらを優先してください。

仕組み

MyChart の Cookie はすべて HttpOnly で、ログインには MFA が必要なため、セッションをブラウザーからコピーして Node から再利用することはできません。そのため、fetchproxy ブリッジと ContextMint Bridge ブラウザー拡張機能を介して、ユーザー自身のサインイン済みタブ経由でリクエストを中継し、認証済みセッションを再利用します。サーバーがセッション Cookie を読み取ったり保存したりすることはありません。

ポータルの Web アプリは、2 世代の JSON API と通信します。新しい POST api/<area>/<Action> と、従来のフォームエンコード形式の POST <Area>/<Controller>/<Action> です。どちらも、実際に取得したリクエスト形式とともに docs/MYATRIUMHEALTH-API.md に記載されています。

インストール

{
  "mcpServers": {
    "myatriumhealth": {
      "command": "npx",
      "args": ["-y", "@chrischall/myatriumhealth-mcp"]
    }
  }
}

ブリッジモードでは、リリースページからインストールする ContextMint Bridge が必要です。Chrome では、chrome の zip を解凍し、chrome://extensions → デベロッパー モード → パッケージ化されていない拡張機能を読み込む、の順に操作してください。現時点では Chrome を使用してください。Safari 版は、まだ一般公開されていない ContextMint アプリに同梱される予定です。

ContextMint Bridge は、fetchproxy ブラウザー拡張機能が新しい名前になったもので、同じメンテナーが開発しています。fetchproxy の README にも掲載されています。ソースコードは公開されているため、nullnet-app/contextmint-bridge から自分でビルドするか、リリースと同じ場所に公開されている .sha256 ファイルを使ってリリース zip を検証してください（shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256）。

ブラウザーで my.atriumhealth.org にサインインし、mah_healthcheck を呼び出してください。最初の呼び出しでペアコードが表示されます。ContextMint Bridge のポップアップで一度だけ承認してください。

Env	Default	Purpose
MAH_USERNAME	—	MyAtriumHealth のユーザー名です。MAH_PASSWORD と併せて設定すると、ブリッジ不要モードが有効になります。
MAH_PASSWORD	—	ポータルのパスワードです。両方の設定が必要です。一方だけを設定した場合は、ブリッジモードにフォールバックし、警告が表示されます。
MAH_DEVICE_FILE	~/.myatriumhealth-mcp/device.json	セッション状態（0600）です。デバイストークンに加えて有効な Cookie jarも保持するため、認証情報として取り扱ってください。
MAH_WS_PORT	37149	fetchproxy のコンセントレーターのポートです（ブリッジモードのみ）。フリート全体でこのポートを共有します。ホストする場合に限り、変更してください。
MAH_READ_ONLY	false	true の場合、mah_reply_message による送信を拒否します（プレビューは引き続き利用できます）。どちらの場合もツールは一覧に表示されます。
MCP_CONFIRM_MODE	ask-user	確認プロンプトを表示できないクライアント（claude.ai、Claude Desktop）で、返信をどのように処理するかを指定します。ask-user：2 段階で処理します。最初の呼び出しでは何も送信せず、プレビューとトークンを返します。モデルは、トークンを使って再度呼び出す前に、チャットであなたの承認を得る必要があります。auto：同じく 2 段階で処理しますが、モデルはプレビューを確認した後、自身の判断でトークンを使用できます。refuse：そのようなクライアントでは返信を拒否します。プロンプトを表示できるクライアント（Claude Code）では、MCP_CONFIRM_ELICITATION=off に設定されていない限り、常に実際のプロンプトが表示されます。認識されない値は refuse として扱われます。
MCP_CONFIRM_ELICITATION	on	off の場合、確認プロンプトは表示されず、すべてのクライアントで MCP_CONFIRM_MODE の方法が使われます。プロンプトをサポートするとされているのに表示されないクライアント（返信がハングする — opencode 2.0.x）では、この値を設定してください。その他の値では on のままとなり、stderr に警告が表示されます。
MCP_CONFIRM_TTL_SECONDS	600	トークンの有効期間です。
MCP_CONFIRM_SECRET	random per process	署名キーです。サーバーを再起動してもトークンを有効に保つ必要がある場合に限り、設定してください。

ツール

2 つを除き、すべて読み取り専用です。mah_set_active_patient は、このコネクターが読み取る患者を切り替えるだけで、カルテには何も書き込みません。mah_reply_message は医療提供者が見るメッセージを送信し、取り消すことはできません。返信を参照してください。

すべての読み取りツールは { patient, data } を返すため、どのカルテの情報かは推測ではなく明示されています。

ツール	返される内容
mah_list_allergies	アレルギーと反応、重症度
mah_list_health_issues	問題リスト
mah_list_immunizations	組織別の予防接種と日付
mah_list_medications	用法・用量の指示（sig）と処方者を含む薬剤
mah_list_test_results	検査と画像診断：名称、異常フラグ、日付、医療提供者のコメント
mah_list_upcoming_visits	今後の予約と進行中の予約
mah_list_past_visits	組織ごとにまとめた過去の受診
mah_list_goals	患者の目標
mah_get_health_summary	健康サマリーのヘッダーとアクションプラン
mah_list_message_folders	未読数を含むメッセージセンターのフォルダー
mah_list_messages	指定フォルダー内のメッセージセンターの会話。各会話には返信先となる conversationId が含まれます
mah_reply_message	アクティブな患者として会話に返信します。最初に確認を求めます。クライアントが対応している場合はプロンプトを表示し、対応していない場合はプレビューと confirmToken を表示します（取り消し不可）
mah_list_insurance	登録済みの保険適用範囲
mah_list_care_team	内部および外部のケアチームの医療提供者
mah_list_billing_accounts	請求アカウントと残高（HTML から解析）
mah_healthcheck	接続の状態。中継時はブリッジの状態、サーバー側でサインインする場合は認証情報とセッションの状態
mah_auth_status	セッションを再開できるかどうか、およびデバイストークンが保存されているかどうか
mah_sign_in	サーバー側でサインインします。コードが必要な場合は確認手段を報告します（認証情報が必要）
mah_send_verification_code	ポータルに依頼してアカウント所有者にコードを送信します（認証情報が必要）
mah_verify_code	ユーザーが受け取ったコードを送信します（認証情報が必要）
mah_list_patients	このログインで開ける患者。アカウント所有者と代理アクセス対象者
mah_get_patient_context	リーダーが対応している患者。ポータルで確認済みの情報
mah_set_active_patient	すべてのリーダーの参照先を、これらの患者のいずれかに設定します。再起動後も維持されます。ブラウザーブリッジ経由では自分のタブも切り替わります。また、そこで患者を変更した場合、読み取り時に元へ戻すのではなく、読み取りを拒否します

すべての読み取りツールでは view を指定できます。compact（既定値）または full です。生のエンベロープは大きく、検査結果は約 33 KB、薬剤は約 30 KB あるため、閲覧には compact が適しています。full では MyAtriumHealth のペイロードがそのまま返されます。

compact では画像とアバターの URL が常に取り除かれます。これは情報を削る処理であり、未知のフィールドが失われることはありません。さらに 10 個のリーダーでは、実際のペイロードを取得してそれを基に投影を導出しているため、各レコードを臨床的に意味のあるフィールドに絞り込みます。対象は mah_list_allergies、mah_list_health_issues、mah_list_immunizations、mah_list_medications、mah_list_care_team、mah_list_goals、mah_list_test_results、mah_list_past_visits、mah_list_insurance、mah_list_messages です。

それ以外のすべてのリーダーでは、URL の削除のみが行われます。フィールドリストは、実際に設定された箇所にのみ適用され、それ以外では適用されません。上記のリストは PROJECTED_ENDPOINTS から生成され、テストによって project() の呼び出し箇所と照合されるため、コードとの不整合がひそかに生じることはありません。ポータルのデータ構造が変わった場合、投影は標準エラー出力に警告を出し、空のリストではなく { projectionFailed: true, endpoint, topLevelKeys, note } を返します。含まれるのはキー名のみで、生の健康記録は含まれません。ポータルのペイロードを確認するには、view: 'full' を指定してください。

セッションは期限切れになり、しかも通知されません

MyChart は、期限切れのセッションに対して HTTP 200 でログインページを本文として返し、401 は返しません。その後、JSON エンドポイントは {} を返します。ツールは空の結果を報告せず、解決方法を添えて「サインインしていません」というエラーを返します。セッションの有効期間は短いため、利用するたびに再度サインインすることを想定してください。

MCP を使わない場合

skills/myatriumhealth-fpx は fpx CLI を使ってシェルから同じ操作を行います。サーバーを実行する必要はありません。references/endpoints.md には、ここにあるすべてのエンドポイントについて、実際に検証済みの jq レシピが記載されています。

メッセージ

mah_list_messages は、空の本文で呼び出せない唯一のエンドポイントです。5 つのキーを含むリクエストが必要で、その PageNonce には /app/* ページの CSP nonce を指定します。また、externalLoadParams には ローカル以外の組織のみを含める必要があります。ローカルの組織を渡すと HTTP 500 が返されます。クライアントは、conversations/GetOrganizations とその明示的な isLocal フラグを使ってこれを組み立てます。

api/item-feed/FetchItemFeed には、まだ取得できていないパラメーターが必要です。

返信

mah_reply_message には、mah_list_messages の conversationId、プレーンテキストの body、および任意の attachments を指定します。現在アクティブな患者として返信します。

• 送信前に確認を求めます。 確認プロンプトを表示できるクライアント（Claude Code など）では、MCP_CONFIRM_ELICITATION=off でない限り、スレッド、宛先、本文、添付ファイルを確認するプロンプトが表示されます。それ以外の環境では、最初の呼び出しでは何も送信せず、プレビューと confirmToken を返します。同じ引数とそのトークンで再度呼び出すと送信されます。MCP_CONFIRM_MODE（上記）は、モデルが使用前にチャットであなたの承認を得る必要があるか（デフォルトの ask-user）、モデル自身で使用してよいか（auto）、それとも使用を拒否するか（refuse）を決定します。送信は取り消せず、プロバイダーに記録されます。
• 送信には、その送信に対応するプレビューが必要です。 トークンは、プレビューに表示された患者、スレッド、宛先、本文、添付ファイルに紐付けられます（@chrischall/mcp-utils による、フリート共通の仕組みです）。それ以外はすべて拒否されます。返信またはスレッドが異なる場合（新しいプレビューと新しいトークンを返す DRAFT_CHANGED）、10 分経過した場合（TOKEN_EXPIRED）、すでに使用済みのトークンの場合（TOKEN_REUSED）、またはこの返信用に発行されていないトークンの場合（TOKEN_INVALID）です。プレビューごとに送信を 1 回だけ承認し、送信が承認されるとトークンは消費されます。そのため、何も送信される前に失敗した場合でも、再試行には新しいプレビューが必要です。したがって、モデルが読んだメッセージによって、ユーザーが一度も確認していない送信を 1 回の呼び出しで実行させることはできません。
• MAH_READ_ONLY=true の場合、すべての送信が拒否されます。 ホスト型コネクターは、環境変数を持たない子プロセスのツール一覧を公開します。そのため、書き込みが許可された場合にのみ登録されるツールは、全員に対して見えなくなってしまいます。このため、ツールの登録自体は維持されます。
• 制限はポータルに基づきます。 文字数は 500 文字、添付ファイルは 3 件まで、文書または画像は 1 件あたり 10 MB、動画は 1 件あたり 64 MB です。対応形式は BMP/DOC/DOCX/JPEG/JPG/PDF/PNG/TIF/TIFF および一般的な動画形式です。
• 添付ファイルにはブリッジなしモードが必要です。 fetchproxy はリクエスト本文をテキストとして中継するため、バイナリーアップロードは保持されません。そのため、ブラウザーブリッジ経由では、添付ファイル付きの返信はアップロード開始前に拒否されます。
• 送信は再試行されません。 患者を確認してから送信するまでの間にセッションが再認証された場合、何も送信されません。新たにサインインするとアカウント所有者のセッションになるため、返信がその人として送信されてしまいます。ポータルからの送信結果を読み取れない場合、返信が送信された可能性があると結果に表示されます。再試行する前にスレッドを確認してください。
• 成功すると、スレッドを読み返して取得した、新しいメッセージの wmgId と deliveryInstantISO が返されます（送信処理自体が返すのはスレッド ID のみです）。

開発

npm install
npm test          # typecheck + vitest
npm run build

ライセンス

MIT