MCP (Model Context Protocol)

Connect AI agents and personal assistants to Jade events. Lets a third-party agent register people, look up registrations, and pull details on the user's behalf — gated by an email OTP that only the person being registered can read.

The endpoint

The externally-callable MCP server lives at:

POST /api/mcp/participant-agent

Transport is streamable-http. The internal /mcp endpoint exists too but is reserved for Jade's own agent — third parties only call /mcp/participant-agent.

Discovery

Personal-assistant tooling can find the endpoint without prior configuration by fetching the well-known discovery doc: 

GET /api/.well-known/mcp.json

Response shape:

{
  "endpoints": [
    {
      "name": "participant-agent",
      "url": "/mcp/participant-agent",
      "transport": "streamable-http",
      "authentication": {
        "type": "bearer",
        "scheme": "Bearer",
        "documentation": "Issued under an API Account with `canActAsParticipantAgent: true`. Contact the event organizer to obtain one."
      },
      "tools": [
        "agent_request_otp",
        "agent_verify_otp",
        "agent_list_flows",
        "agent_submit_registration"
      ],
      "description": "Register a person for an event on their behalf."
    }
  ],
  "documentation": "/api/docs"
}

Two-layer auth

Every tool call on /mcp/participant-agent carries two identities:

  1. Agent app identity (bearer token). An Authorization: Bearer <token> header issued under an API account with the canActAsParticipantAgent flag enabled. Ask your Jade administrator to provision one — this flag is off by default.
  2. Human identity (participant session). An X-Participant-Session: <token> header carrying an OTP-derived session token. Issued by agent_verify_otp; scoped to a single (clientCode, eventCode, email); 1-hour TTL.

The OTP tools (agent_request_otp, agent_verify_otp) only require the bearer — no session token yet. Every other tool requires both.

Tool catalog

The participant-agent surface is filtered to four agent-specific tools plus the read-only participant tools used by the in-app participant chat. Mutators outside the registration pipeline, organizer tools, and enterprise tools are not exposed.

Agent tools

  • agent_request_otp — email a 6-digit code to the user. Throttled to 3 codes per email per hour and 200 codes per API account per day.
  • agent_verify_otp — verify the code; returns the session token to use on subsequent tool calls. The user has 3 attempts before the code burns; codes expire after 15 minutes.
  • agent_list_flows — list the event's visible entry flows (attendee, exhibitor, speaker, etc.) with their field schemas so the agent knows what to collect.
  • agent_submit_registration — submit the registration data. Returns a resume URL the user opens in a browser. Payment always requires the user — the URL drops the user at whatever step is next, including checkout.

Read-only participant tools (once a session is established)

  • get_my_registration — current registration data + completion status.
  • update_my_registration — patch the active registration; remaining steps still require the user to finish in browser if payment is involved.
  • check_balance_due / describe_my_flow / get_hotel_list — read-only context for the agent's UI.

What's not on the agent surface

By design, none of the following are reachable from /mcp/participant-agent:

  • Organizer tools — anything that edits event config (flows, products, discounts, pricing, hotels, theme, etc.).
  • Enterprise tools — cross-event queries, event creation, billing.
  • Support tools — agent OTP for support inboxes, identity lookup.
  • Background and reporting bulk-export tools.
  • Payment completion. Agents always hand off to the user via the resume URL returned from agent_submit_registration.

Rate limits

  • OTP per email: 3 codes per hour. Codes are bcrypt-hashed at rest; 6 digits with 3 verification attempts before burn; 15-minute TTL.
  • OTP per account: 200 codes per day. Prevents an agent app from harvesting an address book.
  • Bearer rate limit: Inherited from the API account's rateLimitPerMinute (default 60/min).

Next steps

  • Follow the MCP setup guide for a worked example from agent_request_otp through to a completed registration URL.
  • Tooling that supports MCP discovery (Claude Desktop, custom agents) can ingest /.well-known/mcp.json directly.