naftiko: 1.0.0-alpha2
info:
  label: Remote Payroll And Billing API — Payroll Billing
  description: 'Self-contained Naftiko capability for reading payroll calendars, billing documents, payslips, expenses, and incentives on Remote.'
  tags:
  - Remote
  - Payroll
  - Billing
  - FinOps
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    REMOTE_ACCESS_TOKEN: REMOTE_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: payroll-billing
    baseUri: https://gateway.remote.com
    description: Remote Payroll And Billing business capability.
    resources:
    - name: v1-payroll-calendars
      path: /v1/payroll/calendars
      operations:
      - name: listpayrollcalendar
        method: GET
        description: List Payroll Calendar
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v1-billing-documents
      path: /v1/billing_documents
      operations:
      - name: listbillingdocuments
        method: GET
        description: List Billing Documents
        inputParameters:
        - name: status
          in: query
          type: string
        - name: period
          in: query
          type: string
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v1-billing-document
      path: /v1/billing_documents/{billing_document_id}
      operations:
      - name: showbillingdocument
        method: GET
        description: Show A Billing Document
        inputParameters:
        - name: billing_document_id
          in: path
          type: string
          required: true
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v1-billing-document-breakdown
      path: /v1/billing_documents/{billing_document_id}/breakdown
      operations:
      - name: getbillingdocumentbreakdown
        method: GET
        description: Get Billing Document Breakdown
        inputParameters:
        - name: billing_document_id
          in: path
          type: string
          required: true
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v1-incentives
      path: /v1/incentives
      operations:
      - name: createincentive
        method: POST
        description: Create An Incentive
        inputParameters:
        - name: body
          in: body
          type: object
          required: true
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v1-payslips
      path: /v1/payslips
      operations:
      - name: listpayslips
        method: GET
        description: List Payslips
        inputParameters:
        - name: employment_id
          in: query
          type: string
        outputParameters:
        - name: result
          type: object
          value: $.
    authentication:
      type: bearer
      value: '{{env.REMOTE_ACCESS_TOKEN}}'
      placement: header
  exposes:
  - type: mcp
    namespace: payroll-billing-mcp
    port: 9090
    transport: http
    description: MCP adapter for Remote Payroll And Billing.
    tools:
    - name: remote-list-payroll-calendar
      description: List the payroll calendar.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: payroll-billing.listpayrollcalendar
    - name: remote-list-billing-documents
      description: List billing documents (invoices) for the company.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: payroll-billing.listbillingdocuments
      with:
        status: tools.status
        period: tools.period
    - name: remote-show-billing-document
      description: Show a billing document.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: payroll-billing.showbillingdocument
      with:
        billing_document_id: tools.billing_document_id
    - name: remote-get-billing-breakdown
      description: Get an itemized breakdown for a billing document (FinOps-grade).
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: payroll-billing.getbillingdocumentbreakdown
      with:
        billing_document_id: tools.billing_document_id
    - name: remote-create-incentive
      description: Create a bonus or recurring incentive for an employee.
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: payroll-billing.createincentive
      with:
        body: tools.body
    - name: remote-list-payslips
      description: List released payslips for an employee.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: payroll-billing.listpayslips
      with:
        employment_id: tools.employment_id