CMS Blue Button 2.0 FHIR API

naftiko: 1.0.0-alpha2
info:
  label: CMS Blue Button 2.0 FHIR API
  description: Read Medicare beneficiary Patient, Coverage, and ExplanationOfBenefit resources from the
    CMS Blue Button 2.0 FHIR R4 API after OAuth 2.0 consent. Self-contained capability covering the core
    Medicare claims read surface.
  tags:
  - CMS
  - Medicare
  - FHIR
  - BlueButton
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    BLUE_BUTTON_ACCESS_TOKEN: BLUE_BUTTON_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: blue-button-fhir
    baseUri: https://api.bluebutton.cms.gov/v2/fhir
    description: CMS Blue Button 2.0 FHIR R4 read surface.
    resources:
    - name: patient
      path: /Patient
      operations:
      - name: searchpatient
        method: GET
        description: Search Patient resources for the authorized beneficiary.
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
    - name: patient-id
      path: /Patient/{id}
      operations:
      - name: readpatient
        method: GET
        description: Read a Patient by ID.
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
        inputParameters:
        - { name: id, in: path, type: string, required: true, description: Patient ID }
    - name: coverage
      path: /Coverage
      operations:
      - name: searchcoverage
        method: GET
        description: Search Coverage resources.
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
    - name: explanation-of-benefit
      path: /ExplanationOfBenefit
      operations:
      - name: searchexplanationofbenefit
        method: GET
        description: Search ExplanationOfBenefit (Medicare claims) resources for the beneficiary.
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
        inputParameters:
        - { name: patient, in: query, type: string, description: Patient reference }
        - { name: type, in: query, type: string, description: 'Claim type filter (carrier, dme, hha, hospice, inpatient, outpatient, pde, snf)' }
        - { name: service-date, in: query, type: string, description: FHIR date range }
    authentication:
      type: bearer
      value: '{{env.BLUE_BUTTON_ACCESS_TOKEN}}'
      placement: header
  exposes:
  - type: mcp
    namespace: blue-button-fhir-mcp
    port: 9090
    transport: http
    description: MCP adapter for Blue Button 2.0 FHIR read surface.
    tools:
    - name: cms-blue-button-search-patient
      description: Search Medicare Patient resources for the authorized beneficiary.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: blue-button-fhir.searchpatient
      outputParameters:
      - { type: object, mapping: $. }
    - name: cms-blue-button-read-patient
      description: Read a Patient by ID.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: blue-button-fhir.readpatient
      outputParameters:
      - { type: object, mapping: $. }
    - name: cms-blue-button-search-coverage
      description: Search Medicare Coverage resources for the beneficiary.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: blue-button-fhir.searchcoverage
      outputParameters:
      - { type: object, mapping: $. }
    - name: cms-blue-button-search-explanation-of-benefit
      description: Search Medicare claim ExplanationOfBenefit resources for the beneficiary.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: blue-button-fhir.searchexplanationofbenefit
      outputParameters:
      - { type: object, mapping: $. }