naftiko: 1.0.0-alpha2
info:
  label: TIAA Retirement Data Access
  description: Unified capability for fintech developers, financial aggregators, and plan administration platforms to access
    TIAA retirement account data. Combines the FDX API for customer-consented data sharing and the SIA API for plan administration,
    enabling a comprehensive view of participant retirement savings, income projections, and account activity.
  tags:
  - TIAA
  - Financial Data
  - FDX
  - Open Finance
  - Plan Administration
  - Retirement
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    TIAA_FDX_ACCESS_TOKEN: TIAA_FDX_ACCESS_TOKEN
    TIAA_SIA_ACCESS_TOKEN: TIAA_SIA_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: tiaa-fdx
    baseUri: https://api.tiaa.org/fdx/v6
    description: TIAA Financial Data Exchange API for account and transaction data
    authentication:
      type: bearer
      token: '{{TIAA_FDX_ACCESS_TOKEN}}'
    resources:
    - name: accounts
      path: /accounts
      description: Customer account management
      operations:
      - name: list-accounts
        method: GET
        description: List all accounts for the authenticated customer
        inputParameters:
        - name: offset
          in: query
          type: integer
          required: false
          description: Pagination offset
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of accounts to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: get-account
        method: GET
        description: Get details for a specific account
        inputParameters:
        - name: accountId
          in: path
          type: string
          required: true
          description: Unique account identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: transactions
      path: /accounts/{accountId}/transactions
      description: Account transaction history
      operations:
      - name: list-transactions
        method: GET
        description: List transactions for a specific account within an optional date range
        inputParameters:
        - name: accountId
          in: path
          type: string
          required: true
          description: Unique account identifier
        - name: startTime
          in: query
          type: string
          required: false
          description: Start of transaction date range (ISO 8601)
        - name: endTime
          in: query
          type: string
          required: false
          description: End of transaction date range (ISO 8601)
        - name: limit
          in: query
          type: integer
          required: false
          description: Maximum number of transactions to return
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: positions
      path: /accounts/{accountId}/positions
      description: Investment positions and holdings
      operations:
      - name: list-positions
        method: GET
        description: List investment positions for a specific account
        inputParameters:
        - name: accountId
          in: path
          type: string
          required: true
          description: Unique account identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: customer
      path: /customer
      description: Customer profile information
      operations:
      - name: get-customer
        method: GET
        description: Get the authenticated customer's profile
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: tax-forms
      path: /tax-forms
      description: Tax document access
      operations:
      - name: list-tax-forms
        method: GET
        description: List available tax forms for the customer
        inputParameters:
        - name: taxYear
          in: query
          type: integer
          required: false
          description: Filter by tax year
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: tiaa-sia
    baseUri: https://api.tiaa.org/sia/v1
    description: TIAA Secure Income Account API for plan administration
    authentication:
      type: bearer
      token: '{{TIAA_SIA_ACCESS_TOKEN}}'
    resources:
    - name: plans
      path: /plans/{planId}
      description: Plan configuration and eligibility
      operations:
      - name: get-plan
        method: GET
        description: Get SIA configuration for a plan
        inputParameters:
        - name: planId
          in: path
          type: string
          required: true
          description: Unique plan identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: participants
      path: /plans/{planId}/participants
      description: Participant enrollment and management
      operations:
      - name: list-participants
        method: GET
        description: List plan participants enrolled in SIA
        inputParameters:
        - name: planId
          in: path
          type: string
          required: true
          description: Unique plan identifier
        - name: page
          in: query
          type: integer
          required: false
          description: Page number
        - name: pageSize
          in: query
          type: integer
          required: false
          description: Page size
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: enroll-participant
        method: POST
        description: Enroll a participant in the SIA product
        inputParameters:
        - name: planId
          in: path
          type: string
          required: true
          description: Unique plan identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            firstName: '{{tools.firstName}}'
            lastName: '{{tools.lastName}}'
            dateOfBirth: '{{tools.dateOfBirth}}'
            ssn: '{{tools.ssn}}'
            email: '{{tools.email}}'
            allocationPercentage: '{{tools.allocationPercentage}}'
      - name: get-participant
        method: GET
        description: Get SIA account details for a participant
        inputParameters:
        - name: planId
          in: path
          type: string
          required: true
          description: Unique plan identifier
        - name: participantId
          in: path
          type: string
          required: true
          description: Unique participant identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: contributions
      path: /plans/{planId}/contributions
      description: Contribution submission
      operations:
      - name: submit-contribution
        method: POST
        description: Submit a contribution to a participant's SIA account
        inputParameters:
        - name: planId
          in: path
          type: string
          required: true
          description: Unique plan identifier
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        body:
          type: json
          data:
            participantId: '{{tools.participantId}}'
            amount: '{{tools.amount}}'
            contributionType: '{{tools.contributionType}}'
            payrollDate: '{{tools.payrollDate}}'
    - name: projections
      path: /plans/{planId}/participants/{participantId}/projections
      description: Income projections
      operations:
      - name: get-income-projection
        method: GET
        description: Get projected lifetime income for a participant
        inputParameters:
        - name: planId
          in: path
          type: string
          required: true
          description: Unique plan identifier
        - name: participantId
          in: path
          type: string
          required: true
          description: Unique participant identifier
        - name: retirementAge
          in: query
          type: integer
          required: false
          description: Target retirement age
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: tiaa-retirement-api
    description: Unified REST API for accessing TIAA retirement account data, plan administration, and income projections.
    resources:
    - path: /v1/accounts
      name: accounts
      description: Customer retirement accounts
      operations:
      - method: GET
        name: list-accounts
        description: List all TIAA retirement accounts
        call: tiaa-fdx.list-accounts
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/accounts/{accountId}
      name: account-detail
      description: Individual account details
      operations:
      - method: GET
        name: get-account
        description: Get specific retirement account details
        call: tiaa-fdx.get-account
        with:
          accountId: rest.accountId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/accounts/{accountId}/transactions
      name: transactions
      description: Account transaction history
      operations:
      - method: GET
        name: list-transactions
        description: List transactions for a retirement account
        call: tiaa-fdx.list-transactions
        with:
          accountId: rest.accountId
          startTime: rest.startTime
          endTime: rest.endTime
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/accounts/{accountId}/positions
      name: investment-positions
      description: Investment positions and holdings
      operations:
      - method: GET
        name: list-positions
        description: List investment positions in a retirement account
        call: tiaa-fdx.list-positions
        with:
          accountId: rest.accountId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/customer
      name: customer
      description: Customer profile
      operations:
      - method: GET
        name: get-customer
        description: Get customer profile information
        call: tiaa-fdx.get-customer
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/tax-forms
      name: tax-forms
      description: Tax documents
      operations:
      - method: GET
        name: list-tax-forms
        description: List available tax forms
        call: tiaa-fdx.list-tax-forms
        with:
          taxYear: rest.taxYear
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/plans/{planId}
      name: plan
      description: Plan configuration
      operations:
      - method: GET
        name: get-plan
        description: Get SIA plan configuration
        call: tiaa-sia.get-plan
        with:
          planId: rest.planId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/plans/{planId}/participants
      name: participants
      description: Plan participants
      operations:
      - method: GET
        name: list-participants
        description: List plan participants in SIA
        call: tiaa-sia.list-participants
        with:
          planId: rest.planId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/plans/{planId}/participants/{participantId}/projections
      name: income-projections
      description: Lifetime income projections
      operations:
      - method: GET
        name: get-income-projection
        description: Get income projection for a participant
        call: tiaa-sia.get-income-projection
        with:
          planId: rest.planId
          participantId: rest.participantId
          retirementAge: rest.retirementAge
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: tiaa-retirement-mcp
    transport: http
    description: MCP server for AI-assisted TIAA retirement account data access, plan administration, and income planning.
    tools:
    - name: list-accounts
      description: List all TIAA retirement and brokerage accounts for the authenticated customer
      hints:
        readOnly: true
        openWorld: false
      call: tiaa-fdx.list-accounts
      outputParameters:
      - type: object
        mapping: $.
    - name: get-account
      description: Get details for a specific TIAA account including current balance and status
      hints:
        readOnly: true
        openWorld: false
      call: tiaa-fdx.get-account
      with:
        accountId: tools.accountId
      outputParameters:
      - type: object
        mapping: $.
    - name: list-transactions
      description: List transaction history for a TIAA account within a date range
      hints:
        readOnly: true
        openWorld: false
      call: tiaa-fdx.list-transactions
      with:
        accountId: tools.accountId
        startTime: tools.startTime
        endTime: tools.endTime
      outputParameters:
      - type: object
        mapping: $.
    - name: list-investment-positions
      description: List current investment positions and holdings in a TIAA account
      hints:
        readOnly: true
        openWorld: false
      call: tiaa-fdx.list-positions
      with:
        accountId: tools.accountId
      outputParameters:
      - type: object
        mapping: $.
    - name: get-customer-profile
      description: Get the authenticated customer's TIAA profile and contact information
      hints:
        readOnly: true
        openWorld: false
      call: tiaa-fdx.get-customer
      outputParameters:
      - type: object
        mapping: $.
    - name: list-tax-forms
      description: List available TIAA tax forms (1099-R, 5498) for a given tax year
      hints:
        readOnly: true
        openWorld: false
      call: tiaa-fdx.list-tax-forms
      with:
        taxYear: tools.taxYear
      outputParameters:
      - type: object
        mapping: $.
    - name: get-plan-details
      description: Get SIA plan configuration, eligibility rules, and allocation limits
      hints:
        readOnly: true
        openWorld: false
      call: tiaa-sia.get-plan
      with:
        planId: tools.planId
      outputParameters:
      - type: object
        mapping: $.
    - name: list-plan-participants
      description: List participants enrolled in the Secure Income Account for a plan
      hints:
        readOnly: true
        openWorld: false
      call: tiaa-sia.list-participants
      with:
        planId: tools.planId
      outputParameters:
      - type: object
        mapping: $.
    - name: get-participant-details
      description: Get SIA account details and balance for a specific plan participant
      hints:
        readOnly: true
        openWorld: false
      call: tiaa-sia.get-participant
      with:
        planId: tools.planId
        participantId: tools.participantId
      outputParameters:
      - type: object
        mapping: $.
    - name: get-income-projection
      description: Get projected lifetime monthly and annual income for a participant at a given retirement age
      hints:
        readOnly: true
        openWorld: false
      call: tiaa-sia.get-income-projection
      with:
        planId: tools.planId
        participantId: tools.participantId
        retirementAge: tools.retirementAge
      outputParameters:
      - type: object
        mapping: $.