How the MCP server fits the platform

The HockeyStick MCP server lets a client's or consultant's AI app (Claude, Claude Code, Codex) use HockeyStick as a set of tools. It adds no new data access of its own. Everything it does goes through the public /v1 API as the signed-in person.

The request path

1. The AI app calls a tool on the MCP server at /mcp, carrying the user's Auth0 access token for the MCP resource.
2. The MCP server verifies the token (issuer, audience, admitted app, expiry), resolves the HockeyStick user, and checks the tool's scope.
3. It exchanges the user's token for a short-lived token for the /v1 API, bound to the same user (native On-Behalf-Of exchange).
4. The /v1 API applies the same role, organisation and row-level security rules as the portal and Command Centre, then does the work.
5. Both the MCP server and the API write audit rows, joined by the request ID.

What that means in practice

• Every call runs as the person. A client user only reaches their own organisation. Staff (admin and consultant) reach the clients their role already reaches, and must name a client with engagement_id on each call.
• Same rules as the UI. Activate entitlement, client-only revenue writes, staff-only go-live and Riley publishing, locks and version checks all live in the API, not in the MCP.
• A fixed route list. Delegated tokens can only reach the /v1 routes behind the current tools. Anything else, such as finance settings, Zoom commands or asset approvals, is refused with 403 DELEGATED_ROUTE_FORBIDDEN.
• One tool catalogue. The Slack agent shares the same tool definitions and descriptions. Slack has its own confirm-card flow; another section covers it.

Confirmation is the app's job

The server sends every app the same instructions: reads are safe; writes must show the user the exact values and wait for explicit confirmation; never invent transcripts, sources, speaker facts or strategy consent; never retry a refused or uncertain write. For Claude and Codex this confirmation happens in the app. The API cannot prove a human confirmed a non-Slack write, so treat the user's own app settings (Codex per-tool approval, Claude tool toggles) as part of the control.

New tools reach users automatically

Apps read the tool list and instructions at the start of each session. A new tool needs no plugin update, but a connection opened before a release keeps the old list until the user reconnects and starts a new chat.

Related

• Environments, URLs and client IDs
• Tool reference: reads
• Audit trail and usage