Healthcare MCP + A2A Server (Mock)

医療保険請求ドメイン向けのModel Context Protocol (MCP)およびAgent-to-Agent (A2A) 通信を実証するサンプルプロジェクトです。

mcp_server/ — 8つのヘルスケアツールを公開するFastMCPサーバー
a2a/ — JSON-RPC 2.0上で調整を行う4つの専門エージェントを備えたカスタムA2Aプロトコル
run_a2a.py — すべてのエージェントをまとめて実行するスタンドアロンHTTPサーバー

すべてのデータは合成されたものであり、実際のPHI（個人健康情報）や外部への呼び出しは含まれません。

公式A2A SDK: a2a-sdk (v1.0.1+) がA2Aプロトコルの公式Pythonライブラリとなりました。本プロジェクトには、学習目的で構築されたカスタム実装が含まれています。

プロジェクト構成

healthcare-mcp/
├── mcp_server/                  # MCP server
│   ├── __init__.py
│   └── server.py                # FastMCP with 8 healthcare tools
├── a2a/                         # A2A protocol implementation
│   ├── __init__.py
│   ├── message.py               # JSON-RPC 2.0 message types
│   ├── a2a_protocol.py          # Protocol engine, registry, routing
│   └── agents.py                # 4 healthcare domain agents
├── run_a2a.py                   # Standalone A2A HTTP server
├── test_a2a_communication.py    # A2A protocol tests (40 tests)
├── diagrams/
│   ├── mcp.mmd                  # MCP Gateway architecture
│   └── a2a.mmd                  # A2A messaging pattern
├── requirements.txt
└── pytest.ini

セットアップ

前提条件: Python 3.10以上

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

MCPサーバーの実行

MCPサーバーは、MCP互換クライアントに対してヘルスケアツールを公開します。

stdio (デフォルト — MCPクライアント用)

python mcp_server/server.py

Streamable HTTP

export MCP_TRANSPORT=streamable-http
export FASTMCP_HOST=127.0.0.1
export FASTMCP_PORT=8000
python mcp_server/server.py

エンドポイント: http://127.0.0.1:8000/mcp

SSE

export MCP_TRANSPORT=sse
python mcp_server/server.py

MCP環境変数

変数	デフォルト	説明
`MCP_TRANSPORT`	`stdio`	トランスポート: `stdio`, `streamable-http`, または `sse`
`FASTMCP_HOST`	`127.0.0.1`	HTTPトランスポートのバインドホスト
`FASTMCP_PORT`	`8000`	HTTPトランスポートのバインドポート
`FASTMCP_STREAMABLE_HTTP_PATH`	`/mcp`	streamable-httpエンドポイントのURLパス
`MCP_MOUNT_PATH`	(なし)	オプションのマウントパスプレフィックス

A2Aサーバーの実行

A2Aサーバーは4つのヘルスケアエージェントすべてを起動し、HTTP経由で公開します。これは、MCPツール関数をプロセス内で呼び出すローカルMCPクライアントを使用するため、個別のMCPサーバーは不要です。

python run_a2a.py

サーバーはデフォルトで http://127.0.0.1:8001 で起動します。

A2A環境変数

変数	デフォルト	説明
`A2A_HOST`	`127.0.0.1`	バインドホスト
`A2A_PORT`	`8001`	バインドポート

A2Aエンドポイント

メソッド	パス	説明
`GET`	`/.well-known/agent.json`	エージェントカード — 検出用の機能とメタデータ
`GET`	`/agents`	登録済みエージェントの一覧表示
`POST`	`/`	A2A JSON-RPC 2.0メッセージの受信

例: エージェントの検出

curl http://127.0.0.1:8001/.well-known/agent.json | python -m json.tool

例: A2Aメッセージの送信

curl -s -X POST http://127.0.0.1:8001/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "check_member_eligibility",
    "params": {"member_id": "M-1001"},
    "id": "req-001",
    "sender": "external-client",
    "recipient": "claims-agent",
    "type": "request"
  }' | python -m json.tool

MCPツール

請求 (Claims)

ツール	パラメータ	説明
`list_member_claims`	`member_id`, `status?`	請求を一覧表示（`paid`/`pending`/`denied`でフィルタリング可能）
`get_claim_detail`	`claim_id`	メンバー、医療機関、査定額を含む請求詳細
`submit_claim_inquiry`	`claim_id`, `inquiry_type`, `note`	問い合わせチケットの送信

給付 (Benefits)

ツール	パラメータ	説明
`get_member_benefits`	`member_id`	メンバーのプランにおける免責金額および自己負担上限額の残高
`estimate_member_responsibility`	`member_id`, `procedure_code`, `billed_amount`, `network?`	費用負担の見積もり

医療機関と承認 (Providers & Authorizations)

