UnitedHealthcare Patient Data Access

naftiko: "1.0.0-alpha1"

info:
  label: "UnitedHealthcare Patient Data Access"
  description: >-
    Workflow capability for accessing UnitedHealthcare member health data through
    FHIR R4 Interoperability APIs mandated by CMS. Enables patient portals, health
    apps, and care coordination tools to retrieve claims history, coverage details,
    and provider directory information. Supports CMS-9115-F Patient Access rule
    compliance and Da Vinci PDex Provider Directory implementation.
  tags:
    - UnitedHealthcare
    - FHIR
    - Patient Access
    - CMS Interoperability
    - Provider Directory
    - Health Data Exchange
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      UHC_FHIR_TOKEN: UHC_FHIR_TOKEN

capability:
  consumes:
    - import: uhc-fhir
      location: ./shared/interoperability-api.yaml

  exposes:
    - type: rest
      port: 8081
      namespace: patient-data-access-api
      description: "Unified REST API for UnitedHealthcare FHIR patient data access."
      resources:
        - path: /v1/patient/{id}
          name: patient
          description: "Patient demographics."
          operations:
            - method: GET
              name: get-patient
              description: "Get FHIR Patient resource."
              call: "uhc-fhir.get-patient"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/claims-history
          name: claims-history
          description: "FHIR ExplanationOfBenefit claims history."
          operations:
            - method: GET
              name: list-eobs
              description: "List EOB claims history."
              call: "uhc-fhir.list-eobs"
              with:
                patient: "rest.patient"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/coverage
          name: coverage
          description: "Coverage details."
          operations:
            - method: GET
              name: list-coverage
              description: "List coverage."
              call: "uhc-fhir.list-coverage"
              with:
                patient: "rest.patient"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: /v1/providers
          name: providers
          description: "Provider directory search."
          operations:
            - method: GET
              name: list-practitioners
              description: "Search providers."
              call: "uhc-fhir.list-practitioners"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9091
      namespace: patient-data-access-mcp
      transport: http
      description: "MCP server for AI-assisted UnitedHealthcare FHIR patient data access."
      tools:
        - name: get-member-demographics
          description: "Retrieve UnitedHealthcare member demographics from the FHIR Patient resource."
          hints:
            readOnly: true
            openWorld: false
          call: "uhc-fhir.get-patient"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-claims-history
          description: "Retrieve a member's claims history as FHIR ExplanationOfBenefit resources including service dates, amounts billed, and payment status."
          hints:
            readOnly: true
            openWorld: false
          call: "uhc-fhir.list-eobs"
          with:
            patient: "tools.patientId"
            type: "tools.claimType"
            _lastUpdated: "tools.lastUpdated"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-insurance-coverage
          description: "Get a member's UnitedHealthcare insurance coverage details including plan name, effective dates, and benefit periods."
          hints:
            readOnly: true
            openWorld: false
          call: "uhc-fhir.list-coverage"
          with:
            patient: "tools.patientId"
            status: "tools.status"
          outputParameters:
            - type: object
              mapping: "$."
        - name: find-in-network-providers
          description: "Search UnitedHealthcare's FHIR Provider Directory for in-network physicians and organizations by name, specialty, or state."
          hints:
            readOnly: true
            openWorld: true
          call: "uhc-fhir.list-practitioners"
          with:
            name: "tools.providerName"
            specialty: "tools.specialty"
            "address-state": "tools.state"
          outputParameters:
            - type: object
              mapping: "$."