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.

Anti-triggers

• Sherweb's request model — the other CSP marketplace here uses OAuth client-credentials plus a subscription-key header, underscored tool names, and 1-based pagination, against Pax8's single token, hyphenated tool names, and 0-based pagination. Use sherweb-api-patterns. Copying a paging pattern between the two silently changes which records you get.
• Pax8 tools missing from the client entirely, or a 401 before any call succeeds — that is a gateway-connection problem; use shared-skills-wyre-gateway-troubleshooting.
• How to change something — nothing in this surface writes. All 15 tools are list or fetch; orders, quantity changes, and cancellations happen in the Pax8 portal. That is a scope fact, not a missing permission, and no other skill in this plugin works around it.

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:

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

Product Tools

Subscription Tools

Order Tools

Invoice Tools

Usage Tools

Quote Tools

Pagination

Page-Based Pagination

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

Pagination Parameters:

Pagination Response Metadata:

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:

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:

Subscription Status Values

Invoice Status Values

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

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

Troubleshooting MCP Connection

1. Verify token - Ensure the MCP token is valid and not expired
2. Check URL - MCP server URL must be https://mcp.pax8.com/v1/mcp
3. Test with a simple call - Try pax8-list-companies with size=1 to verify connectivity
4. Regenerate token - If authentication fails, generate a new token from the Pax8 portal

Best Practices

1. Use maximum page size - Set size=200 to minimize total tool calls when fetching all records
2. Filter server-side - Use tool parameters to narrow results rather than fetching everything
3. Sort consistently - Use sort=name, order=asc for predictable pagination results
4. Use UUIDs - All Pax8 resource IDs are UUIDs; validate format before passing to tools
5. Use company-scoped queries - Always pass companyId when checking a specific client's data
6. Paginate large results - The full Pax8 catalog has thousands of products; always paginate
7. Cache results when appropriate - Company and product data changes infrequently
8. Use the search parameter - pax8-list-products supports a search parameter for flexible text matching

Related Skills

• Pax8 Companies - Company management
• Pax8 Products - Product catalog
• Pax8 Subscriptions - Subscription lifecycle
• Pax8 Orders - Order management
• Pax8 Invoices - Invoice and billing