How to Connect Any MCP Server to Your AI Agent

The Model Context Protocol (MCP) is an open standard that lets AI agents discover and call tools exposed by external services. ChatBotKit supports MCP natively through its ability system, meaning you can connect your agent to any MCP-compatible server with just a URL and, optionally, a secret for authentication.

In this tutorial you will learn how to:

• Use pre-built MCP abilities from the ChatBotKit catalogue
• Provide a custom MCP server URL to dynamically load tools
• Handle authentication when an MCP server requires it
• Choose between shared and personal secret modes

Prerequisites

• A ChatBotKit account
• Basic familiarity with the Blueprint Designer
• An MCP server URL you want to connect (or use one of the pre-built options)

How MCP Works in ChatBotKit

When your agent calls an MCP ability, it triggers an mcp/install action that connects to the specified URL, discovers the available tools, and loads them into the conversation. From that point on the agent can call any of the discovered tools as if they were native abilities.

The instruction format for an MCP ability looks like this:

The url tells ChatBotKit where to find the MCP server, and the prefix namespaces the discovered tools so they don't collide with other abilities.

Step 1: Use a Pre-Built MCP Ability

ChatBotKit includes a growing catalogue of pre-configured MCP abilities for popular services like Notion, Linear, Stripe, Sentry, Slack, and many more.

1. Open the Blueprint Designer for your blueprint
2. Open your skillset and search for the service you want (e.g. "Load Notion Tools" or "Load Stripe Tools")
3. Add the ability to your skillset - it will automatically include the correct MCP URL and prefix
4. Associate the required secret when prompted

For example, the Load Notion Tools ability comes pre-configured with:

When the agent invokes this ability, it connects to the Notion MCP server, discovers available tools (creating pages, querying databases, managing blocks, etc.), and makes them available for the rest of the conversation.

Step 2: Connect a Custom MCP Server

If the MCP server you want to use is not in the catalogue, you can use the generic Install MCP ability (conversation/mcp/install[url]) to connect to any MCP-compatible endpoint.

1. In the Blueprint Designer, search for "Install MCP"
2. Add the ability to your skillset
3. Configure the URL parameter - you have two options:
   • Static URL: Set the MCP server URL directly in the Blueprint Designer as a fixed value. The agent will always connect to that specific server when the ability is invoked. This is the right choice when you know exactly which MCP server you want to use.
   • Dynamic URL: Leave the URL as a parameter that the agent fills in at runtime. This is useful when you want the agent to be able to connect to any MCP server on demand.

With a dynamic URL, you can tell your agent something like:

"Connect to the MCP server at https://mcp.myservice.com/mcp"

The agent will call the Install MCP ability with that URL, discover the available tools, and load them into the session.

With a static URL, the agent simply invokes the ability and the pre-configured server is connected automatically.

Step 3: Understand Authentication Modes

MCP servers often require authentication. ChatBotKit handles this through its secret system, and there are two distinct modes depending on who should be authenticating.

Without a Secret (On-the-Fly Authentication)

If you add an MCP ability without associating a secret, authentication is handled entirely on the fly. When the agent calls the MCP server and the server responds that authentication is required, the agent will prompt the contact (end user) to authenticate during the conversation. This is useful when:

• Each end user should authenticate with their own account
• The MCP server supports its own OAuth flow
• You want zero configuration on the ChatBotKit side

The authentication is memorized for the session or on a per-contact basis, so the user only needs to authenticate once. However, because there is no secret resource attached, there is no way for the contact to pre-authorize the connection before the conversation starts.

With a Shared Secret

When you associate a secret with kind: shared (the default), the credentials are provided by the bot owner and apply to all conversations. This means contacts can access the MCP tools directly without being prompted to authenticate.

This is the right choice when:

• You (the bot operator) own the API key or token
• All conversations should use the same credentials
• You want the MCP tools to be available immediately, with no authentication step for contacts

