@pixsys/clientapi-mcp

stdio MCP server that exposes Pixsys Client API as agent tools. Authenticates with a tenant Gateway API key plus a user personal access token (PAT). tools/list is filtered to endpoints granted to that PAT.

Runtime lock

| Item | Choice | |------|--------| | Home | Sibling package in pixsys-clientapi (not Lambda, not Nexus.Api) | | Transport | stdio | | Runtime | TypeScript / Node 20+ (@modelcontextprotocol/sdk) | | Auth | PIXSYS_CLIENT_API_KEY (x-api-key) + PIXSYS_PAT (Authorization: Bearer) | | Grant discovery | GET /v1/access/granted-endpoints |

Env

| Variable | Required | Purpose | |----------|----------|---------| | PIXSYS_CLIENT_API_BASE_URL | yes | e.g. https://dev-clientapi.pixsystechnologies.net/v1 | | PIXSYS_CLIENT_API_KEY | yes | Tenant MCP Gateway key | | PIXSYS_PAT | yes | User PAT (pxpat_…) | | PIXSYS_MCP_SKIP_GRANT_FILTER | no | Set 1 only for local dogfood if GET access/granted-endpoints is down. Advertises the full catalog; authorizer still enforces grants on each call. |

Log only to stderr. stdout is reserved for MCP JSON-RPC.

Install / run

Published package (after npm publish)

npx -y @pixsys/clientapi-mcp

Publish path (maintainers):

1. Bump version in package.json and package-lock.json (npm rejects republishing an existing version)
2. Commit, then tag with the same semver: git tag mcp-v0.1.1 && git push origin mcp-v0.1.1
3. GitHub Action Publish MCP package runs npm publish (needs repo secret NPM_TOKEN for @pixsys)

Date-only tags like mcp-v2026.07.23 still publish whatever is in package.json — bump that first.

Manual: cd pixsys-clientapi-mcp && npm run prepublishOnly && npm publish

Local dogfood (before / without npm)

cd pixsys-clientapi-mcp
npm install
npm run build

Cursor / Claude config with an absolute path to the built entry:

{
  "mcpServers": {
    "pixsys": {
      "command": "node",
      "args": ["C:/path/to/pixsys-clientapi/pixsys-clientapi-mcp/dist/index.js"],
      "env": {
        "PIXSYS_CLIENT_API_BASE_URL": "https://dev-clientapi.pixsystechnologies.net/v1",
        "PIXSYS_CLIENT_API_KEY": "<tenant-mcp-key>",
        "PIXSYS_PAT": "<user-pat>"
      }
    }
  }
}

Or link globally: npm link then "command": "pixsys-mcp".

v1 tools

| MCP tool | ClientApiEndpointName | Route | |----------|----------------------|-------| | get_work_order_details | work-orders-details | GET work-orders/by-number/{workOrderNumber} (preferred) or GET work-orders/{workOrderId} | | list_regions | reference-regions | GET reference/regions | | list_branch_offices | reference-branch-offices | GET reference/branch-offices | | list_work_order_statuses | reference-work-order-statuses | GET reference/work-order-statuses | | list_internal_work_order_types | reference-internal-work-order-types | GET reference/internal-work-order-types | | list_retail_payment_types | reference-retail-payment-types | GET reference/retail-payment-types | | get_employee_report | employees-report | GET employees/report | | list_drivers_licenses_by_expiration | employees-drivers-licenses | GET employees/drivers-licenses | | get_performance_data | performance-data | GET performance-data/{reportType} | | list_work_order_changes | work-orders | GET work-orders | | list_timesheet_punches | timesheets-punches | GET timesheets/punches |

Only tools whose endpoint is in the PAT grant set appear in tools/list.

Agent config examples

Cursor (published)

{
  "mcpServers": {
    "pixsys": {
      "command": "npx",
      "args": ["-y", "@pixsys/clientapi-mcp"],
      "env": {
        "PIXSYS_CLIENT_API_BASE_URL": "https://clientapi.pixsystechnologies.net/v1",
        "PIXSYS_CLIENT_API_KEY": "<tenant-mcp-key>",
        "PIXSYS_PAT": "<user-pat>"
      }
    }
  }
}

Claude Desktop

Add under mcpServers in claude_desktop_config.json (same command / args / env shape as Cursor).

Develop

cd pixsys-clientapi-mcp
npm install
npm run typecheck
npm run build
npm run pack:check
npm run dev

Status (AB#11336)

• Stdio MCP server, dual-auth HTTP client, grant-filtered tools/list, tools/call, and v1 GET catalog are implemented.
• Publish path: npm publish + tag-triggered workflow; dogfood via local node dist/index.js until @pixsys npm scope credentials are configured.
• Per-tenant MCP Gateway usage-plan keys are a separate todo.