naftiko: 1.0.0-alpha2
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-06'
binds:
- namespace: env
  keys:
    UHC_FHIR_TOKEN: UHC_FHIR_TOKEN
capability:
  consumes:
  - type: http
    namespace: uhc-fhir
    baseUri: https://api.uhc.com/fhir/R4
    description: UnitedHealthcare FHIR R4 Interoperability API.
    authentication:
      type: bearer
      token: '{{UHC_FHIR_TOKEN}}'
    resources:
    - name: patient
      path: /Patient/{id}
      description: FHIR Patient resource.
      operations:
      - name: get-patient
        method: GET
        description: Retrieve FHIR Patient demographics for a member.
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
          description: Patient resource ID.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: explanation-of-benefit
      path: /ExplanationOfBenefit
      description: FHIR ExplanationOfBenefit resources.
      operations:
      - name: list-eobs
        method: GET
        description: List ExplanationOfBenefit (claims) for a patient.
        inputParameters:
        - name: patient
          in: query
          type: string
          required: true
          description: Patient resource ID.
        - name: _lastUpdated
          in: query
          type: string
          required: false
          description: Filter by last updated date.
        - name: type
          in: query
          type: string
          required: false
          description: Claim type filter.
        - name: _count
          in: query
          type: string
          required: false
          description: Max results.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: coverage
      path: /Coverage
      description: FHIR Coverage resources.
      operations:
      - name: list-coverage
        method: GET
        description: List Coverage resources for a patient.
        inputParameters:
        - name: patient
          in: query
          type: string
          required: true
          description: Patient resource ID.
        - name: status
          in: query
          type: string
          required: false
          description: Coverage status filter.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: practitioner
      path: /Practitioner
      description: FHIR Practitioner resources.
      operations:
      - name: list-practitioners
        method: GET
        description: Search provider directory for practitioners.
        inputParameters:
        - name: name
          in: query
          type: string
          required: false
          description: Provider name search.
        - name: specialty
          in: query
          type: string
          required: false
          description: Specialty taxonomy code.
        - name: address-state
          in: query
          type: string
          required: false
          description: State filter.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  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: $.