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
| Piece | Expectation |
|---|---|
| Transport | Streamable HTTP (preferred) or SSE-compatible responses on one HTTPS endpoint |
| Protocol | JSON-RPC 2.0: initialize, notifications/initialized, tools/list, tools/call |
| Auth | See Authentication below |
| Customer-facing tools | Read-only lookups only (docs search, account status, order status, …) |
| Response shape | Prefer 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).
- Your server accepts
Authorization: Bearer <token>(optional extra headers are also supported). - You paste that token into Ticketping.
- Every
tools/listandtools/calluses 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:
- The widget (or host app) identifies the visitor with a Ticketping identity JWT (
sub= your user id). Ticketping storesCustomer.external_id/ email and discards the original JWT. - On each AI turn, Ticketping remints a short-lived identity JWT with your team’s identity secret (
sub,email,aud: "ticketping"). - Ticketping
POSTs that JWT to your token URL with your partner server key (X-Ticketping-Keyheader, and/orserver_keyin the JSON body). - You return
{ "access_token": "…", "token_type": "Bearer", "expires_in": 120 }. - 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).
| Setting | Role |
|---|---|
| MCP Server URL | Your Streamable HTTP MCP endpoint |
| Auth mode | identity_exchange |
| Token URL | Your exchange endpoint |
| Partner server key | Shared 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.
Recommended tools (conventions)
Names are yours to choose. These shapes work well:
Docs search
{
"name": "search_docs",
"description": "Search the public help center and product docs",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string" }
},
"required": ["query"]
}
}Return something like:
{
"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)
{
"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
| Convention | Effect |
|---|---|
url / title on result objects | Shown 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 dashboard | Called 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
- Open Settings → AI agent → MCP.
- Paste your MCP URL.
- Choose Bearer or Identity exchange (and token URL + partner key if exchange).
- Turn Enabled on and click Test & sync tools.
- Allowlist only the tools the customer-facing agent may call. Optionally turn on Prefetch for context tools (e.g. a support snapshot).
- Optionally add Guidance (tone, when to escalate) — not for teaching the model how to parse your JSON.
- 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
| Surface | Behavior |
|---|---|
| Widget chat | Auto-replies with allowlisted MCP tools when AI answers are on |
| Ticket draft | Same agent + MCP; agents request a draft from the inbox |
| Email-only teams | Use 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:
- Add articles under Settings → AI agent → Knowledge.
- Turn on AI answers for your widget.
- 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):
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.