naftiko: 1.0.0-alpha2
info:
  label: CMS BCDA Bulk FHIR Export
  description: Initiate and consume bulk FHIR exports from the CMS Beneficiary Claims Data API (BCDA) for
    Medicare Shared Savings Program ACOs. Asynchronous $export, job-status polling, and NDJSON download.
  tags:
  - CMS
  - Medicare
  - FHIR
  - BulkData
  - ACO
  - BCDA
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    BCDA_ACCESS_TOKEN: BCDA_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: bcda-bulk-fhir
    baseUri: https://api.bcda.cms.gov/api/v2
    description: CMS BCDA bulk FHIR export surface.
    resources:
    - name: patient-export
      path: /Patient/$export
      operations:
      - name: exportpatient
        method: GET
        description: Initiate a bulk export of Patient, Coverage, and ExplanationOfBenefit resources.
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
    - name: group-export
      path: /Group/{groupId}/$export
      operations:
      - name: exportgroup
        method: GET
        description: Initiate a Group-scoped bulk export (all, runout, new).
        inputParameters:
        - { name: groupId, in: path, type: string, required: true, description: 'all | runout | new' }
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
    - name: jobs-job
      path: /jobs/{jobId}
      operations:
      - name: getjob
        method: GET
        description: Get bulk export job status and output manifest.
        inputParameters:
        - { name: jobId, in: path, type: string, required: true }
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
      - name: canceljob
        method: DELETE
        description: Cancel a bulk export job.
        inputParameters:
        - { name: jobId, in: path, type: string, required: true }
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
    authentication:
      type: bearer
      value: '{{env.BCDA_ACCESS_TOKEN}}'
      placement: header
  exposes:
  - type: mcp
    namespace: bcda-mcp
    port: 9090
    transport: http
    description: MCP adapter for BCDA bulk FHIR export.
    tools:
    - name: cms-bcda-export-patient
      description: Initiate a BCDA bulk export of beneficiary FHIR resources.
      hints: { readOnly: false, destructive: false, idempotent: false }
      call: bcda-bulk-fhir.exportpatient
      outputParameters:
      - { type: object, mapping: $. }
    - name: cms-bcda-export-group
      description: Initiate a Group-scoped BCDA bulk export (all, runout, new).
      hints: { readOnly: false, destructive: false, idempotent: false }
      call: bcda-bulk-fhir.exportgroup
      outputParameters:
      - { type: object, mapping: $. }
    - name: cms-bcda-get-job
      description: Poll a BCDA bulk export job for status and output manifest.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: bcda-bulk-fhir.getjob
      outputParameters:
      - { type: object, mapping: $. }
    - name: cms-bcda-cancel-job
      description: Cancel a BCDA bulk export job.
      hints: { readOnly: false, destructive: true, idempotent: true }
      call: bcda-bulk-fhir.canceljob
      outputParameters:
      - { type: object, mapping: $. }