MCP integration

MCP integration is useful when your application already exposes business data or operations through a remote MCP server. Tiketo Chat can let the agent call an explicitly allowed subset of those tools on behalf of the user who is signed in to your host page.

The call is made by the browser directly to your MCP endpoint. Use this integration for user-scoped operations. Do not use it for service credentials or secrets that must stay on a backend.

What to provide to Tiketo

For each server, provide:

an absolute HTTPS MCP endpoint using the Streamable HTTP transport; URLs must not contain credentials, including query-string credentials;
the tools to enable, with each tool classified as read or write;
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 is default-deny. Tiketo assigns each endpoint a short server key, and the agent can only call tools configured under that key. No real endpoint or customer configuration belongs in client-side integration code.

Register browser authentication

Register each server before or after init. The header provider runs for every MCP HTTP request, so your application can refresh credentials when needed. A typical server accepts the logged-in user’s bearer access 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 may contain bearer authorization, API-key headers, tenant headers, or any other headers your server expects. If a server uses cookies, set credentials: "include"; the header provider is then optional. Calling the command again replaces that server’s registration. Remove it during logout with tiketoChat("mcp", "primary", null) and call reset to discard the chat and all MCP session IDs.

Protocol headers are controlled by the embed. Values supplied for Authorization or custom headers are accepted, but host values for Content-Type, Accept, mcp-session-id, and MCP-Protocol-Version are ignored.

React

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

Your MCP server must allow requests from every frontend origin where the configured client ID is used. Allow POST and the request headers Authorization, Content-Type, Accept, mcp-session-id, and MCP-Protocol-Version, plus every custom header returned by your provider. Expose mcp-session-id so the browser can retain the server’s session identifier.

Do not use a wildcard origin with credentialed requests. Return the exact allowed origin and include the appropriate Vary: Origin response header.

Credential and data handling

Authentication headers are read only when an MCP request is about to be sent. Tiketo Chat does not cache their values, persist them, put them in done events, or log their names or values. They travel only from the browser to your configured MCP endpoint; they are not sent to Tiketo’s Worker or Voiceflow.

Tool arguments and tool results are different: the agent needs them to perform the task, so they are processed by the agent and can appear in conversation transcripts. Do not enable tools whose arguments or output are inappropriate for that data path.

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.

Limits and results

The default timeout is 20 seconds per call and covers authentication header resolution, network requests, response reads, parsing, and retries. The default result limit is 8,000 Unicode characters; Tiketo can configure a different server default or a smaller/larger per-tool limit. Text content items are concatenated. Other content types are represented by short placeholders, and truncated reports whether text was cut.

Every response also has a streamed byte ceiling. The per-server maxResponseBytes setting defaults to 1 MiB and stops JSON or SSE bodies as soon as they exceed that limit.

The embed retries once after 401 or 403, calling your header provider again. A stale server session that returns 404 is initialized once more and the tool call is retried once.

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.
`invalid_arguments`	The MCP server returned JSON-RPC error `-32602`.
`timeout`	The configured call deadline expired.
`tool_error`	The tool returned `isError`, or JSON-RPC returned another tool error.
`mcp_unavailable`	The endpoint could not be reached, including network and CORS failures.
`cancelled`	The user declined a write-tool confirmation.

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 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.