MCP

Transport Types

Connectors support two MCP transport types:

• Streamable HTTP (streamable_http) — default transport, uses HTTP requests with streaming responses
• SSE (sse) — Server-Sent Events, uses a persistent connection for server-to-client messages
• Stdio (stdio) — runs the MCP server as a subprocess inside the sandbox. See Stdio MCP Connectors for details.

Authentication Types

Connectors support three authentication types:

1. Static Token — shared authentication token, available to all users. Configured via the Header field (e.g., Authorization: Bearer secretkey123)
2. OAuth 2.1 — each user authenticates with their own OAuth credentials
3. JWT Passthrough — used by embedded chat, the decrypted JWT token is passed to the MCP server

Static Token

Configure a shared authentication token via the Header field (e.g., Authorization: Bearer secretkey123). This token is used for all requests to the MCP server.

OAuth 2.1

Each user authenticates individually and gets their own connection to the MCP server. OAuth tokens are stored per user — no credentials are shared between users, and one user cannot access another user's data through the connector.

When using OAuth 2.1 authentication, configure the following fields:

The authorization and token URLs are automatically discovered from the MCP server's metadata endpoint. If the MCP server supports Dynamic Client Registration (RFC 7591), the client ID and secret are obtained automatically and do not need to be configured manually.

OAuth connectors also support custom Header fields (e.g., X-Custom-Header: value), which are sent alongside the OAuth token on every request to the MCP server.

JWT Passthrough

JWT Passthrough is used with embedded chat. The website signs and encrypts a JWT token, which the platform decrypts and passes to the MCP server for authentication.

Use the %{jwt_token} placeholder in the connector Header field (e.g., Authorization: Bearer %{jwt_token}). It will be replaced with the decrypted JWT token at runtime.

How It Works

Key Pair Distribution

Two RSA key pairs are required for secure JWT token exchange:

Configure Key Pairs

1. Go to Admin → Workspaces
2. Click Add Workspace
3. Enter Name
4. Click Save Workspace
5. Click on Configure Embedded Chat and configure key pairs

Tool Approval in Embedded Chat

Embedded chats have no AI Platform user assigned to them, so there is no per-user Auto Approve preference to consult. Every tool the admin has marked Allow Auto Approve therefore runs without prompting the visitor. Tools without that flag still ask the visitor to approve each call.

Treat Allow Auto Approve as "safe to run unattended for anonymous website visitors" on any connector used by embedded chat. See Tool Approval for the full model.

Refreshing Tools

The platform needs a valid JWT token to call tools/list, and tokens only arrive with embedded chat traffic. The token from the most recently used embedded chat is reused when you click Refresh Tools, so the refresh works straight away — including when tool caching is enabled.

If that token is missing or expired (nobody has used the embedded chat, or the last chat is older than the token lifetime):

• With Cache tools list disabled, the tool list is cleared and re-fetched on the next chat message.
• With Cache tools list enabled, chats keep serving the cached list, so nothing would trigger a re-fetch. Disable Cache tools list, send a message in the embedded chat, then enable it again.

Tool Caching

By default, the platform fetches the list of available tools from the MCP server on every chat interaction. For connectors with a large number of tools or slower servers, you can enable Tools Cache to store the tool list locally and avoid repeated lookups.

Enabling Tool Caching

1. Go to Admin → Connectors → select a connector
2. Edit the connector and enable the Tools Cache toggle
3. Click Save

When caching is enabled, a "Cached" badge appears on the connector in the connectors index. To refresh the cached tools (e.g., after the MCP server adds new tools), click Refresh Tools on the connector detail page. For JWT Passthrough connectors, see Refreshing Tools.

Tool Approval

By default, tool calls require user approval before they execute, adding a consent step to the chat flow. Approval is split into two layers: org admins decide which tools may ever be auto-approved, and each user decides which of those they actually want to auto-approve in their workspace.

Admin: tool settings

Tool settings live under Admin → Tools — the Organization Policies tab in a workspace, or the whole page at organization level. It lists the tools of every connector in one table. The connector detail page does not list tools itself: it shows a tool count and a Manage Tools button that opens this page filtered to that connector.

For each tool, an admin can toggle:

• Enabled — When enabled, the tool is available for use in chats. Disabled tools are not exposed to the assistant.
• Allow Auto Approve — When enabled, individual users may opt in to auto-approving this tool. When disabled (the default), the tool always requires approval and users cannot opt out, regardless of their personal settings.
• Deferred — See Deferred Tools below.

Alongside each tool the table shows the tool's hints and how many workspaces use its connector, and you can narrow the list by name, connector, and hint — plus by workspace at organization level. The connector filter defaults to All enabled, so tools belonging to disabled connectors are hidden until you pick that connector explicitly; disabled connectors are greyed out in the dropdown. Flipping a column's header switch bulk-applies it to the currently filtered set after a confirmation dialog listing the affected tools.

