Team MCP for the AI agent

Standard remote MCP contract Ticketping expects from your server — transport, auth modes, read-only tools, and how to connect.

Ticketping’s support AI can call your tools over the Model Context Protocol. We act as an MCP client. You host a normal remote MCP server; there is no Ticketping-specific RPC, SDK, or required tool names.

The same connection powers widget chat, on-demand ticket drafts (including email tickets), and future email auto-draft. Teams that skip MCP can still use the agent with static knowledge in Settings → AI agent.

What to expose

PieceExpectation
TransportStreamable HTTP (preferred) or SSE-compatible responses on one HTTPS endpoint
ProtocolJSON-RPC 2.0: initialize, notifications/initialized, tools/list, tools/call
AuthSee Authentication below
Customer-facing toolsRead-only lookups only (docs search, account status, order status, …)
Response shapePrefer JSON with title + url (and a short snippet) so we can show citations

Writable actions (refunds, cancels, deletes) are blocked for the customer-facing agent today, even if the tool appears in tools/list.

Authentication

Ticketping supports two auth modes on Settings → AI agent → MCP.

Bearer (standard MCP — default)

This is the usual “point an MCP client at a server” path (the same idea as connecting MCP in Grok or Cursor).

  1. Your server accepts Authorization: Bearer <token> (optional extra headers are also supported).
  2. You paste that token into Ticketping.
  3. Every tools/list and tools/call uses that static bearer.

No Ticketping-specific protocol. If your MCP server works with other clients using a shared secret, use Bearer.

Identity exchange (optional on-behalf-of bridge)

Some partners need tools scoped to the verified Ticketping customer (orders, balance, eSIM usage) without letting the model pick a user id.

Identity exchange is not part of the MCP specification. It is Ticketping’s optional bridge:

  1. The widget (or host app) identifies the visitor with a Ticketping identity JWT (sub = your user id). Ticketping stores Customer.external_id / email and discards the original JWT.
  2. On each AI turn, Ticketping remints a short-lived identity JWT with your team’s identity secret (sub, email, aud: "ticketping").
  3. Ticketping POSTs that JWT to your token URL with your partner server key (X-Ticketping-Key header, and/or server_key in the JSON body).
  4. You return { "access_token": "…", "token_type": "Bearer", "expires_in": 120 }.
  5. Ticketping calls your MCP URL with that short-lived bearer. Anonymous chats skip the exchange and call MCP with no user bearer (catalog-style tools can still work if you allow it).
SettingRole
MCP Server URLYour Streamable HTTP MCP endpoint
Auth modeidentity_exchange
Token URLYour exchange endpoint
Partner server keyShared secret; sent as X-Ticketping-Key (not an MCP bearer)

Use this mode only when your server must authorize per end-user. Do not point the customer-facing agent at a commerce MCP that can create orders, cancel, or reveal codes.

Most teams should use Bearer. Choose identity exchange only if you have built (or been given) a token endpoint that accepts Ticketping identity JWTs.

Recommended tools (conventions)

Names are yours to choose. These shapes work well:

Docs search

json
{
  "name": "search_docs",
  "description": "Search the public help center and product docs",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" }
    },
    "required": ["query"]
  }
}

Return something like:

json
{
  "results": [
    {
      "title": "How refunds work",
      "url": "https://docs.example.com/refunds",
      "snippet": "Refunds are available within 14 days…"
    }
  ]
}

Any JSON object with a url (nested lists included) can become a citation. You do not need a special “MCP response guide” in Ticketping — clear tool descriptions and JSON are enough for the model.

Account / order lookup (read-only)

json
{
  "name": "get_account_status",
  "description": "Look up subscription status for a customer id or email",
  "inputSchema": {
    "type": "object",
    "properties": {
      "customer_id": { "type": "string" },
      "email": { "type": "string" }
    }
  },
  "annotations": { "readOnlyHint": true }
}

Mark read-only tools with annotations.readOnlyHint: true when you can. Tools whose names look mutating (refund, delete, cancel, …) are treated as writable and stay off the allowlist.

Optional conventions Ticketping understands

ConventionEffect
url / title on result objectsShown as citations when possible
"needs_human": true (plus optional customer-safe message)Widget handoff / draft marked as needing human judgment
Prefetch toggle on a tool in the dashboardCalled once before the model on each turn (when identity rules allow), result injected as context

Account-looking tool names (order, account, snapshot, esim, …) require a verified customer; anonymous visitors are asked to sign in or handed off.

Connect in Ticketping

  1. Open Settings → AI agent → MCP.
  2. Paste your MCP URL.
  3. Choose Bearer or Identity exchange (and token URL + partner key if exchange).
  4. Turn Enabled on and click Test & sync tools.
  5. Allowlist only the tools the customer-facing agent may call. Optionally turn on Prefetch for context tools (e.g. a support snapshot).
  6. Optionally add Guidance (tone, when to escalate) — not for teaching the model how to parse your JSON.
  7. Use Preview to try the same runtime as the widget. Use Draft reply on a ticket to exercise the same MCP path for email/inbox.

Limits we enforce: about 15s per tool call, a small number of tool rounds per turn, and truncated tool results so chats stay responsive.

Chat and email

SurfaceBehavior
Widget chatAuto-replies with allowlisted MCP tools when AI answers are on
Ticket draftSame agent + MCP; agents request a draft from the inbox
Email-only teamsUse draft today; auto-draft / gated auto-send are planned separately

Identity exchange needs a linked customer with external_id. Email tickets that only have an address use bearer/anonymous semantics until the customer is identified.

Without MCP

If you do not run an MCP server yet:

  1. Add articles under Settings → AI agent → Knowledge.
  2. Turn on AI answers for your widget.
  3. The agent answers only from that knowledge (or hands off to a human).

You can keep knowledge articles after you connect MCP — they act as short policy / tone context alongside live tools.

Migration and reuse

  • The same MCP server works with other MCP clients (Cursor, Claude, custom agents) when you use Bearer auth.
  • Identity exchange is Ticketping-specific; other MCP clients will not perform that exchange unless you build it for them separately.
  • No Ticketping SDK is required for a minimal Streamable HTTP MCP server in Node or Python.

Minimal curl check

After initialize (and reading Mcp-Session-Id if the server returns one):

bash
curl -s -X POST 'https://mcp.example.com/mcp' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-03-26' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

You should get a JSON-RPC result with a tools array. If that works, Test & sync in the dashboard should too.

Start with one read-only `search_docs` tool. Allowlist it, preview a few questions, then add account lookups once answers look solid.