> ## Documentation Index > Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt > Use this file to discover all available pages before exploring further. # MCP server > Operating the Soundcheck Model Context Protocol endpoint on api-events. Soundcheck MCP is hosted **in-process on api-events**. The `@soundcheck/mcp` package (`mcp-ts/`) is the catalog + Streamable HTTP handler library. api-events executes tools via `DirectBackend` → existing `*Operation` functions. CheckAI calls the same catalog out of process via `HttpToolBackend` against `API_BASE_URL`. End-user setup for Claude Code and Cursor lives in [Soundcheck MCP server](https://docs.soundchecklive.io/integrations/mcp-server.md). This page covers what an operator needs. ## Architecture ```text theme={null} [Claude / Cursor / CheckAI] │ OAuth → Clerk (Authorization Code + PKCE) │ Authorization: Bearer ▼ [api-events Encore] /mcp /public/mcp /.well-known/oauth-protected-resource │ validates JWT in-handler (routes are auth: false so 401 can send PRM) │ DirectBackend.exec(op) → *Operation ▼ [PostgreSQL] ``` The MCP transport is **stateless**. It does not own a database; sessions exist only inside the MCP transport. ## Source layout | Path | Purpose | | - | - | | `mcp-ts/src/exports.ts` | Public SDK surface (`handleMcpRequest`, backends, catalog). | | `mcp-ts/src/handler.ts` | Streamable HTTP + `SERVER_*` / instructions. | | `mcp-ts/src/backend.ts` | `SoundcheckBackend.exec(op, input?, body?)`. | | `mcp-ts/src/httpBackend.ts` | CheckAI adapter over the generated OpenAPI client. | | `api-events/src/systems/mcp/` | Encore routes, `DirectBackend`, Clerk + rate-limit wiring. | | `mcp-ts/src/tools/catalog.ts` | Declarative tool definitions (reads, writes, composites). Clone-org tools live in `catalog-gap.ts` (`export_workspace`, `preview_import_file`, `import_file`). | Opt-in 1:1 tools are annotated with sibling `mcpTool()` next to `openapiRoute()`. Emit JSON Schema ToolDefs with `cd api-events && npm run mcp:emit`. ## Local development ```bash theme={null} npm run dev:infra cd api-events && npm run db:migrate && npm run db:seed:demo-full cd api-events && npm run dev:emulator ``` Then point [MCP Inspector](https://github.com/modelcontextprotocol/inspector) at `http://localhost:4000/mcp`. CheckAI uses `API_BASE_URL=http://localhost:4000` (no Soundcheck `MCP_URL`). ## OAuth 2.0 Protected Resource api-events exposes [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728.html) PRM at: ```text theme={null} GET /.well-known/oauth-protected-resource GET /.well-known/oauth-protected-resource/mcp ``` and [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414.html) authorization-server metadata (live Clerk AS document, including CIMD when Clerk advertises it) at: ```text theme={null} GET /.well-known/oauth-authorization-server GET /.well-known/oauth-authorization-server/mcp ``` OpenAI Apps domain verification (plain-text token, no auth): ```text theme={null} GET /.well-known/openai-apps-challenge ``` Override the token with `OPENAI_APPS_CHALLENGE` (production defaults to the pinned verification value when unset). Spec-compliant MCP clients read PRM on 401 and run the OAuth flow against Clerk. Older clients that fetch AS metadata from the resource origin get the same Clerk authorize, token, and DCR endpoints. Hosted API and MCP hosts fill `authorization_servers` from the resource URL when `OAUTH_ISSUER` is unset (`HOSTED_MCP_OAUTH_ISSUERS` in `api-events/src/config/config.ts`). ## Public MCP hostname (same Cloud Run) MCP is in-process on api-events. The public connect hostname is a **third cert + host rule** on the existing api-events ALB (`mcp_domain_name` on `infra-gcp/modules/events`). CheckAI does not use these hosts; it talks to api-events via `API_BASE_URL`. There is no leftover dedicated MCP Cloud Run in any GCP env state. | Env | Host | `MCP_RESOURCE_URL` | Squarespace CNAME | | | - | - | - | - | - | | prod | `mcp.soundchecklive.io` | `https://mcp.soundchecklive.io/mcp` | `api-events.soundchecklive.io` | | | qa | `qa-mcp.soundchecklive.io` | `https://qa-mcp.soundchecklive.io/mcp` | `qa-api-events.soundchecklive.io` | | | dev | `dev-mcp.soundchecklive.io` | `https://dev-mcp.soundchecklive.io/mcp` | `dev-api-events.soundchecklive.io` | | The MCP host is path-restricted to `/mcp`, `/public/mcp`, and `/.well-known/*`. Member connect stays `https:///mcp` (not the origin root). Do not advertise these URLs until Squarespace CNAMEs exist and the managed cert is **ACTIVE** (ENG-613). Apply order (Cloud Agent or human only) is in `infra-gcp/README.md`. ```hcl theme={null} mcp_domain_name = "dev-mcp.soundchecklive.io" # extra_cloud_run_env.MCP_RESOURCE_URL = "https://dev-mcp.soundchecklive.io/mcp" ``` ## Server tracing (telemetry.dev) `api-events` emits one OpenTelemetry SERVER span per JSON-RPC request on `/mcp` and `/public/mcp` (`api-events/src/observability/mcpServerSpans.ts`), exported over OTLP/HTTP to telemetry.dev so client and server spans pair up. The MCP SDK is v1, so the vendor's `@telemetry-dev/mcp` wrapper (v2 only) is not used. * **Parent context:** W3C `traceparent` / `tracestate` from `params._meta` first, then the HTTP `traceparent` header. **Clients must inject `_meta`** — a header alone is not enough in practice, because proxies in front of the server (the harness `/api/mcp-proxy` among them) forward only an allow-list of headers and drop `traceparent`. Header-only runs show up as orphan client spans. CheckAI does this in `checkai/agent/lib/mcpClientTracing.ts`. Neither present means a new root span. * **Attributes:** `mcp.method.name`, `mcp.tool.name` / `gen_ai.tool.name` (on `tools/call`), `gen_ai.operation.name`, `mcp.tier` (`member` / `public`), `mcp.confirmation_required` (the call returned a confirmation prompt), `jsonrpc.request.id`, `mcp.protocol.version`, `http.response.status_code`, `error.type`. * **Never captured:** tool arguments or results, tool error messages, `confirmation_token`, bearer tokens, org ids. * **Client-supplied values are validated before export:** methods must be known MCP methods, tool names must be in the tier's catalog (otherwise the span is just `tools/call`), request ids are kept only when integer or UUID, and protocol versions only when `YYYY-MM-DD`. At most 16 messages per request are traced. * **Batches:** the invocation hook has no request id, so when one batch calls the same tool twice those spans carry no `mcp.confirmation_required` / tool `error.type` rather than a guessed one. * **Notifications** produce no span. `mcp.confirmation_required` and tool `error.type` come from the mutating-tool invocation hook, so read-only tools always report `false`. * The provider is private (never registered globally), so Sentry's trace sampling and the PostHog trace exporter are unaffected. | Variable | Purpose | Default | | - | - | - | | `TELEMETRY_DEV_API_KEY` | Ingest key (Secret Manager `{env}-TelemetryDevAPIKey`). Unset or `PLACEHOLDER` = spans off | — | | `MCP_TELEMETRY_DEV_ENABLED` | Kill switch; `false` turns spans off with the key still mounted | `true` | | `TELEMETRY_DEV_ENVIRONMENT` | `deployment.environment.name` resource attribute | `development` | | `TELEMETRY_DEV_SERVICE_NAME` | `service.name` resource attribute | `soundcheck-mcp-server` | | `TELEMETRY_DEV_TRACES_URL` | OTLP traces endpoint (point at a local collector to smoke-test) | `https://ingest.telemetry.dev/v1/traces` | Only dev enables it (`enable_telemetry_dev_api_key = true` in `infra-gcp/environments/dev`). After `terraform apply`, add the key and roll a revision: ```bash theme={null} printf '%s' "$TELEMETRY_DEV_API_KEY" | gcloud secrets versions add dev-TelemetryDevAPIKey \ --project dev-soundcheck-live --data-file=- ``` qa/prod stay off until the flag is set there after a redaction review. ### Tool-call errors agents can act on `tools/call` is checked before the MCP SDK sees it (`mcp-ts/src/tools/preflight.ts`), because the SDK answers an unknown tool or a schema miss with bare prose and nothing is recorded. Both now come back as the usual JSON envelope with `isError` and `structuredContent`: * **Unknown tool** → `{"code":"unknown_tool","tool":"list_org_call_lists","did_you_mean":["get_staffing_plan"]}`. Nothing ran, so no audit row is written. * **Bad arguments** → `{"code":"invalid_arguments","tool":"…","missing_fields":[…],"issues":[{"field":"…","message":"…"}]}`, recorded as an `error` invocation. `create_event_invitations` is event-scoped (no `organization_id`) and takes `invitations:[{email|user_id|phone_number, …}]`, or the `emails:["sam@example.com"]` shorthand. With valid arguments it returns `confirmation_required` while `MCP_CONFIRMATION_SECRET` is set, never a silent failure. ## MCP Apps (SEP-1865) The member tier can serve [MCP Apps](https://modelcontextprotocol.io/extensions/apps): interactive HTML views that hosts implementing the extension render in a sandboxed iframe next to a tool result. Code lives in `mcp-ts/src/apps/`: `viewRuntime.ts` (shared bridge, theme, widget styles, and confirm step), `confirmCard.ts` (ENG-855 Confirm Card), `planReview.ts` (ENG-856 Plan Review), `staffingDraft.ts` (ENG-857 Staffing Draft), `gigs.ts` (Gigs, with OpenAI entrypoints), `toolViews.ts` (which catalog tools link to which view and which results carry view data), `helloWorld.ts` (ENG-854 spike: tool `show_hello_world_app` renders `ui://soundcheck/hello-world.html`), and `register.ts`. * **Product views are on in every environment; the hello-world spike is dev-only.** `handleMcpRequest` always registers the Confirm Card, Plan Review, Staffing Draft, and Gigs resources, the app-only `reject_confirmation` tool, the card link on gated member tools, and the view links in `toolViews.ts`. The public tier never gets MCP Apps. The ENG-854 hello-world tool and resource are registered only with `handleMcpRequest({ mcpAppsSpike: true })`: api-events sets that from `mcpConfig().mcpAppsSpikeEnabled = !isDeployedEnvironment()` → `runtime.mcpAppsSpike`, so qa/prod `tools/list` never lists `show_hello_world_app`. There is no feature flag. * **No SDK upgrade.** The wire contract is plain `_meta`, which SDK v1.30 already passes through on tools, resources, content items, and `CallToolResult`: the tool has `_meta.ui.resourceUri` (plus the legacy `_meta["ui/resourceUri"]` key), and the resource is `text/html;profile=mcp-app` with `_meta.ui.csp` / `prefersBorder`. `@modelcontextprotocol/ext-apps` 2.x needs SDK v2 (`@modelcontextprotocol/server`) and zod 4. 1.7.x works with SDK `^1.29` and zod 3 if we later want its `App` class or React hooks in the view. `@mcp-ui/server` 6.x still pins ext-apps `^0.3`; skip it. * **Views are self-contained HTML built from `viewRuntime.ts`.** `VIEW_BRIDGE_JS` is a hand-rolled postMessage JSON-RPC client (`scCreateBridge`): `ui/initialize` → `ui/notifications/initialized`, then `tool-input` / `tool-result` / `host-context-changed` / `size-changed`, and `tools/call` / `ui/update-model-context` back through the host. `VIEW_THEME_CSS` maps host variables onto `--sc-*` tokens for light and dark. `mcpAppHtml()` assembles a page. No build step, no external scripts, styles, or fonts. Views set dynamic text with `textContent` only. * **Text fallback.** Every app tool returns normal `content` text plus `structuredContent`. Clients without MCP Apps support ignore `_meta` and read the text. The server cannot detect UI support per client, because the transport is stateless and `initialize` capabilities are gone by the next request. So the same response has to work both ways. ### Confirm Card (ENG-855) Every confirmation-gated member tool (any tool with a `confirm` callback or a `confirmation_token` argument, including the custom-gated `send_message`, `broadcast_event_reminder`, and `reply_to_mailbox_thread`) links to `ui://soundcheck/confirm-card.html`. When the tool returns `confirmation_required`, hosts that support MCP Apps (Cursor, Claude) render the card: the summary, an optional structured preview, a live "Expires in …" countdown, "Nothing is sent or changed until you approve.", and **Approve** / **Reject**. * **What changes for tools-only clients.** `tools/list` gains `_meta` on gated tools plus the `reject_confirmation` entry. Hosts that honour `visibility` hide that tool from the model. Other clients may show it, but its description says it is not for agents, and calling it can only void an unused token, never perform an action. Tool result `content` and `structuredContent` do not change. * **Result `_meta`, not the body.** The card's data rides in `CallToolResult._meta["soundcheck/confirm"] = { tool, arguments (without confirmation_token), preview? }`. `content` and `structuredContent` are unchanged, so tools-only clients see exactly what they saw before. The token only arrives at runtime inside the tool result; the static HTML never contains one. * **Previews.** `ToolConfirmResult.preview` (and the optional last argument of `requireConfirmation`) is `{ title, facts: [{ label, value }], recipients: [{ name, detail? }] }`. It is kept beside the confirmation payload (a `WeakMap`), so it never touches `parts`, `items`, the args hash, or the payload. `send_message`, `send_crew_offer`, and `create_event_invitations` build one from data their confirm step already has (no extra backend calls; `send_message` recipients are user ids). Other gated tools show the summary only. * **Approve.** Only a click sends `tools/call` through the host with the **same arguments** plus `confirmation_token`. The view uses the host's `ui/notifications/tool-input` arguments and falls back to `_meta` arguments; the tool name comes from `_meta` then `hostContext.toolInfo`. A busy flag disables both buttons on the first click, so a double-click sends one call. The card then shows done, the error, or a fresh card if the server asks for confirmation again. It tells the model with `ui/update-model-context` (or `ui/message` when the host only supports that). * **Reject burns the token.** Reject calls the app-only tool `reject_confirmation` (`_meta.ui.visibility: ["app"]`, accepted by preflight through `mcpAppTools()`) with `{ tool, confirmation_token, organization_id? }`. `Gate.reject` checks the token is authentic, unexpired, and bound to this caller, organization, and tool. It then claims the action row and marks it failed with `REJECTED_ACTION_ERROR`. A later approve with that token fails with "was rejected by the user … get a fresh approval" instead of the generic unresolved-outcome error. Rejecting an action that already ran, is running, or failed returns an error and changes nothing. The card also tells the model the user rejected, so the agent stops. * **Expiry.** After `expires_in_seconds` the card disables Approve and Reject and says "This approval expired. Ask the agent to prepare it again." The click handler re-checks expiry too. * **Executed results.** With the gate disabled (local dev without `MCP_CONFIRMATION_SECRET`) or after the tool ran, the card shows "Done" or the error. * **Reuse (ENG-856 / ENG-857).** Embed `VIEW_BRIDGE_JS` + `CONFIRM_STEP_JS` in a view and call `scRenderToolResult(container, bridge, { tool, arguments, preview, result, onSettled? })` or `scConfirmStep(container, bridge, { tool, arguments, preview, required, onSettled? })` to run the same Approve/Reject flow inside a larger widget. `onSettled(outcome, result)` fires once with `approved`, `failed`, `rejected`, `reject-failed`, or `expired`, so the widget can refresh or give its own controls back. ### Plan Review (ENG-856) `get_event_plan` and `review_event_plan` link to `ui://soundcheck/plan-review.html`. A tool can link to one view only, so the gated `create_draft_event_from_plan` keeps the Confirm Card link; the Plan Review runs the same confirm step inline instead. * **Data.** `get_event_plan`, `review_event_plan`, and `update_event_plan` results carry `_meta["soundcheck/plan"]`: a compact model built by `planReviewModel()` (title, dated details with provenance, venue/client, template, counts, readiness, open questions with draft-blocking ones first, open conflicts, the review's proposed changes, status, version, created gig id). `update_event_plan` gets the result `_meta` but no view link. `content` and `structuredContent` are unchanged, so tools-only clients see the same JSON as before. * **Answer / Dismiss.** Each open question gets a select built from its own `options` when it has them, otherwise a text, number, date, or time input. Save sends one `update_event_plan` with the plan's current `plan_version` and `[{ op: "answer_question", question_id, value }]` (Dismiss sends `dismiss_question`). The view submits only what the user typed or picked, never an empty answer, and re-renders from the plan in the result. * **Version conflicts.** A 412 / `PLAN_VERSION_MISMATCH` / `PLAN_CHANGED_REVIEW_REQUIRED` answer makes the view call `get_event_plan` once, show the fresh version, and tell the user nothing was saved. It never retries the write. * **Mark reviewed** calls `review_event_plan` and then shows the proposed gig. **Create draft gig** is enabled only when the plan is REVIEWED and `readiness.can_create_draft`; otherwise it is disabled and the view lists the blocking reasons. The click calls `create_draft_event_from_plan` without a token, renders the confirm step from the `confirmation_required` result, and only Approve re-sends the same arguments plus `confirmation_token`. Reject burns the token. A refusal from the tool's confirm step (plan not ready) shows as an error line. A CREATED plan shows "Draft gig created" with the gig id and no controls. * **Model sync.** After each write the view sends a one-line factual summary through `ui/update-model-context` (or `ui/message`), including the new plan version, so the agent's next edit uses it. ### Staffing Draft (ENG-857) `review_staffing_draft`, `get_crew_offer`, and `save_crew_offer` link to `ui://soundcheck/staffing-draft.html`. `send_crew_offer` keeps its Confirm Card link; the Staffing Draft runs the same confirm step inline. * **New read-only tool.** `review_staffing_draft { event_id, organization_id? }` (`mcp-ts/src/tools/staffingRoster.ts`) makes two backend reads, `v1OrganizationsOffersList` (event-scoped, complete) and `v1OrganizationsPositionsList` (`active_only: false`, for position names), and returns a model-shaped roster: shifts grouped by position, each with title, type, status, days with call times formatted in the gig's timezone, fee, `seats_needed` / `max_acceptances`, per-person name / status / delivery / fee, counts (seats, attached, accepted, declined, pending, not sent), `sendable` plus a hint, gig totals, and a `next_step` line. Names come from the `name` / `username` / `email` the offer rows already carry, so there is no per-person lookup. Both ops were already in api-events `DIRECT_OPS`. * **Data.** The roster rides in `_meta["soundcheck/staffing"]`. `get_crew_offer` and `save_crew_offer` results get a single-shift roster there, built from the offer they return with no extra read; their `content` and `structuredContent` are unchanged. * **Send.** A shift is `sendable` when it is DRAFT with people attached (or a linked call list), or OPEN with attached PENDING people whose delivery is NOT\_SENT. Its "Send…" button calls `send_crew_offer { offer_id, organization_id? }` without a token, renders the confirm step with the ENG-855 preview (which now shows people's names instead of user ids, and call times in the gig's timezone instead of raw instants; the text summary is unchanged), and only Approve re-sends with `confirmation_token`. Reject burns the token. After an approved send the view re-reads the board once and tells the model which shift was sent. * **Refresh** re-calls `review_staffing_draft` (or `get_crew_offer` for the single-shift variant). The view never calls anything on render. ### Gigs and ChatGPT extensions `open_gigs` (title **Gigs**, input `{}`) links to `ui://soundcheck/gigs.html` and lists the caller's upcoming gigs through `v1EventsList` (`upcoming: true`, active org when set). It is the first tool to use OpenAI's [MCP Extensions](https://github.com/openai/mcp-extensions/blob/main/docs/spec.md). Code: `mcp-ts/src/tools/catalog-gigs.ts`, `mcp-ts/src/apps/gigs.ts`, `mcp-ts/src/apps/openaiExtensions.ts`, `mcp-ts/src/apps/toolIcons.ts`. * **Entrypoints.** `_meta["openai/ui"].entrypoints` is `[{ type: "global" }, { type: "thread" }]`, so ChatGPT shows Gigs in the sidebar and as a thread tab. Both open the tool with `{}`. The view renders the entrypoint's tool result and does not call the tool again on first render. Refresh re-calls `open_gigs`. * **Icon.** `icons` holds one 20×20 monochrome stroke SVG (`currentColor`, 1.33px strokes) as a base64 `data:` URI. The MCP `Icon` type allows `data:` URIs, and an inline icon needs no hosting, CORS, or same-origin trust. SDK 1.30 does not serialize tool `icons`, so `decorateToolListIcons` adds them to `tools/list` responses on the member transport. * **Display modes.** Gigs declares `availableDisplayModes: ["inline", "fullscreen"]` and `preferredDisplayMode: "fullscreen"` on its resource `_meta["openai/ui"]`. Plan Review and Staffing Draft declare both modes with no preference. * **Ask about this gig.** Each row sends `ui/message` with the gig's title, date, and `event_id` when the host advertises `message`; otherwise it tells the user what to ask. **Open in Soundcheck** uses `ui/open-link` for `{appUrl}/gigs/{event_id}` when the host advertises `openLinks`, and shows the URL otherwise. * **Gig detail.** `open_gig` (title **Gig**, input `{ event_id }`) links to `ui://soundcheck/gig.html` (prefers fullscreen). It reads `v1EventsDetail` (normal event view access checks and server-side redaction), then, failing soft, crew offers and positions for the gig's org, `v1EventsRunOfShowList` when the org adopted Run of Show, and `v1EventsLedgerList` only when `viewer_capabilities.can_view_financials` is true. Money is left out of the result entirely without finance access. Code: `mcp-ts/src/tools/catalog-gig.ts`, `mcp-ts/src/apps/gig.ts`. * **Navigation.** A Gigs row calls `open_gig` from the view (`tools/call`) and renders the detail in place with a back button. The spec has no host navigation request for moving between views, and rendering in place keeps the list cached. Deep links: the Gigs view reads `hostContext["openai/deepLink"]` (`{ url }`, or the older `{ path, query }`) at initialize and on `host-context-changed`; `/gigs/{event_id}` opens the detail, `/` and `/gigs` show the list, anything else is ignored. * **Model context.** While a gig is on screen the detail sends `ui/update-model-context` with one titled text block (`_meta["openai/title"]`) naming the gig and its `event_id`, and sends `{ content: [] }` on back. Hosts without `updateModelContext` get nothing. * **Composer @-mentions.** `search_gig_mentions` (`_meta["openai/extensions"]["mentions/search"]`, `ui.visibility: ["app"]`) takes `{ query }` and returns `structuredContent.items` as `resource_link`s to `soundcheck://gig/{event_id}` (`text/markdown`). That template returns the same short summary as the `open_gig` text fallback, with the same finance gate. `soundcheck://event/{event_id}` is unchanged (raw event JSON) for other clients. * **MCP Apps off.** `registerTools` adds the OpenAI metadata only with `mcpApps: true`, so `tools/list` for other callers is unchanged apart from the two new tools. ### CSP and sandbox constraints * Hosts render the view in a sandboxed iframe on their own origin, with a CSP built from `_meta.ui.csp`. Ours declares empty `connectDomains` and `resourceDomains`, so the view **cannot fetch anything or load remote assets**. Inline `