The Allow Auto Approve flag is a gate, not a default — flipping it on does not auto-approve the tool for anyone. Each user must still opt in.

The one exception is embedded chat: those chats have no AI Platform user, so there is no preference to opt in with and Allow Auto Approve acts as the decision itself. See Tool Approval in Embedded Chat.

User: per-workspace auto approve

Go to Admin → Tools in a workspace — the My Policies tab, which is where the Tools page opens by default — or click the Tools button in the chat header for the same panel without leaving the conversation. It lists every enabled tool in the workspace's connectors with an Auto Approve switch (defaults to off). The switch is disabled for tools the admin has not allowed for auto-approval.

Use the search box and the hint / approval-type filters to narrow the list, then flip individual switches or use the header switch to bulk-toggle the currently filtered set. A confirmation dialog lists the affected tools before any bulk change is applied.

These settings are scoped to a (user, workspace) pair, so opting in to auto-approve for a tool in one workspace does not affect other workspaces or other users.

Approval flow at runtime

When a tool requires approval — either because the admin has not allowed auto-approval or because the user has not opted in — the chat displays the tool name and arguments and asks the user to approve or reject the call. The prompt offers Yes (approve this call only), No (reject it), and — when the admin has allowed auto-approval for the tool — Yes, always, which approves this call and turns on Auto Approve for that tool in the current workspace, so it won't prompt again. Approved calls execute normally; rejected calls return a rejection result to the assistant. Tools that are both admin-allowed and user-opted-in run without prompting.

Deferred Tools

For connectors with many tools (dozens or hundreds), loading all of them into every conversation is inefficient. Deferred tools solve this by loading tools on-demand using semantic search.

Toggle Deferred for individual tools under Admin → Tools (see Admin: tool settings). Deferred tools are not loaded into the conversation initially. Instead, when the assistant needs a tool, it uses a built-in tool_search to find relevant deferred tools by description. Matched tools are then loaded into the active conversation.

This keeps conversations lightweight while still giving the assistant access to the full tool catalog.

Stdio MCP Connectors

When the sandbox is enabled for a workspace, admins can configure MCP servers that run inside the sandbox as stdio processes using a Claude Desktop-style {command, args, env} config. This opens up the full npx/uvx MCP ecosystem — for example @modelcontextprotocol/server-everything or mcp-server-time — without needing a hosted HTTP endpoint.

Configuring a Stdio Connector

When creating or editing a connector, set the transport type to Stdio and provide:

The sandbox must be enabled on the workspace for stdio connectors to function.

Connector Settings in Chat

Users can view and manage their connector connections directly from the chat interface. A settings icon in the chat header shows the connection status of each connector assigned to the workspace:

• Green indicator — Connected and ready to use
• Red indicator — Not connected (OAuth connectors only)

For OAuth connectors, users can connect or disconnect their account directly from this panel without leaving the chat.

Troubleshooting

The tool list is empty

The tool list is populated the first time the platform successfully calls tools/list on the MCP server. Check, in order:

1. The connector is Enabled and assigned to the workspace you are chatting in.
2. Click Refresh Tools on the connector detail page — the resulting flash message reports the exact MCP error if the connection fails.
3. For JWT Passthrough connectors, a token is required to reach the server. See Refreshing Tools.
4. For OAuth connectors, tools are only fetched for users who have connected their account. An unconnected user sees the cached list, which is empty until someone connects and chats.

The assistant says a tool is not available

• The tool is disabled. Only tools with Enabled on are exposed to the assistant. Check the table under Admin → Tools.
• The tool is deferred. Deferred tools are not loaded up front; the assistant has to find them via tool_search first. If it consistently fails to find one, improve the tool's description on the MCP server, or turn Deferred off for that tool.
• The tool list is stale. With tool caching enabled, tools added on the MCP server do not appear until you click Refresh Tools.
• The connector failed to connect during the chat. Connector failures do not abort the chat — the assistant simply continues without those tools. Check the server logs (or Sentry) for MCP Service: Failed to connect to <connector>.

Tools disappeared after a refresh

Refresh Tools reconciles the list with what the server currently reports and deletes tools the server no longer returns, along with their per-tool settings (Enabled, Allow Auto Approve, Deferred). If a server temporarily renames or hides tools, refreshing drops them; refreshing again after the server recovers re-creates them with default settings.

Every tool call asks for approval

The user has not opted in to Auto Approve, or the admin has not enabled Allow Auto Approve for the tool — both are required. See Tool Approval. In embedded chat only the admin flag applies; see Tool Approval in Embedded Chat.