How to Connect Your Bot via MCP

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

Open the Playground for your bot.
Switch to the MCP tab.
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.
If you chose API Key mode: copy the API key immediately — it is shown only once.
Note the MCP endpoint URL shown on the page. It looks like:
```
https://app.chatbotiq.ai/v1/mcp/bots/<bot-id>/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

Open claude.ai or Claude Desktop.
Go to Customize (in the left sidebar) > Connectors.
Click +, then Add custom connector.
Enter the MCP endpoint URL from the ChatbotIQ Playground (e.g., https://app.chatbotiq.ai/v1/mcp/bots/<bot-id>/mcp).
Click Add.

For Team / Enterprise plans

Admin setup:

Go to Organization settings > Connectors.
Click Add, hover over Custom, select Web.
Enter the MCP endpoint URL.
Click Add.

Members then connect individually:

Go to Customize > Connectors.
Find the connector labeled Custom.
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:

claude mcp add --transport http chatbotiq-my-docs \
  https://app.chatbotiq.ai/v1/mcp/bots/<bot-id>/mcp \
  --header "Authorization: Bearer mcpk_your_api_key_here"

Public mode (no auth):

claude mcp add --transport http chatbotiq-my-docs \
  https://app.chatbotiq.ai/v1/mcp/bots/<bot-id>/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:

claude mcp list        # list configured servers
/mcp                   # check status inside a Claude Code session

Shared team config (.mcp.json in project root):

{
  "mcpServers": {
    "chatbotiq-my-docs": {
      "type": "http",
      "url": "https://app.chatbotiq.ai/v1/mcp/bots/<bot-id>/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

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
Run MCP: Add Server.
Select HTTP as the server type.
Enter a name (e.g., chatbotiq-my-docs) and the MCP endpoint URL.
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):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "chatbotiq-key",
      "description": "ChatbotIQ MCP API Key",
      "password": true
    }
  ],
  "servers": {
    "chatbotiq-my-docs": {
      "type": "http",
      "url": "https://app.chatbotiq.ai/v1/mcp/bots/<bot-id>/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):

{
  "servers": {
    "chatbotiq-my-docs": {
      "type": "http",
      "url": "https://app.chatbotiq.ai/v1/mcp/bots/<bot-id>/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

Open Settings: Cmd+, (macOS) / Ctrl+, (Windows/Linux).
Navigate to Tools & MCP.
Click Add new MCP server.
Set:
- Type: streamableHttp
- Name: chatbotiq-my-docs
- URL: your MCP endpoint URL
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:

{
  "mcpServers": {
    "chatbotiq-my-docs": {
      "type": "streamableHttp",
      "url": "https://app.chatbotiq.ai/v1/mcp/bots/<bot-id>/mcp",
      "headers": {
        "Authorization": "Bearer mcpk_your_api_key_here"
      }
    }
  }
}

Public mode (no auth):

{
  "mcpServers": {
    "chatbotiq-my-docs": {
      "url": "https://app.chatbotiq.ai/v1/mcp/bots/<bot-id>/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

Open Windsurf and click the Plugins icon in the sidebar.
Click Manage plugins > View raw config.
Add your ChatbotIQ server (see JSON format below).
Save and refresh.

Option B: Edit config file

Edit ~/.codeium/windsurf/mcp_config.json:

With API key:

{
  "mcpServers": {
    "chatbotiq-my-docs": {
      "serverUrl": "https://app.chatbotiq.ai/v1/mcp/bots/<bot-id>/mcp",
      "headers": {
        "Authorization": "Bearer mcpk_your_api_key_here"
      }
    }
  }
}

Public mode (no auth):

{
  "mcpServers": {
    "chatbotiq-my-docs": {
      "serverUrl": "https://app.chatbotiq.ai/v1/mcp/bots/<bot-id>/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).

Open ChatGPT Settings.
Go to Apps (or Connectors) > Advanced settings.
Toggle on Developer Mode.
Click Create to add a new connector.
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)
Click Create to save.
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.

If you want visitors to see available MCP tools in your embedded chat widget:

Enable MCP in Public mode (the widget toggle requires public mode).
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.ai. On paid plans, you can point it to your own domain (e.g., ai.yourcompany.com) so MCP clients see a branded URL.

Setup

Go to Settings → MCP Domain.
Enter your custom domain (e.g., ai.yourcompany.com).
In your DNS provider, create a CNAME record pointing your domain to the target shown in the settings (e.g., mcp.chatbotiq.eu).
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.
Once active, all MCP endpoint URLs for your bots automatically switch to https://ai.yourcompany.com/v1/mcp/bots/<bot-id>/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.

Bot Settings Reference — MCP settings
Build a Knowledge Bot for Confluence — tutorial using MCP

How to Connect Your Bot via MCP

Prerequisites

Step 1: Enable MCP on your bot

Step 2: Connect from your AI tool

Claude (claude.ai and Claude Desktop)

For Pro / Max plans

For Team / Enterprise plans

Using the connector

Claude Code (CLI)

GitHub Copilot (VS Code)

Option A: Command Palette

Option B: Edit config file

Cursor

Option A: Settings UI

Option B: Config file

Windsurf

Option A: Plugin UI

Option B: Edit config file

ChatGPT

Available MCP tools

Show MCP tools in the chat widget (optional)

Use a custom MCP domain

Setup

Troubleshooting

Related