naftiko: 1.0.0-alpha2
info:
  label: CMS BFD FHIR Server
  description: Read Medicare Patient, Coverage, and ExplanationOfBenefit resources from the upstream
    Beneficiary FHIR Data (BFD) server. Peering-only — mutual TLS with CMS-issued client certificates.
  tags:
  - CMS
  - Medicare
  - FHIR
  - BFD
  - Internal
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    BFD_CLIENT_CERT: BFD_CLIENT_CERT
    BFD_CLIENT_KEY: BFD_CLIENT_KEY
capability:
  consumes:
  - type: http
    namespace: bfd-fhir
    baseUri: https://prod.bfd.cms.gov/v2/fhir
    description: CMS BFD FHIR R4 read surface (mutual TLS).
    resources:
    - name: patient
      path: /Patient
      operations:
      - name: searchpatient
        method: GET
        description: Search Patient resources by identifier.
        inputParameters:
        - { name: identifier, in: query, type: string }
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
    - name: explanation-of-benefit
      path: /ExplanationOfBenefit
      operations:
      - name: searchexplanationofbenefit
        method: GET
        description: Search ExplanationOfBenefit resources by patient.
        inputParameters:
        - { name: patient, in: query, type: string, required: true }
        - { name: type, in: query, type: string }
        - { name: excludeSAMHSA, in: query, type: boolean }
        outputRawFormat: json
        outputParameters:
        - { name: result, type: object, value: $. }
    authentication:
      type: mtls
      cert: '{{env.BFD_CLIENT_CERT}}'
      key: '{{env.BFD_CLIENT_KEY}}'
  exposes:
  - type: mcp
    namespace: bfd-mcp
    port: 9090
    transport: http
    description: MCP adapter for BFD FHIR read surface.
    tools:
    - name: cms-bfd-search-patient
      description: Search BFD Patient resources by identifier.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: bfd-fhir.searchpatient
      outputParameters: [ { type: object, mapping: $. } ]
    - name: cms-bfd-search-explanation-of-benefit
      description: Search BFD ExplanationOfBenefit resources.
      hints: { readOnly: true, destructive: false, idempotent: true }
      call: bfd-fhir.searchexplanationofbenefit
      outputParameters: [ { type: object, mapping: $. } ]