Documentation

Introduction

The PHS Pallets MCP Gateway exposes live PHS production data — 100+ plastic pallet SKUs, real quotes with freight estimates, order history and shipment tracking — to any client that speaks the Model Context Protocol (ChatGPT, Claude, and any MCP-compatible agent).

Quick start

ChatGPT

Settings → Apps & Connectors → Create. Set Name to PHS Pallets, Server URL to the endpoint below, and Authentication to No Auth.

https://mcp.phsinc.com/api/mcp

Claude

Settings → Connectors → Add custom connector, then paste the same URL. Claude discovers the gateway's OAuth server automatically and connects in one click — no client ID or secret required.

cURL

curl -X POST https://mcp.phsinc.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

curl -X POST https://mcp.phsinc.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"popular_pallets","arguments":{"max_results":3}}}'

Authentication

The gateway has two independent layers. Neither ever handles passwords in chat.

OAuth 2.1 endpoints

A spec-compliant, auto-approving authorization server for MCP clients: dynamic client registration (RFC 7591), PKCE S256 (RFC 7636), authorization-server metadata (RFC 8414) and protected-resource metadata (RFC 9728). Codes and tokens are stateless HMAC-signed values.

curl -X POST https://mcp.phsinc.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<code from redirect>" \
  -d "code_verifier=<PKCE verifier>" \
  -d "redirect_uri=<your callback>" \
  -d "client_id=<from /api/oauth/register>"

In-chat customer sign-in

The three-step passwordless flow assistants should follow for returning customers:

1. Call request_login_code with the customer's account email. A single-use 6-digit code (10-minute expiry) is emailed.
2. Ask the customer for the code from their inbox — never ask for a password.
3. Call login_with_code to exchange it for a bearer token, then pass that token to my_orders, track_order, my_quotes and reorder.

Tools reference

Every tool publishes a typed outputSchema and MCP ToolAnnotations. Results arrive as structuredContent in the JSON-RPC response. Writes are strictly additive — nothing can be modified or deleted through this API.

{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {"name": "search_pallets",
            "arguments": {"query": "rackable", "max_results": 3}}}

{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
 "params": {"name": "get_pallet_details",
            "arguments": {"product_id": "phs_15735"}}}

{"jsonrpc": "2.0", "id": 3, "method": "tools/call",
 "params": {"name": "popular_pallets", "arguments": {"max_results": 5}}}

{"jsonrpc": "2.0", "id": 4, "method": "tools/call",
 "params": {"name": "request_quote",
            "arguments": {"contact_name": "Jane Doe",
                          "contact_email": "jane@acme.com",
                          "destination_zip": "75201",
                          "items": [{"product_id": "phs_15735", "quantity": 200}],
                          "company": "Acme Logistics"}}}

{"jsonrpc": "2.0", "id": 5, "method": "tools/call",
 "params": {"name": "request_login_code",
            "arguments": {"email": "customer@example.com"}}}

{"jsonrpc": "2.0", "id": 6, "method": "tools/call",
 "params": {"name": "login_with_code",
            "arguments": {"email": "customer@example.com", "code": "847291"}}}

{"jsonrpc": "2.0", "id": 7, "method": "tools/call",
 "params": {"name": "my_orders", "arguments": {"token": "<bearer token>"}}}

{"jsonrpc": "2.0", "id": 8, "method": "tools/call",
 "params": {"name": "track_order",
            "arguments": {"order_id": "<order id>", "token": "<bearer token>"}}}

{"jsonrpc": "2.0", "id": 9, "method": "tools/call",
 "params": {"name": "my_quotes", "arguments": {"token": "<bearer token>"}}}

{"jsonrpc": "2.0", "id": 10, "method": "tools/call",
 "params": {"name": "reorder", "arguments": {"token": "<bearer token>"}}}

Protocol notes

• Stateless: no session or initialize handshake is required before tools/list or tools/call. Every request is self-contained and horizontally scalable.
• Headers: send Content-Type: application/json and Accept: application/json, text/event-stream.
• No redirects: /api/mcp and /api/mcp/ are equivalent — the gateway rewrites the path internally so clients never see a 307.
• Structured output: tool results include both human-readable content and machine-readable structuredContent validated against each tool's outputSchema.
• Annotations: read-only tools carry readOnlyHint=true, idempotentHint=true; write tools carry readOnlyHint=false, destructiveHint=false. All tools are openWorldHint=false — the gateway only ever talks to the PHS first-party API.
• Payments: never happen in chat. Quotes are paid via Stripe checkout through the emailed link or the PHS Pallets mobile app.

Error handling

Tool failures return a normal JSON-RPC result with isError: true and a plain-text explanation — upstream API problems are surfaced as PHS API error <status>: <detail>. Invalid or expired sign-in codes, bad tokens and PKCE failures all produce descriptive errors rather than 5xx responses.

{"jsonrpc": "2.0", "id": 5,
 "result": {"isError": true,
            "content": [{"type": "text",
                         "text": "PHS API error 401: Invalid or expired code"}]}}

Resources