Register your application at bluebutton.cms.gov developer portal and obtain a client_id and client_secret for the sandbox environment.
Implement the OAuth 2.0 authorization code flow: redirect the Medicare beneficiary to the CMS authorization endpoint; after consent, exchange the code for tokens at the token endpoint.
Query the FHIR R4 endpoints with the access token; the Blue Button 2.0 API exposes ExplanationOfBenefit (EOB), Patient, and Coverage resources.
Retrieve all EOBs for the beneficiary: GET [base]/ExplanationOfBenefit?patient=[id]&_count=50; paginate through results using Bundle next links; EOBs represent Medicare Part A, B, and D claims.
Parse EOB.item[].productOrService for procedure codes (CPT/HCPCS), EOB.diagnosis[] for ICD-10 codes, EOB.item[].adjudication[] for payment amounts and adjustment reasons.
Access Coverage resources via GET [base]/Coverage?patient=[id] to determine Part A, B, and D enrollment status and effective periods.
Known gotchas
Blue Button 2.0 data is claims-based, not clinical; it reflects what was billed and paid, not necessarily the complete clinical picture; EOB data may lag weeks behind service dates.
The sandbox uses synthetic beneficiary data; sandbox credentials do not work against production and production access requires CMS approval including a data use agreement.
ExplanationOfBenefit resources in Blue Button 2.0 use CMS-specific profiles and extensions; the resource structure differs from a generic FHIR R4 EOB and requires CMS-specific documentation to interpret.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp