Skip to main content

MCP server selection

Discovery exposes available servers and tool schemas. The effective conversation, profile or per-send selection determines which servers a generation can use.

Platform servers​

The next turn uses the configured server selection when it is the effective list. An active agent profile replaces conversation settings, so put the server on that profile when your application uses one.

To expose only selected discovered tools, add allowlistToolPatterns using their discovered names. A blocklist takes precedence over the allowlist. Keep one reference per server; duplicate references do not combine their filters.

Per turn servers​

The next normal turn inherits its configuration again. An empty override currently inherits too; it does not clear tools. Queued turns currently lose their overrides when later dequeued, so do not depend on this mechanism to restrict queued work. Tool selection does not establish a separate authorization ceiling; only trusted callers should choose it.

MCP server selection​

Updating conversation settings replaces the whole settings object. Read its current value and preserve unrelated settings when changing server selection.

mcpServers on conversation settings is the base set of MCP servers. Three tiers resolve in order, with each tier replacing the one below:

  1. Per-send override (overrideMcpServers on the send request) — applies only to that send.
  2. Active profile (profile.mcpServers) — replaces conversation-level servers while the profile is active; an empty list means no servers.
  3. Conversation settings (settings.mcpServers) — the baseline.

No server is attached unless one of these tiers names it — including the platform's own catalog (built-in:tavily, built-in:firecrawl, …). See Platform-provided servers.

Each server reference carries allowlistToolPatterns and blocklistToolPatterns — glob patterns enforced at call time to control which of that server's tools the model may use.