MCP integration
Since v0.4.0. Production stable can lag behind new releases. If the version in its manifest is older than v0.4.0, load a pinned vX.Y.Z path (v0.4.0 or later) instead. Use MCP integration when your application already exposes data or operations through a remote MCP server. The chatbot can call an approved set of tools for the user signed in to your page.
The browser calls your MCP endpoint directly. This flow is for user-scoped operations. Keep backend-only credentials out of it; see Security and CSP.
What to provide to Tiketo
Section titled “What to provide to Tiketo”For each server, provide:
- an absolute HTTPS MCP endpoint that uses Streamable HTTP; URLs must not contain credentials, including query-string credentials;
- the tools to enable, with each tool classified as
readorwrite; - a description and JSON input schema for each enabled tool, or access for Tiketo to create a filtered snapshot;
- the frontend origins that will host the chatbot;
- a test account for integration and agent evaluation.
The allowlist denies all tools by default. Tiketo gives each endpoint a short server key. The chatbot can call only the tools configured for that key. Keep real endpoints and customer configuration out of client-side integration code.
Register browser authentication
Section titled “Register browser authentication”Register each server before or after init. The header provider runs for every MCP request, so your application can refresh credentials when needed. This example supplies the signed-in user’s bearer token:
tiketoChat("mcp", "primary", { headers: async () => ({ Authorization: "Bearer " + await getToken(), }),});
tiketoChat("mcp", "analytics", { headers: async () => await getAnalyticsHeaders(),});
tiketoChat("mcp", "cookie-session", { credentials: "include",});The object can contain authorization, API-key, tenant, or other headers expected by your server. Header mode is the default because many MCP servers advertise bearer_methods_supported: ["header"] in their OAuth protected-resource metadata and accept bearer credentials only in Authorization. For cookies, set credentials: "include"; the header provider is optional. Calling the command again replaces that server’s registration. On logout, remove it with tiketoChat("mcp", "primary", null) and call reset to discard the conversation and all MCP session IDs.
The embed controls protocol and correlation headers. It accepts Authorization and custom headers, but ignores host values for Content-Type, Accept, mcp-session-id, MCP-Protocol-Version, X-Tiketo-Conversation-Id, and X-Tiketo-Request-Id.
Register MCP access in an effect. Remove it when the signed-in session changes or the component unmounts:
import { useEffect } from "react";
export function ChatMcpAuth({ getToken }: { getToken(): Promise<string> }) { useEffect(() => { tiketoChat("mcp", "primary", { headers: async () => ({ Authorization: `Bearer ${await getToken()}` }), }); return () => tiketoChat("mcp", "primary", null); }, [getToken]);
return null;}MCP server CORS
Section titled “MCP server CORS”Allow requests from every frontend origin that uses the client ID. Permit POST and list Authorization, Content-Type, Accept, mcp-session-id, MCP-Protocol-Version, X-Tiketo-Conversation-Id, and X-Tiketo-Request-Id, plus every custom host header. Access-Control-Allow-Headers: * does not cover Authorization under the Fetch standard. Expose mcp-session-id so the browser can keep the server’s session identifier. Your page’s Content Security Policy must also list the MCP origin in connect-src; see Security and CSP.
For bearer header mode, a preflight response can be:
HTTP/1.1 204 No ContentAccess-Control-Allow-Origin: https://app.example.comAccess-Control-Allow-Methods: POST, OPTIONSAccess-Control-Allow-Headers: Authorization, Content-Type, Accept, mcp-session-id, MCP-Protocol-Version, X-Tiketo-Conversation-Id, X-Tiketo-Request-IdAccess-Control-Expose-Headers: mcp-session-idVary: OriginCookie mode requires the exact frontend origin, not *, and the credentials flag:
HTTP/1.1 204 No ContentAccess-Control-Allow-Origin: https://app.example.comAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: POST, OPTIONSAccess-Control-Allow-Headers: Authorization, Content-Type, Accept, mcp-session-id, MCP-Protocol-Version, X-Tiketo-Conversation-Id, X-Tiketo-Request-IdAccess-Control-Expose-Headers: mcp-session-idVary: OriginCheck the deployed preflight from an allowed frontend origin. Add every custom host header to the request and the server allowlist.
curl -X OPTIONS 'https://mcp.example.com/rpc' \ -H 'Origin: https://app.example.com' \ -H 'Access-Control-Request-Method: POST' \ -H 'Access-Control-Request-Headers: Authorization, Content-Type, Accept, mcp-session-id, MCP-Protocol-Version, X-Tiketo-Conversation-Id, X-Tiketo-Request-Id' \ -iProtocol and transport
Section titled “Protocol and transport”The embed supports MCP 2025-06-18 and sends MCP-Protocol-Version: 2025-06-18. It does not negotiate another version from the initialize response. The changelog will announce support for a newer version before it is enabled.
The transport is POST only. The embed never opens a GET SSE stream, so a stateless server needs no GET handler. POST responses may use text/event-stream or application/json.
Every MCP HTTP request includes:
Content-Type: application/json;Accept: application/json, text/event-stream;MCP-Protocol-Version: 2025-06-18;mcp-session-idafter the server establishes a session;X-Tiketo-Conversation-Id, an opaque per-chat-session ID generated by the embed;X-Tiketo-Request-Idontools/callonly; and- the headers returned by the host provider.
The embed rotates X-Tiketo-Conversation-Id on reset, logout, or a widget Restart conversation / Start new chat action. It records the same opaque per-chat-session ID generated by the embed in the new launch event as tiketoConversationId, so Tiketo can correlate it with transcripts on request. Hosts can observe widget restarts with tiketoChat("on", "restart", ({ tiketoConversationId }) => { /* new chat */ }). X-Tiketo-Request-Id matches params._meta["tiketo/requestId"].
Credential and data handling
Section titled “Credential and data handling”Authentication headers are read only when an MCP request is about to be sent. Tiketo Chat does not cache, persist, or log their names or values. It does not include them in completion events. They travel from the browser to your configured MCP endpoint and are not sent to Tiketo’s Worker or the conversation service.
Tool arguments and results are part of the chatbot task. The conversation service processes them, and they can appear in transcripts. Enable only tools whose input and output are suitable for that data path.
Tiketo can configure a server argument as bound to a host context field, for example projectId from tiketoChat("context", { projectId }). On every call the embed reads the current context, overwrites that argument even if the model supplied another value, and only then prepares the MCP request. A missing or blank bound value returns context_missing before authentication, confirmation, initialization, or any network request. Servers without bound arguments are unaffected. Bound values are still ordinary tool arguments and can appear in conversation transcripts.
A binding can apply to every tool on a server or only to selected tools. This keeps mixed-schema servers safe: for example, a workspace ID can be required and host-overwritten for a data-query tool without adding an unsupported field to a schema-discovery tool.
Ask Tiketo for the retention, region, and subprocessor documentation that applies to your integration.
Write tools always show an explicit confirmation in the chat before the browser makes a network request. Declining returns cancelled and sends nothing to the MCP server. The confirmation waits at most the server’s timeoutMs (20 seconds by default, 32 seconds for Tiketo CMS); an unanswered confirmation also returns cancelled. The call budget below starts only after the user confirms.
Treat tool results as untrusted third-party text. The chatbot can call only allowlisted tools, and every write requires fresh user confirmation in the UI. Tool text cannot authorize or execute a write by itself.
Limits and results
Section titled “Limits and results”The per-server timeoutMs setting (default 20 seconds) bounds each HTTP request separately: initialize, notifications/initialized, tools/call, and every retry each get the full bound, covering header resolution, the network request, response reading, and parsing. Set it above your server’s worst-case execution time, otherwise the embed can abort a write that the server still completes. The Tiketo CMS server always uses at least 32 seconds, above its 30-second gateway limit. A whole call also has an overall budget of three times timeoutMs: after it is spent, no new request or retry wait starts, but a request already in flight keeps its full bound. The worst-case wall time of one call after confirmation is therefore about four times timeoutMs: 80 seconds by default and about 128 seconds for Tiketo CMS (a 96-second budget plus a 32-second request already in flight). The default result limit is 8,000 Unicode characters; Tiketo can change the server default or set a per-tool limit. Only text content items are passed to the chatbot. Other content types become short placeholders, and truncated says whether text was cut. structuredContent is not passed to the chatbot, so always include a text rendering in content. The only part the embed reads is the execution state of an isError result (see below).
Every response also has a byte ceiling. The per-server maxResponseBytes setting defaults to 1 MiB and stops JSON or SSE bodies as soon as they exceed the limit.
One user turn can make a bounded chain of up to four MCP calls when an answer needs hints, schema information, and a final data query. The intermediate decision steps are silent. Only the final result prompt produces a user-visible answer; a single-call request follows the same final path after its first result.
Each chatbot tool call gets a new opaque ID in _meta["tiketo/requestId"]. Use it to de-duplicate writes. The embed keeps the same ID if it sends that logical call again:
| Condition | Embed behavior |
|---|---|
401 |
Calls the header provider again and retries once with the same request id; another 401 or a 403 returns not_authenticated. A 401 means the server rejected the caller before running anything, so that attempt did not execute. |
403 |
No retry; returns not_authenticated. |
404 with mcp-session-id |
Re-initializes once and retries once with the same request id. The unknown session means the server did not execute that attempt. |
Read call transport timeout, network reset/failure, or HTTP 5xx |
Retried once with the same request ID. Tool-level isError, JSON-RPC errors, invalid results, and HTTP 4xx are not retried. |
503 with JSON-RPC error.data { "code": "AUTH_UNAVAILABLE", "retryable": true } |
The only failure a write retries. Waits for Retry-After (clamped to 0.5–3 seconds, default 1 second), then retries the whole call once with the same request ID. The wait does not count against timeoutMs; if it would end after the call budget, the retry is skipped and the call returns mcp_unavailable with executed: false. A body over 16 KB is not trusted as this marker. |
Marker contract. The embed trusts the AUTH_UNAVAILABLE marker from any configured MCP server, not only Tiketo CMS. A server may send 503 with AUTH_UNAVAILABLE and retryable: true only before it executes anything for that request, for example when it cannot verify the caller yet. Never send it after a tool has started running or after a write may have taken effect: the embed would send the write again. Every other 503 and every other 5xx is treated as an unknown outcome for writes and is not retried.
After timeout or mcp_unavailable, the chatbot is instructed not to repeat a write automatically. A write timeout means the outcome is unknown, not that it failed: the server may still have completed it. The chatbot tells the user that the outcome is unknown, never repeats the write blindly, and verifies the current state with a read tool before any retry the user confirms.
A failed write result can carry an executed field that overrides this default reading:
executed: false: the write provably did not run, so the chatbot says nothing changed. The embed sets it withmcp_unavailablewhen notools/callrequest of the call could have executed: it was never sent (for exampleinitializefailed or the call budget ran out before theAUTH_UNAVAILABLEretry), or every one sent was answered with401,AUTH_UNAVAILABLE, or an unknown-session404.executed: "unknown": the write may have run even though the error istool_error. The embed sets it when theisErrorresult’sstructuredContent.errorhasexecuted: "unknown", or hascode: "TIMEOUT"from a write tool: the server stopped waiting for its upstream, which may still commit.
An explicit structuredContent.error.executed of false or "unknown" from the server is forwarded as is and wins over the TIMEOUT rule: code: "TIMEOUT" with executed: false stays executed: false.
The Tiketo CMS create pass template workflow makes up to 9 MCP calls plus design-generation steps. It starts no new step after 180 seconds and then stops with budget_exhausted, so its worst case is about 180 seconds plus one call already in flight and one design step. When a create ends with an unknown outcome, the chatbot remembers that template name. If a later request for the same name finds it in the workspace’s template list, the chatbot reports that a template with this name exists, most likely from the earlier attempt, and that nothing new was created, instead of reporting a duplicate name. The list read shows only that the name exists, not who created the template.
| Error | Meaning |
|---|---|
not_authenticated |
No header/cookie registration exists, the provider failed, or authentication still failed after one retry. |
tool_not_allowed |
The tool is not in that server’s explicit allowlist. No request was sent. |
unknown_server |
The server key is not configured for this client. |
context_missing |
A configured bound argument has no non-empty string value in the current host context. No request was sent. |
invalid_arguments |
The MCP server returned JSON-RPC error -32602. |
timeout |
A request exceeded timeoutMs, or the overall call budget was spent. For a write, the outcome is unknown; a write whose tools/call provably did not run returns mcp_unavailable with executed: false instead. |
tool_error |
The tool returned isError, or JSON-RPC returned another tool error. executed: "unknown" marks a write whose outcome is unknown. |
mcp_unavailable |
The endpoint could not be reached, including network and CORS failures. With executed: false, a write provably did not run. |
cancelled |
The user declined a write-tool confirmation. |
Tool schema synchronization
Section titled “Tool schema synchronization”The chatbot’s schema snapshot is generated from the configured allowlist. Tiketo refreshes it in a pull request after your team announces a tool schema change. If a server changes an input schema without notice, the chatbot can send outdated arguments. The server should return JSON-RPC -32602, which becomes invalid_arguments.
Adding or removing a tool requires a client configuration change, a schema snapshot change, and a deploy. It does not require a new embed version because the generic mcpCall@1 browser contract stays the same.
Tiketo CMS read access
Section titled “Tiketo CMS read access”The tiketo-cms chatbot can use the CMS MCP server for read-only workspace questions. Its allowlist contains only describe_schema and ts_query; no create, update, publish, or delete tool is enabled. The browser supplies the signed-in user’s authorization header for each MCP request, and the current workspaceId host context is always substituted into ts_query before the request is sent.
The assistant calls describe_schema only when it needs exact table or column names, then answers a data question from the ts_query result. Tool results remain bounded by the CMS server’s 7,500-character complete-response contract and the chatbot’s configured result limit.
Client checklist
Section titled “Client checklist”- The endpoint is absolute HTTPS and implements Streamable HTTP with protocol version
2025-06-18. - The enabled tool list and read/write classifications are agreed with Tiketo.
- The MCP server validates the logged-in user’s authorization and tenant scope for every call.
- CORS allows each frontend origin and every header the provider can return, and exposes
mcp-session-id. - The
curl -X OPTIONSpreflight check succeeds for each frontend origin and auth mode. - The bearer token or other credential is available through an async host function and is never hard-coded.
- Write-tool confirmation, timeout behavior, result limits, token refresh, and logout removal/reset have been tested.
- Tiketo has a non-production test account for evaluation.