For example, if you add the Load Stripe Tools ability to your skillset, you will be asked to configure a secret. When you create that secret as a shared OAuth secret and complete the authorization, every conversation with the agent can use Stripe tools immediately - no authentication prompt for contacts.

Some pre-built MCP abilities use bearer tokens or API keys instead of OAuth. For example, the Load BetterStack Tools ability requires a shared API key. You create a bearer-type secret, paste your BetterStack API key, and attach it to the ability. The platform injects the key into the request headers automatically at runtime.

Note: Shared secrets are configured once by the bot owner and do not require any action from contacts.

With a Personal Secret

When you set the secret kind to personal, each contact must authenticate individually. The credentials are stored per contact, so different users talking to the same bot will each have their own authenticated session.

This is ideal when:

• Each user needs access to their own account (e.g. their own Notion workspace, their own Linear issues)
• You want per-user isolation
• The MCP server uses OAuth and each user should authorize separately

To set this up, create a secret and set its kind to personal. For example, when configuring the Load Notion Tools ability you can create a personal OAuth secret for Notion.

A key advantage of attaching a secret is that contacts can pre-authorize the connection before the conversation even starts. This is especially useful when building custom applications or when using ChatBotKit Portals, where a Connect application can be paired with the Chat application. The contact completes the OAuth flow once through the Connect interface, and every subsequent conversation can use the MCP tools immediately.

If the contact has not pre-authorized, authentication still happens on the fly: when the agent tries to load the MCP tools and the secret is not yet authorized for that contact, the agent will prompt them with an authentication link during the conversation. Once they complete the flow, the token is stored for that contact and reused automatically in future conversations.

Different contacts talking to the same bot will each authorize their own account, so they only see their own workspace data.

Step 4: Build a Complete MCP-Powered Agent

Let's put it all together by building an agent that uses MCP to interact with both Notion and Sentry.

1. In the Blueprint Designer, create a new blank blueprint with a bot and a skillset

2. Search for "Load Notion Tools" and add it to the skillset

3. Search for "Load Sentry Tools" and add it to the skillset

4. Configure the required secrets for both abilities:

   • For Notion: use the notion[mcp] OAuth secret
   • For Sentry: use the sentry[mcp] OAuth secret

5. Give the bot a backstory, for example:

   You are a development assistant. When the user asks about project management, load Notion tools. When they ask about errors or monitoring, load Sentry tools. Only load tools when needed.

6. Build the blueprint

Step 5: Test the Solution

1. Open the Chat interface from your blueprint
2. Ask the agent to interact with one of the connected services:
   • "Show me my recent Notion pages"
   • "Show me unresolved issues in Sentry"
3. If using a personal secret, the agent will prompt you to authenticate the first time
4. Once authenticated, the MCP tools are loaded and the agent can call them freely

Example prompts to try:

• "Connect to Notion and search for pages about onboarding"
• "Load Sentry tools and show me the most frequent errors this week"
• "What tools are available from the Stripe MCP server?"

Authentication Comparison

Troubleshooting

MCP tools are not loading

• Verify the MCP URL is correct and the server is online
• Ensure the URL uses the HTTP Streamable transport (SSE-only or stdio servers are not supported)
• Check that the secret is properly configured if the server requires authentication

Authentication prompt keeps appearing

• For personal secrets, ensure the OAuth flow completed successfully
• Check that the secret type matches what the MCP server expects (OAuth vs bearer vs plain)
• Verify the secret's resourceUrl matches the MCP server domain

Tools loaded but calls fail

• Check that the prefix does not conflict with other loaded abilities
• Verify the authenticated token has the required permissions/scopes
• Some MCP servers have rate limits - wait and try again

Next Steps

• Browse the full list of pre-built MCP abilities in the Blueprint Designer by searching for "MCP"
• Learn how to create a help bot for Slack that combines MCP tools with messaging integrations
• Explore the shell abilities tutorial to combine MCP with sandboxed code execution
• Read about building a reprogrammable AI agent for advanced agent patterns