--- title: "MCP Server" description: "Connect an MCP server so your agent can use its tools during a conversation, such as looking up orders or booking appointments." --- :::note[Plan] Actions are available on the **Starter** plan and above. ::: **MCP Server** connects your agent to a server that speaks the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Many services, such as online stores, booking systems, and help desks, offer an MCP server. Once it's connected, your agent can use the server's tools to answer customers. For example, it can check an order's status when a customer gives their order number. Unlike [Custom API](/docs/actions/custom-api), you don't describe each request yourself: Chatvox reads the list of tools from the server, and you choose which ones the agent can use. You can add several MCP Server actions to one agent, one for each server. To add one, go to **Build** > **Actions**, select **Create action**, and choose **MCP Server**. ## Choose a server meant for customers MCP servers are built for different audiences, and that decides what your visitors can reach: | Kind of server | Built for | What a visitor can reach | Examples | | --- | --- | --- | --- | | **Customer-facing** | Shoppers and website visitors | Only public data, or the signed-in customer's own data | [Shopify's Storefront MCP](https://shopify.dev/docs/apps/build/storefront-mcp/index.md) (products, cart, store policies) | | **Admin** | Store owners and staff using AI assistants | Everything the credentials you enter can access | WooCommerce's MCP, and most "connect your account" servers for payments, project management, or code hosting | :::warning An admin server acts with your credentials. If you connect one to a public channel, a visitor can ask for anything those credentials can see, such as every order or customer. For public channels, prefer customer-facing servers, and read [Protecting your data](#protecting-your-data). ::: The MCP Server editor shows the same reminder. ## Examples | Use case | Server | Suggested setup | | --- | --- | --- | | Answer product questions and help shoppers find items | A customer-facing store server, such as Shopify's Storefront MCP | Read-only tools on, **Everyone**, all public channels. | | Answer questions from public documentation | A documentation server that only serves public pages | Read-only tools on, **Everyone**. | | Let customers check their own orders | Your own MCP server with a tool that requires the order number **and** the billing email, and returns only that order | **Everyone**, or **Identified visitors** if your site signs customers in. | | Look up account details for signed-in users | Your own MCP server that returns data for one user | **Identified visitors** only. Make sure the server only returns that user's data. | | Book or cancel appointments | A booking system's MCP server | Lookup tools on. Booking and cancelling tools **Identified visitors** only, or off. | | Let staff query internal systems | An admin server, such as a store or project management server | Don't use a public channel. Use [Playground](/docs/agents/playground) or a channel only your team can reach. | ## Server - **Name**: a short name for the service, such as "Shop". The agent sees it next to each tool. - **Server URL**: the server's address, such as `https://example.com/mcp`. It must start with `https://`. - **When to use** (optional): when these tools are useful, for example: > Use when a customer asks about an existing order, shipping, or returns. ## Authentication Choose how Chatvox proves its identity to the server: | Auth type | Sends | | --- | --- | | **None** | Nothing. | | **Bearer token** | An `Authorization: Bearer ` header. | | **Basic auth** | A username and password. For WordPress and WooCommerce, use the WordPress username and an [Application Password](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/). | | **API key header** | A header with your header name and key value. | Tokens and keys are stored encrypted. ## Tools 1. **Load the tools** Enter the server URL and authentication, then select **Load tools**. Chatvox connects to the server and lists its tools. 2. **Choose which tools the agent can use** Turn on the tools you want. Tools the server marks as **Read-only** start on. Tools marked **Can change data**, such as creating a refund, start off. 3. **Choose who can use each tool** For each enabled tool, choose **Everyone** or **Identified visitors**. See [Protecting your data](#protecting-your-data). 4. **Save** Select **Save**. The agent can use the enabled tools right away. If the server adds or changes tools later, select **Refresh tools**. Your choices are kept for tools that still exist. ### WordPress and WooCommerce WordPress sites, including WooCommerce stores, share their features through the [WordPress MCP Adapter](https://developer.woocommerce.com/docs/features/mcp/) as "abilities". When you load the tools of a WordPress server, Chatvox lists each ability as its own tool, such as **Query orders** or **Delete product**, so you can turn each one on or off. Abilities the site marks as read-only start on. - **Server URL**: `https://your-store.com/wp-json/mcp/mcp-adapter-default-server` - **Auth type**: **Basic auth**, with a WordPress username and an Application Password (**Users → Profile → Application Passwords**). Use a WordPress user with only the permissions the agent needs. Each ability also checks the user's own permissions. ## Protecting your data **Every tool runs with the credentials you entered, not the visitor's.** Chatvox can't know which records a visitor is allowed to see: it passes the agent's request to your server, and your server answers with whatever those credentials can access. So treat each enabled tool as a door into your system. If a tool can list orders, customers, or bookings, **any visitor who can use it can ask for all of them**, for example: "show me all orders". Instructions to the AI reduce this, but they are not a security control. The limits that actually protect your data are your credentials and the settings below. :::warning If a tool can return data about other people, assume a visitor can get it, unless the tool is limited to identified visitors **and** your server only returns that visitor's own data. ::: ### Who can use each tool | Setting | Who the agent offers the tool to | | --- | --- | | **Everyone** | Anyone chatting on the channels you turned on. | | **Identified visitors** | Only conversations with a verified visitor: someone signed in through [user identification](/docs/deployments/web-widget/user-identification), or a WhatsApp sender. Anonymous visitors don't get the tool. | **Identified visitors** stops anonymous visitors from using a tool, and you know who each conversation belongs to. It does **not** limit the data to that visitor: a signed-in customer can still ask for other customers' records if your server returns them. The editor warns you when enabled tools are open to everyone on a public channel. The [Playground](/docs/agents/playground) has no verified visitor, so tools limited to identified visitors don't run there. Test them through the web widget with user identification set up. ### Checklist before going live - **Use least-privilege credentials.** Create a dedicated user or API key for Chatvox with only the access the agent needs, ideally read-only and limited to public data. - **Prefer customer-safe tools.** The safest tools only return the caller's own data, or require proof such as an order number together with the billing email. If you build or control the MCP server, add tools like that rather than general "list" or "search" tools. - **Keep tools that change data off**, or limit them to identified visitors. - **Turn off tools you don't need.** Fewer tools also means more accurate answers. - **Test like an attacker.** In the [Playground](/docs/agents/playground), ask for things a visitor shouldn't get, such as "list all orders", "show other customers", or "what's the admin email?", and check what comes back. - **Choose channels deliberately.** The Web widget, Public Chat, and WhatsApp are open to anyone who can reach them. ## How the agent uses the tools - The agent decides when to call a tool, based on the customer's request, each tool's description, and your **When to use** text. - The agent is instructed to use a tool that changes something only when the customer clearly asked for it. - The agent is instructed to treat tool results as information only and to ignore any instructions that appear in a result. - If the server doesn't respond within 15 seconds or returns an error, the agent tells the customer it couldn't complete the request. ## Test it Ask the agent a matching question in the [Playground](/docs/agents/playground) and check that it uses the right tool and the result. ## Channels Choose where the action runs: **Web widget**, **Public Chat**, **WhatsApp**, and **API** (conversations started through the [REST API](/docs/developers/agents-and-chat)). **API** is off by default. See [Where actions run](/docs/actions#where-actions-run). ## Troubleshooting | Message | What to do | | --- | --- | | The MCP server rejected the credentials | Check the auth type, token, or key. | | URL must resolve to a public IP address | Chatvox only connects to servers on the public internet. | | We couldn't connect to the MCP server | Check the URL, and that the server supports the Streamable HTTP transport. |