Pax8 API Patterns

Pax8 MCP Tools & API Patterns

Overview

Pax8 provides a first-party hosted MCP server at https://mcp.pax8.com/v1/mcp for AI tool integration. The MCP server exposes 15 tools covering companies, products, subscriptions, orders, invoices, usage, and quotes. This skill covers MCP server connection, the complete tool reference, pagination patterns, sorting, error handling, and best practices.

Connection & Authentication

MCP Server

Pax8 hosts an official MCP server. Authentication uses a single token:

1. Log into app.pax8.com
2. Navigate to Integrations > MCP (or visit app.pax8.com/integrations/mcp)
3. Generate an MCP token

MCP Server URL: https://mcp.pax8.com/v1/mcp

Required Header:

| Header | Value | Description | |--------|-------|-------------| | x-pax8-mcp-token | <token> | MCP token from Pax8 portal |

Environment Variables

export PAX8_MCP_TOKEN="your-mcp-token"

Claude Desktop Configuration

{
  "mcpServers": {
    "pax8": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.pax8.com/v1/mcp",
        "--header", "x-pax8-mcp-token:YOUR_TOKEN"
      ]
    }
  }
}

Complete MCP Tool Reference

Company Tools

| Tool | Description | Parameters | |------|-------------|------------| | pax8-list-companies | List and filter companies | page, size, sort (name/city/country/stateOrProvince/postalCode), order (asc/desc), company_name, status (active/inactive/deleted) | | pax8-get-company-by-uuid | Get a single company | uuid (required) |

Product Tools

| Tool | Description | Parameters | |------|-------------|------------| | pax8-list-products | Search the product catalog | productName, page, size, vendorName, search | | pax8-get-product-by-uuid | Get a single product | productId (required) | | pax8-get-product-pricing-by-uuid | Get product pricing | productId (required), companyId (optional) |

Subscription Tools

| Tool | Description | Parameters | |------|-------------|------------| | pax8-list-subscriptions | List and filter subscriptions | page, size, sort, status (Active/Cancelled/PendingManual/PendingAutomated/PendingCancel/WaitingForDetails/Trial/Converted/PendingActivation/Activated), billingTerm (monthly/annual/two-year/three-year/one-time/trial/activation), companyId, productId | | pax8-get-subscription-by-uuid | Get a single subscription | uuid (required) |

Order Tools

| Tool | Description | Parameters | |------|-------------|------------| | pax8-list-orders | List orders | page, size, companyId | | pax8-get-order-by-uuid | Get a single order | uuid (required) |

Invoice Tools

| Tool | Description | Parameters | |------|-------------|------------| | pax8-list-invoices | List and filter invoices | page, size, sort, status (unpaid/paid/void/carried/nothing due), invoiceDate, invoiceDateRangeStart, invoiceDateRangeEnd, dueDate, total, balance, carriedBalance, companyId | | pax8-get-invoice-by-uuid | Get a single invoice | uuid (required) |

Usage Tools

| Tool | Description | Parameters | |------|-------------|------------| | pax8-get-usage-summary | Get usage summary for a subscription | subscriptionId (required), page, size, sort, resourceGroup, companyId | | pax8-get-detailed-usage-summary | Get detailed usage data | usageSummaryId (required), usageDate, page, size |

Quote Tools

| Tool | Description | Parameters | |------|-------------|------------| | pax8-list-quotes | List and filter quotes | page, limit, sort, search, status (accepted/closed/declined/draft/expired/pending/sent) | | pax8-get-quote-by-uuid | Get a single quote | quoteId (required) |

Pagination

Page-Based Pagination

All list tools use zero-based page pagination with configurable page size:

Pagination Parameters:

| Parameter | Description | Default | Max | |-----------|-------------|---------|-----| | page | Page number (0-based) | 0 | - | | size | Results per page | 50 | 200 |

Pagination Response Metadata:

| Field | Description | |-------|-------------| | page.size | Number of results per page | | page.totalElements | Total number of records | | page.totalPages | Total number of pages | | page.number | Current page number (0-based) |

Iterating Through All Pages

To fetch all results, call the list tool repeatedly, incrementing page from 0 until page.number >= page.totalPages - 1:

1. Call the tool with page=0 and size=200
2. Check page.totalPages in the response
3. If more pages exist, call again with page=1, then page=2, etc.
4. Collect content arrays from each response

Sorting

Sort Parameters

Use the sort parameter on list tools. The order parameter specifies direction:

| Parameter | Values | Description | |-----------|--------|-------------| | sort | Varies by tool | Field to sort by | | order | asc, desc | Sort direction |

Company sort fields: name, city, country, stateOrProvince, postalCode

Example

To list companies sorted by name ascending:

• Call pax8-list-companies with sort=name, order=asc, size=200

Filtering

Filter Parameters by Tool

Each list tool supports specific filter parameters:

| Tool | Filter Parameters | |------|-------------------| | pax8-list-companies | company_name, status (active/inactive/deleted) | | pax8-list-products | productName, vendorName, search | | pax8-list-subscriptions | companyId, productId, status, billingTerm | | pax8-list-orders | companyId | | pax8-list-invoices | companyId, status, invoiceDate, invoiceDateRangeStart, invoiceDateRangeEnd, dueDate, total, balance, carriedBalance | | pax8-list-quotes | search, status |

Subscription Status Values

| Status | Description | |--------|-------------| | Active | Subscription is live and billing | | Cancelled | Subscription has been terminated | | PendingManual | Awaiting manual provisioning | | PendingAutomated | Automated provisioning in progress | | PendingCancel | Cancellation in progress | | WaitingForDetails | Additional information needed | | Trial | Free trial active | | Converted | Trial converted to paid | | PendingActivation | Activation pending | | Activated | Recently activated |

Invoice Status Values

| Status | Description | |--------|-------------| | unpaid | Invoice issued, payment not received | | paid | Invoice has been paid | | void | Invoice has been voided | | carried | Balance carried forward | | nothing due | No payment required |

Response Format

Single Resource:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme Corporation",
  "address": {
    "street": "123 Main St",
    "city": "Springfield",
    "stateOrProvince": "IL",
    "postalCode": "62704",
    "country": "US"
  },
  "phone": "555-123-4567",
  "website": "https://www.acme.com",
  "status": "Active",
  "billOnBehalfOfEnabled": false,
  "selfServiceAllowed": false,
  "orderApprovalRequired": false,
  "createdDate": "2024-01-15T10:30:00.000Z"
}

Paginated Collection:

{
  "page": {
    "size": 50,
    "totalElements": 237,
    "totalPages": 5,
    "number": 0
  },
  "content": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Acme Corporation"
    }
  ]
}

Rate Limiting

Rate Limit Details

| Metric | Limit | |--------|-------| | Successful calls per minute | 1000 |

When rate limited, the MCP tool will return an error. Wait before retrying. The MCP server handles authentication automatically, so rate limit responses are the main error to watch for.

Error Handling

Common Errors

| Error | Cause | Resolution | |-------|-------|------------| | Tool not found | MCP server