--- doc_version: "1.0.0" last_updated: "2026-07-14T15:00:57.718Z" title: "How to Connect Your Bot via MCP" description: "Set up your ChatbotIQ bot as an MCP server so AI tools like Claude Desktop, Claude Code, Cursor, Windsurf, and ChatGPT can search your knowledge base." keywords: [MCP, Model Context Protocol, Claude Desktop, Claude Code, Cursor, Windsurf, ChatGPT, AI tools, integration, ChatbotIQ] --- MCP (Model Context Protocol) is an open protocol that lets AI tools connect to external data sources. When you enable MCP on your ChatbotIQ bot, AI coding assistants and other MCP-compatible tools can search your knowledge base directly. This is especially useful for development teams, your coding assistant can look up internal documentation without leaving the IDE. --- ## Prerequisites - A ChatbotIQ bot with at least one indexed knowledge source. - A paid plan (Personal, Standard, or Business). MCP is not available on the Free tier. --- ## Step 1: Enable MCP on your bot 1. Open the **Playground** for your bot. 2. Switch to the **MCP** tab. 3. Choose how to enable MCP: - **Enable with API Key** - generates a secret key for authenticated access. Recommended for private knowledge bases. - **Enable Public** - no authentication required. Use this if you want anyone with the URL to query your bot's knowledge base. 4. If you chose API Key mode: copy the API key immediately - it is shown only once. 5. Note the **MCP endpoint URL** shown on the page. It looks like: ``` https://app.chatbotiq.eu/v1/mcp/bots//mcp ``` --- ## Step 2: Connect from your AI tool Use the instructions for your specific client below. In all cases, you will need: - **MCP endpoint URL** from the MCP tab in Playground - **API key** (if you enabled authenticated mode) The Playground shows ready-to-copy configuration snippets for each client under the **Client Configuration** section. --- ### Claude (claude.ai and Claude Desktop) Claude supports remote MCP servers via **Custom Connectors**. Connectors configured on claude.ai sync to the Claude Desktop app automatically. > **Important:** Custom Connectors support **authless (public)** and **OAuth** authentication only, Bearer token / API key auth is not supported. Use **Public mode** when enabling MCP on your ChatbotIQ bot for Claude. If you need API key authentication, use **Claude Code** instead (see below). #### For Pro / Max plans 1. Open [claude.ai](https://claude.ai) or Claude Desktop. 2. Go to **Customize** (in the left sidebar) > **Connectors**. 3. Click **+**, then **Add custom connector**. 4. Enter the **MCP endpoint URL** from the ChatbotIQ Playground (e.g., `https://app.chatbotiq.eu/v1/mcp/bots//mcp`). 5. Click **Add**. #### For Team / Enterprise plans **Admin setup:** 1. Go to **Organization settings** > **Connectors**. 2. Click **Add**, hover over **Custom**, select **Web**. 3. Enter the MCP endpoint URL. 4. Click **Add**. **Members** then connect individually: 1. Go to **Customize** > **Connectors**. 2. Find the connector labeled **Custom**. 3. Click **Connect**. #### Using the connector After setup, activate the connector per-conversation: click the **+** button in the chat input, select **Connectors**, and toggle your ChatbotIQ connector on. Claude can then search your knowledge base directly. --- ### Claude Code (CLI) Claude Code supports MCP servers via the `claude mcp add` command. **With API key:** ```bash claude mcp add --transport http chatbotiq-my-docs \ https://app.chatbotiq.eu/v1/mcp/bots//mcp \ --header "Authorization: Bearer mcpk_your_api_key_here" ``` **Public mode (no auth):** ```bash claude mcp add --transport http chatbotiq-my-docs \ https://app.chatbotiq.eu/v1/mcp/bots//mcp ``` **Scope options:** - `--scope local` (default) - available only in the current project, stored privately in `~/.claude.json`. - `--scope project` - shared with your team via `.mcp.json` in the project root (committed to git). - `--scope user` - available across all your projects. **Verify the connection:** ```bash claude mcp list # list configured servers /mcp # check status inside a Claude Code session ``` **Shared team config (`.mcp.json` in project root):** ```json { "mcpServers": { "chatbotiq-my-docs": { "type": "http", "url": "https://app.chatbotiq.eu/v1/mcp/bots//mcp", "headers": { "Authorization": "Bearer ${CHATBOTIQ_MCP_KEY}" } } } } ``` Team members set the `CHATBOTIQ_MCP_KEY` environment variable locally. Claude Code supports `${VAR}` and `${VAR:-default}` syntax in config values. --- ### GitHub Copilot (VS Code) GitHub Copilot supports MCP servers via a `.vscode/mcp.json` file in your project or a user-level config. #### Option A: Command Palette 1. Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`). 2. Run **MCP: Add Server**. 3. Select **HTTP** as the server type. 4. Enter a name (e.g., `chatbotiq-my-docs`) and the MCP endpoint URL. 5. VS Code will create or update `.vscode/mcp.json` for you. #### Option B: Edit config file Create or edit `.vscode/mcp.json` in your project root: **With API key (using input variables for secrets):** ```json { "inputs": [ { "type": "promptString", "id": "chatbotiq-key", "description": "ChatbotIQ MCP API Key", "password": true } ], "servers": { "chatbotiq-my-docs": { "type": "http", "url": "https://app.chatbotiq.eu/v1/mcp/bots//mcp", "headers": { "Authorization": "Bearer ${input:chatbotiq-key}" } } } } ``` VS Code will prompt you for the API key on first connection. The value is stored securely and not committed to git. **Public mode (no auth):** ```json { "servers": { "chatbotiq-my-docs": { "type": "http", "url": "https://app.chatbotiq.eu/v1/mcp/bots//mcp" } } } ``` > **Note:** VS Code tries HTTP Streamable transport first and falls back to SSE automatically. Avoid hardcoding API keys, use `${input:...}` variables instead. You will be asked to confirm trust for new MCP servers on first use. --- ### Cursor Cursor supports MCP via a JSON config file or the Settings UI. #### Option A: Settings UI 1. Open Settings: `Cmd+,` (macOS) / `Ctrl+,` (Windows/Linux). 2. Navigate to **Tools & MCP**. 3. Click **Add new MCP server**. 4. Set: - **Type**: `streamableHttp` - **Name**: `chatbotiq-my-docs` - **URL**: your MCP endpoint URL 5. **Fully restart Cursor** (not just reload window). #### Option B: Config file Create or edit `.cursor/mcp.json` in your project root (project-level) or `~/.cursor/mcp.json` (global): **With API key:** ```json { "mcpServers": { "chatbotiq-my-docs": { "type": "streamableHttp", "url": "https://app.chatbotiq.eu/v1/mcp/bots//mcp", "headers": { "Authorization": "Bearer mcpk_your_api_key_here" } } } } ``` **Public mode (no auth):** ```json { "mcpServers": { "chatbotiq-my-docs": { "url": "https://app.chatbotiq.eu/v1/mcp/bots//mcp" } } } ``` After saving, **fully restart Cursor**. Requires Cursor v0.40 or later. --- ### Windsurf Windsurf supports MCP via its plugin marketplace or manual config. #### Option A: Plugin UI 1. Open Windsurf and click the **Plugins** icon in the sidebar. 2. Click **Manage plugins** > **View raw config**. 3. Add your ChatbotIQ server (see JSON format below). 4. Save and refresh. #### Option B: Edit config file Edit `~/.codeium/windsurf/mcp_config.json`: **With API key:** ```json { "mcpServers": { "chatbotiq-my-docs": { "serverUrl": "https://app.chatbotiq.eu/v1/mcp/bots//mcp", "headers": { "Authorization": "Bearer mcpk_your_api_key_here" } } } } ``` **Public mode (no auth):** ```json { "mcpServers": { "chatbotiq-my-docs": { "serverUrl": "https://app.chatbotiq.eu/v1/mcp/bots//mcp" } } } ``` > **Note:** Windsurf uses `serverUrl` (not `url`) for remote MCP servers. --- ### ChatGPT ChatGPT supports remote MCP servers on Plus, Team, Enterprise, and Education plans. Only remote servers are supported (no local/stdio). 1. Open **ChatGPT Settings**. 2. Go to **Apps** (or **Connectors**) > **Advanced settings**. 3. Toggle on **Developer Mode**. 4. Click **Create** to add a new connector. 5. Fill in: - **Name**: a descriptive name (e.g., `ChatbotIQ Docs`) - **MCP Server URL**: your MCP endpoint URL - **Authentication**: choose **API Key** and enter `Bearer mcpk_your_api_key_here` (or **None** for public mode) 6. Click **Create** to save. 7. In a new conversation, click the **+** menu, select **Developer mode**, then enable your ChatbotIQ connector. ChatGPT will show a confirmation dialog before each tool call. --- ## Available MCP tools When connected, your AI tool can use these tools: | Tool | Description | |------|-------------| | **search_knowledge_base** | Semantic search across your bot's knowledge base. Returns relevant passages with source URLs and relevance scores. Supports optional `top_k` (max 20) and `source_id` filters. | | **list_sources** | List all knowledge sources attached to the bot, including source type, base URL, and page count. | | **get_page_content** | Retrieve the full markdown content of a specific page by its URL. | | **list_pages** | List pages in the knowledge base with pagination. Optionally filter by source. | --- ## Show MCP tools in the chat widget (optional) If you want visitors to see available MCP tools in your embedded chat widget: 1. Enable MCP in **Public mode** (the widget toggle requires public mode). 2. In the MCP tab, toggle **Show MCP Tools in Widget** to ON. This displays the available tools in the widget interface so users know what data the bot can access. --- ## Use a custom MCP domain By default, your MCP endpoint URL uses `app.chatbotiq.eu`. On paid plans, you can point it to your own domain (e.g., `ai.yourcompany.com`) so MCP clients see a branded URL. ### Setup 1. Go to **Settings** → **MCP Domain**. 2. Enter your custom domain (e.g., `ai.yourcompany.com`). 3. In your DNS provider, create a **CNAME record** pointing your domain to the target shown in the settings (e.g., `mcp.chatbotiq.eu`). 4. Click **Verify** to check DNS propagation. The status progresses through: - **Pending DNS** - waiting for your CNAME record to propagate. - **Pending SSL** - DNS verified, SSL certificate is being provisioned automatically. - **Active** - everything is working. Your MCP URLs now use your custom domain. 5. Once active, all MCP endpoint URLs for your bots automatically switch to `https://ai.yourcompany.com/v1/mcp/bots//mcp`. > **Note:** DNS propagation can take up to 48 hours, but usually completes within minutes. You can click Verify repeatedly to check. To remove a custom domain, go to the same settings page and clear the domain field. --- ## Troubleshooting - **Connection refused / timeout**: Verify the endpoint URL is correct and your bot has MCP enabled. - **401 Unauthorized**: Check that the API key is correct and prefixed with `Bearer ` in the Authorization header. - **403 Forbidden**: MCP may not be enabled on this bot, or the bot may be inactive. - **Tools not appearing**: Restart your client fully after adding the config. Some clients (Claude Desktop, Cursor) require a full restart, not just a window reload. - **Rate limited**: MCP endpoints are rate-limited per bot. Wait a moment and retry. - **Custom domain not working**: Check that DNS has propagated (`nslookup ai.yourcompany.com` should resolve). The domain status must be "Active" before URLs switch over. --- ## Related - [Bot Settings Reference](/reference/bot-settings/) - MCP settings - [Build a Knowledge Bot for Confluence](/tutorials/build-an-internal-knowledge-bot/) - tutorial using MCP ## Sitemap Full documentation index: [sitemap.md](/sitemap.md) and [llms.txt](/llms.txt).