What this is

From zero to a real call: discover the live services, make a read, make an authenticated write, and connect an AI agent over MCP. No step is left implicit.

Base URL

• Production: https://people-analytics-toolbox-<deploy>.vercel.app — reads are public (Deployment Protection is off on Production so consumers can hit reads without a bypass token).
• Preview: Vercel-auth-protected and ephemeral — not for integration.
• Local: http://localhost:3000 (npm run dev).

1. Discover what's live

curl https://<base>/api/registry      # every spoke, status, and contract version
curl https://<base>/api/health        # aggregate health roll-up across spokes

Each spoke also has GET /api/spokes/<slug>/health → { spoke, status, contractVersion, schemaReachable, latencyMs, checkedAt }.

2. Make a read (no key needed)

# example: JobFrame canonical classification
curl "https://<base>/api/spokes/job-family-agent/classify?title=Staff%20Data%20Scientist"

Read endpoints (GET) are open on Production by design.

3. Get a service key, then make a write ← (don't leave the reader guessing)

Write endpoints (POST) require a service key. The key is the production env var TOOLBOX_SERVICE_KEY (issued by a toolbox admin; for local dev an unset key logs a warning and lets requests through). Send it as either header:

curl -X POST "https://<base>/api/spokes/<slug>/<verb>" \
  -H "x-toolbox-service-key: $TOOLBOX_SERVICE_KEY" \   # preferred for new consumers
  -H "Content-Type: application/json" \
  -d '{ ... }'
# Authorization: Bearer $TOOLBOX_SERVICE_KEY  is also accepted (backwards-compatible)

The gate is requireServiceKey(request) in src/lib/auth/service-key.ts, called as the first line of every POST handler. A 401 means the key/header is the place to look.

4. Connect an AI agent over MCP

Spokes are exposed as MCP tools named <slug>.<method> (e.g. job-family-agent.classify). Auth uses a per-consumer scoped key — TOOLBOX_MCP_KEY_<CONSUMER> (e.g. TOOLBOX_MCP_KEY_PERFORMIX) — which maps to a scope set in src/lib/mcp/auth.ts. Send it as Authorization: Bearer <key> or x-toolbox-service-key: <key>.

npm run mcp:smoke      # PAT-24 MCP client smoke (needs dev server + a TOOLBOX_MCP_KEY_* or TOOLBOX_SERVICE_KEY)

Honest scope

This reaches a real call against live services. Tenant context, entitlement checks, and min-N governance (the Tenant Platform "board") apply to production data flows — see Trust & Security. Reads being open on Production is a deliberate choice for consumer apps, not an oversight.

See also

Concepts · APIs · MCP Tools