How do I connect MCP tools to my assistant?

Two sources of tools

• Marketplace — a curated set of providers with their MCP URLs, OAuth endpoints and scopes pre-filled, so you don't hand-type them. The end-user marketplace holds ten providers today — Linear, Notion, GitHub, Atlassian, Intercom, ClickUp, monday.com, Sentry, Stripe and Miro — and each visitor authorizes their own account.
• Custom MCP — any MCP server you've deployed on CMD+K (built from your API or hosted as-is), or any third-party MCP URL you add yourself.

Slack, and other connectors that only make sense with one workspace-wide credential, live on the Assistant tools tab: your workspace connects them once and the assistant uses that connection for every visitor. They are not per-end-user tools.

Assistant tools vs. your users' tools

The Tool library has two tabs, matching two audiences. Assistant tools are connections your workspace makes once — your docs, your Calendly, your status page — so the assistant answers better and can act. Your users' tools are tools each end user connects with their own account (their Linear, their Notion) and uses right in chat through your product. End-user tools always require OAuth — each user authorizes their own account — or, for your own product, verifying the widget JWT. See connection modes for how that trust works, and End-user tools: OAuth model for the per-provider table — which providers exist, which OAuth client mode each supports, the callback URL to register, and where the tokens live.

Per-widget allowlist

Even if your workspace has 50 tools connected, each assistant only exposes the ones on its allowlist. This keeps the model focused and prevents a marketing widget from calling destructive support tools. Edit the allowlist from the assistant's Tools tab.

Which tools reach the model on a given turn

Every tool on the allowlist is callable, but they are not all described to the model on every turn. Up to 24 bound tools the whole set is sent. Above that, the visitor's message is matched against your tools and the 20 closest are described for that turn, which keeps a large connector from spending the whole prompt on schemas the question cannot reach.

Three groups are always present regardless of the match: the tools behind the use cases configured on the assistant, the provider's identity tool, and every tool already called in the current conversation. If the match cannot be computed at all, the full set is sent instead of a reduced one, so a selection problem never looks like a missing capability. Each assistant turn in Dashboard → Conversations records how many read and write tools were offered and whether that turn went through per-turn selection.

How writes are reported

The assistant only reports a create, update or delete as done when the matching tool call ran and succeeded in that same turn. If a write fails — a value the API rejects, a permission error — it says what failed, and a “yes, go ahead” from the visitor produces a fresh approval card and a real retry, never a success sentence on its own.

Constrained values follow the same rule. Locale, status, label, priority and similar fields are read from your account first and passed from that list; they are never inferred from the content — a Turkish draft does not make the assistant guess a Turkish locale that your project has not enabled.

End-user consent flow

1. A signed-in visitor asks for something that needs their own account. Anonymous visitors can't hold a personal connection, so the tool is never offered to them.
2. The widget shows a Connect card; clicking it opens the provider's OAuth popup.
3. The token is encrypted and stored against that visitor's identity, then reused across sessions and refreshed automatically.
4. The visitor disconnects from Your connections in the widget header; a workspace owner or admin can revoke it from Dashboard → Users → the visitor. Both delete the stored token; neither revokes the grant upstream at the provider.

How much tool output reaches the answer

Each tool result is capped on its own, and the results of one turn share an evidence budget of roughly 24,000 characters. When a turn goes over — seven full article bodies alongside a short issue list, say — the largest results are trimmed first and the small ones are left whole, each trimmed result ending with a visible marker. Only the copy sent to the model is shortened: the full result stays in the conversation log and in the tool card the visitor sees. If an answer needs one item in full, ask for that item on its own.

Write, destructive, and what the visitor approves

Every tool the assistant can call is classed read, write, or destructive. Read tools run on their own. Write and destructive tools stop at an approval card first, and the destructive ones are styled as the loud, red variant.

• Destructive means the change cannot be taken back — delete, remove, purge, wipe, drop, revoke, reset, an HTTP DELETE, or a description that says the change cannot be undone. A tool that creates or updates a record — Linear's save_issue, an add_comment, an update_* — is a plain write, even when the upstream server marks it with the MCP destructiveHint. That hint means "not purely additive", which is true of every update, so on its own it does not earn the red badge. Tools that reach people — send_*, publish_*, post_*, reply_*, merge_* — keep the loud badge when the server marks them: an email to your subscribers is no more recallable than a deletion.
• Cancel is final. Cancelling an approval card records the decision on the conversation. Reloading the page, reopening the chat, or replaying the history never brings that card back, and the action can no longer be resumed — ask again to get a fresh card.
• The visitor's scope gates their own connections too. A JWT whose scopes claim has no write gets read tools only — from your workspace's assistant tools and from the visitor's personal connections. A read-only visitor is never shown an approval card for their own Linear or Notion, because the write tool is never offered in the first place.

Adding a custom MCP

Deploy your MCP server via Build MCP first, then return here and click Add custom MCP. You'll see all your workspace's deployments — pick one and choose which tools to expose.