Healthcare MCP + A2A 서버 (모의)

건강 보험 청구 도메인을 위한 Model Context Protocol (MCP) 및 에이전트 간(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	이름	공제액	잔액	OOP 최대치	잔액	네트워크 내 공동 부담금
`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	1차 진료	네트워크 내	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