ツール	パラメータ	説明
`search_providers`	`specialty`, `zip_code?`, `network?`	専門分野による医療機関検索
`create_prior_authorization`	`member_id`, `provider_id`, `procedure_codes`, `service_date`, `diagnosis_codes?`	事前承認リクエストの送信
`get_prior_authorization_status`	`auth_id`	事前承認の現在のステータスを取得

A2Aエージェントシステム

エージェント

エージェント	ID	役割
`MemberAssistAgent`	`member-assist-agent`	患者コーディネーター — 資格確認、医療機関検索
`ClaimsAgent`	`claims-agent`	請求処理担当 — 資格確認、請求履歴、費用見積もり
`ProviderAdvocateAgent`	`provider-advocate-agent`	ネットワーク管理者 — 医療機関検索
`BenefitsAgent`	`benefits-agent`	給付スペシャリスト — 費用計算

通信フロー

MemberAssistAgent
    ├─ A2A → ClaimsAgent: "check_member_eligibility"
    │         ├─ MCP: list_member_claims, get_member_benefits
    │         └─ MCP: get_claim_detail
    │
    └─ A2A → ProviderAdvocateAgent: "search_network_providers"
              └─ MCP: search_providers

ClaimsAgent
    └─ A2A → BenefitsAgent: "calculate_member_responsibility"
              └─ MCP: estimate_member_responsibility

コード内でのエージェントの使用

import asyncio
from a2a import A2AProtocol, MemberAssistAgent, ClaimsAgent, ProviderAdvocateAgent, BenefitsAgent

async def main():
    protocol = A2AProtocol()

    member_assist     = MemberAssistAgent(protocol, mcp_client)
    claims            = ClaimsAgent(protocol, mcp_client)
    provider_advocate = ProviderAdvocateAgent(protocol, mcp_client)
    benefits          = BenefitsAgent(protocol, mcp_client)

    for agent in [member_assist, claims, provider_advocate, benefits]:
        await agent.register()

    protocol.register_handler("check_member_eligibility",        claims.handle_check_member_eligibility)
    protocol.register_handler("search_network_providers",        provider_advocate.handle_search_network_providers)
    protocol.register_handler("calculate_member_responsibility", benefits.handle_calculate_member_responsibility)

    eligibility = await member_assist.check_eligibility("M-1001")
    providers   = await member_assist.find_providers("primary care", "55401")

asyncio.run(main())

テスト

pytest -v                          # all 40 tests
pytest test_a2a_communication.py   # A2A protocol tests only

テストドキュメントについては TEST_GUIDE.md を、コマンドのフィルタリングについては QUICKSTART.md を参照してください。

モックデータリファレンス

メンバー

ID	名前	プラン
`M-1001`	Jordan Lee	`P-100` Optum Choice PPO
`M-1002`	Casey Patel	`P-200` Optum Select HMO

プラン

ID	名前	免責金額	残高	自己負担上限	残高	ネットワーク内共同保険
`P-100`	Optum Choice PPO	$1,500	$420	$5,000	$2,100	20%
`P-200`	Optum Select HMO	$500	$120	$3,000	$980	10%

医療機関

ID	名前	専門分野	ネットワーク	郵便番号
`PR-2001`	Northside Primary Care	プライマリケア	ネットワーク内	55401
`PR-2002`	Lakeview Ortho Clinic	整形外科	ネットワーク内	55111
`PR-2003`	Metro Imaging Center	放射線科	ネットワーク外	55415

請求

ID	メンバー	医療機関	ステータス	請求額
`C-10001`	M-1001	PR-2001	支払い済み	$250.00
`C-10002`	M-1001	PR-2003	保留中	$980.00
`C-10003`	M-1002	PR-2002	拒否（事前承認が必要）	$1,350.00

事前承認

ID	メンバー	ステータス
`PA-9001`	M-1002	承認済み

アーキテクチャ図

ファイル	説明
diagrams/mcp.mmd	ドメインサーバーへルーティングするMCPゲートウェイ
diagrams/a2a.mmd	エージェント間のA2Aメッセージング

Mermaid Live Editor またはMermaid互換ビューアでレンダリングしてください。

MCPインスペクター

MCP Inspector は、MCPツールを対話的に呼び出すためのブラウザベースのツールです。

npm install
npm start

注意事項

すべてのデータはメモリ上にあり、再起動時にリセットされます。
estimate_member_responsibility はモックの乗数（ネットワーク内75%、ネットワーク外60%）を使用しています。支払いを保証するものではありません。
PHI、外部API呼び出し、永続ストレージは含まれていません。
公式のA2A Python SDKは a2a-sdk>=1.0.1 です。本プロジェクトの a2a/ モジュールは、同じプロトコルパターンを教育目的でカスタム実装したものです。

Health Claims MCP Server