# Connect MCP Servers to Your Bot MCP servers let your AI bot use tools from another system during live conversations — without you having to build each tool by hand. You point the bot at an MCP server once, and every tool that server offers becomes available to the bot automatically. If you've used Custom Functions, this is the same idea, taken one step further: a custom function is a single tool you wire up yourself, while an MCP server is a ready-made bundle of tools the bot can discover and call on its own. --- ## What Is an MCP Server? MCP (Model Context Protocol) is an open standard for giving AI assistants access to external tools. Lots of modern apps and services now publish an "MCP server" — a single web address that exposes a set of tools the AI can call: look something up, fetch a record, run a query, create an item. Instead of describing each tool to the bot, you give Your AI Connector the server's address and an access key. Your AI Connector asks the server "what can you do?", gets back the list of tools, and makes them available to your bot. When the server adds a new tool, your bot can use it without any extra setup on your side. **Custom Functions vs MCP Servers — which to use:** | | Custom Functions | MCP Servers | | ------------------ | --------------------------------------------------- | -------------------------------------------------------------- | | **What you set up** | One tool at a time, fully by hand (URL, inputs, response mapping). | One server address — the bot discovers all its tools for you. | | **Best for** | A single, specific call to your own system. | Connecting to a service that already speaks MCP and offers many tools. | | **Maintenance** | You update the function when the tool changes. | New tools from the server appear automatically. | You can use both at the same time on the same Agent. --- ## How It Works (The Simple Version) 1. You **register an MCP server** on the **MCP Servers** page — its web address and an authorization header (usually an API key). 2. Your AI Connector **connects and discovers** the server's tools, and remembers the list. 3. You **enable the server on an Agent**. 4. During a conversation, when the customer asks for something a tool can answer, **the bot calls the tool**, reads the result, and replies naturally. The customer never sees the machinery — they just get an answer backed by real, up-to-date information. ### What an MCP tool call costs A tool call from an MCP server is billed exactly like a custom function call, at your Agent's AI Quality tier: | AI Quality tier | Credits per MCP tool call | With your own Anthropic key (BYOK) connected | |---|---|---| | Pro | 1 credit | 0 credits — runs on your key | | Economy (deprecated) | 0.5 credits | 0 credits — runs on your key | | Max | 0.25 credits | still 0.25 credits, billed even with your own key connected, because Max runs on our own model | | Mini | 0.15 credits | still 0.15 credits, billed even with your own key connected, because Mini runs on our own model | --- ## Adding an MCP Server (Step by Step) In the main sidebar, under **AI Studio**, click **MCP Servers**. Then click **+ Add Server**. Fill in the form: | Field | What to Enter | Example | | -------------------- | ----------------------------------------------------------------------------- | --------------------------------- | | **Name** | A short label for the server (also used to name its tools for the bot). | `Order System` | | **Server URL** | The server's MCP address (sometimes called an "endpoint"), starting with `https://`. | `https://tools.mystore.com/mcp` | | **Auth Header Name** | The header the server expects for authentication. Leave as `Authorization` unless the server's docs say otherwise. | `Authorization` | | **Auth Header Value**| The credential itself, in the format the server expects. | `Bearer sk_live_abc123` | ### Choosing How to Sign In: API Key or OAuth Your AI Connector supports two ways to authenticate with a server. Pick whichever the server's documentation tells you to use, using the **Authentication** option at the top of the form: - **API key / header:** the original method described above. You paste a fixed credential (an API key or token) into the **Auth Header Value** field, and Your AI Connector sends it on every request. Best for servers that hand you a long-lived key. - **OAuth (sign in):** for servers that ask you to log in instead of pasting a key. With OAuth there's no key to copy — you approve access by signing in, the same way "Sign in with Google" works on other sites. **To connect with OAuth:** 1. Choose **OAuth** as the authentication method. The Auth Header fields disappear, replaced by a **Connect** card — you won't need a key. 2. Fill in the **Name** and **Server URL**, then click **Save**. The server is added to your list, but shows as **not connected** for now. 3. Click **Connect** on the server. A secure sign-in window opens where you approve access. 4. Approve, and the window closes on its own. The server now shows as connected, and Your AI Connector loads its tools. That's it. Your AI Connector keeps the connection fresh automatically in the background, so you normally never have to touch it again. If a server ever drops the connection (for example, the sign-in expires or someone revokes it on the server's side), it shows as disconnected — just click **Reconnect** and sign in again. If the server can't be set up automatically when you click Connect, you'll be asked to paste a few details (a sign-in address and a client ID) that the server's own documentation provides, then Connect finishes the sign-in. ### Test the Connection Before saving, click **Test Connection**. Your AI Connector contacts the server and shows you the list of tools it offers. This is the quickest way to confirm your URL and key are correct — if the connection fails, you'll see the error message right there instead of finding out mid-conversation. When the test succeeds, click **Save**. Your server appears in the list with a green status dot and the number of tools it offers. ### Reading the Server List Each server in the list shows: - A **status dot** — green when the last connection worked, red when the last attempt failed (hover for the error), grey before the first successful connection. - The **server's address** and how many tools it currently offers. - An **on/off toggle** to quickly enable or disable the whole server without deleting it. Your AI Connector refreshes each server's tool list in the background about once a day, so new tools show up on their own. A slow or temporarily unreachable server never holds up a conversation — the bot simply uses the last known tool list, and falls back gracefully if a call can't get through. ### Choosing Which Tools the Bot Can Use A server often offers more tools than you want the bot to touch. You can turn individual tools on or off without disconnecting the whole server. 1. Click the **pencil (edit)** icon on the server in the list. 2. Scroll to the **Tools** section — every tool the server offers is listed, each with its own on/off switch. 3. Switch off any tool you don't want the bot to call, or use **Enable all** / **Disable all** to set them in one go. 4. Click **Save changes**. Only the tools you leave switched on are offered to the bot. A tool that's switched off is completely invisible to the bot — it can't call it, and it won't count toward the 40-tool limit. Two things worth knowing: - **New tools stay off until you turn them on.** Once you've curated a server's tools, any tool the server adds later arrives switched off, so nothing new becomes available to the bot until you decide to enable it. (Servers you've never curated keep all their tools on, exactly as before.) - **This is separate from the Agent choice below.** Here you decide which of a server's tools exist at all, account-wide; on the Agent you decide which servers that Agent can reach — and, if you want, narrow its tools further for just that Agent. ### Setting Execution Limits per Tool Next to each tool's on/off switch you'll find a **Limits** control. It opens the same execution limits you can set on a [custom function](custom-functions.md#execution-limits), applied to just that one tool — useful when a server's tool calls a paid third-party service, or when a tool should only ever run once per conversation. Everything here is optional; leave it empty and the tool behaves exactly as before. - **Read-only.** Some servers declare for each tool whether it only reads data. **Automatic (server setting)** trusts that declaration; you can override it either way — mark a tool **Read-only** when you know it never creates or changes anything (this lets the AI safely retry an interrupted reply instead of leaving the customer without an answer), or **Not read-only** when you don't trust the server's claim. - **Serve cached result on repeat calls.** When the AI calls the tool again with the same inputs, the previous result is reused (for up to 24 hours) instead of calling the server again. - **Max runs per conversation** and **max runs per time window** work exactly as on custom functions: successful runs only, and when a limit kicks in the AI is told why and answers with the information it already has — the customer is never left hanging. Test conversations are exempt. One honest note on trust: limits control whether and how often *we call* the server — they can't change what the server does internally once called. And overriding a third-party tool to Read-only is a stronger claim than on your own custom function, because it's someone else's code; only do it for tools you understand. --- ## Enabling a Server on an Agent Registering a server makes it available; you still choose which Agents can use it. 1. Open the [Agent](../ai-agents/ai-agents.md) and go to its **AI Abilities** tab. (For a campaign that still holds its own AI settings directly rather than through a separate Agent, the same list appears on that campaign's own **AI Abilities** step instead.) 2. Find the **MCP servers** section. 3. Toggle on each server you want this Agent's bot to be able to use. 4. Click **Save changes** — selections only apply once saved. You can enable up to **5 servers per Agent**. Only the servers you enable are available to that Agent's bot, which keeps the bot focused on the tools that are relevant. ### Choosing Which Tools an Agent Can Use Once a server is enabled on an Agent, you can also narrow **which of its tools** that particular Agent may call — handy when one Agent should only read data while another may also create records. 1. On the **AI Abilities** tab, under the enabled server, click the **"… tools enabled for this agent"** row to expand the tool list. 2. Switch off any tool this Agent shouldn't use, then click **Save changes**. Two rules keep this predictable: - **An Agent can only narrow, never widen.** Tools you switched off account-wide (on the MCP Servers page) don't appear here and can't be re-enabled for a single Agent. - **Agents inherit by default.** An Agent where you haven't touched the tool list simply follows the account-wide selection — including tools you enable there later. Once you narrow an Agent's list, new tools stay off for that Agent until you enable them. --- ## Ready-Made Example: Connect a Shopify Store Every Shopify store comes with a built-in MCP server — no app to install, no key to create. Shopify hosts it at the store's own web address with `/api/mcp` added to the end. What the bot gets from it: - **Product search** — find products by describing what the customer wants ("a warm running jacket under $100"), with live prices, variants, and stock. - **Product details** — full information on a specific product, including options and availability. - **Store policies and FAQs** — shipping, returns, refund, and privacy questions, answered from the store's own pages. - **Cart** — build a cart for the customer and hand them a checkout link. To connect one, add a server with: | Field | What to enter | |---|---| | **Name** | `Shopify Store` (or the store's name) | | **Server URL** | The store's web address plus `/api/mcp` — for example `https://mystore.com/api/mcp`. The store's technical address works too: `https://mystore.myshopify.com/api/mcp`. | | **Authentication** | Leave **API key / header** selected and leave the **Auth Header Value** empty — this server needs no key. | Save, click **Test Connection**, and enable the server on your agent — that's the entire setup. Two things to know: - **Orders are not on this server.** Shopify deliberately keeps order data off this public endpoint. For "where is my order?" questions, pair this server with one custom function — see the [Shopify order status example](custom-functions.md#complete-example-shopify-order-status). - **It works for any Shopify store** — including a client's store if you manage accounts for others. All you need is the store's web address. --- ## Security — Only Connect Servers You Trust An MCP server you connect can be called by your bot and can return text that the bot reads and acts on. Treat it like any other integration that holds a key to your systems: - **Only register servers you control or fully trust.** A tool's description is written by whoever runs the server, and the bot reads those descriptions to decide when to use a tool. - **Use a dedicated, limited API key**, not an admin credential. Your key is stored securely and never shown in data exports. The same applies to OAuth sign-ins — the access tokens are stored securely and redacted from any export. - **The URL must be a public `https://` address.** Internal, localhost, and private-network addresses are rejected for security. - **Disable a server the moment you stop trusting it** — toggle it off or delete it, and it's gone from every Agent immediately. --- ## Troubleshooting - **Red status dot / connection failed:** Re-open the server and click **Test Connection** to see the exact error. The most common causes are a wrong or expired key, a typo in the URL, or the server requiring a header name other than `Authorization`. - **An OAuth server stopped working / asks you to reconnect:** OAuth sign-ins can be revoked or expire on the server's side. Open the server and click **Connect** again to sign back in. Note that OAuth sign-ins are never copied between accounts, so a copied Agent or campaign's servers must be reconnected in the account you copied it into. - **The bot isn't using a tool:** First check the tool is switched on in the server's **Tools** section (edit the server to see the list) — a switched-off tool is invisible to the bot. Then make sure the server is enabled on that specific Agent, and that the customer's request clearly matches what the tool does. As with custom functions, clear tool names and descriptions on the server's side help the bot choose correctly. - **A tool the server offers isn't showing up for the bot:** If you've curated this server's tools, remember that any tool added after you curated arrives switched off. Edit the server, open the **Tools** section, and switch it on. - **Does the connector handle MCP HTTP sessions?** Yes. If your server issues an `mcp-session-id` header when the connection is established, we store it and send it back on every following request, along with the `MCP-Protocol-Version` header. Stateful servers work without any extra configuration on your side. - **A tool was skipped:** An Agent can use at most 5 servers and 40 MCP tools at once. If a server offers a very large number of tools, some may not be loaded — switch off the tools you don't need in the server's **Tools** section, or keep each server focused on the tools you actually use. --- ## Plan Requirements MCP servers are part of the developer toolset, alongside custom functions. If you don't see **MCP Servers** in the AI Studio section of the sidebar, your current plan doesn't include it — upgrade to a plan with developer tools to turn it on. --- ## Next Steps - [Custom Functions](custom-functions.md) — wire up a single tool by hand instead of connecting a whole server. - [AI Agents](../ai-agents/ai-agents.md) — where MCP servers get enabled for a bot. - [AI Agents](../ai-agents/ai-agents.md) — the main page of the AI Studio group MCP Servers lives in.