←back to features

MCP SDK Integration

Connect agents to any MCP tool server without extra wiring - pass inline skillsets and abilities through the SDK to plug external tools straight into your agents.

ChatBotKit lets you connect agents to any MCP tool server directly in the conversation request. Instead of pre-provisioning integrations through the dashboard, you pass an extensions object with inline skillsets and abilities that use the mcp/install instruction template. The platform discovers the server's tools at runtime and makes them available to the agent.

This means any MCP-compatible server - GitHub, Notion, Slack, or your own - can be wired into an agent with a single complete() call. No upfront resource creation, no separate setup step.

Key Features

  • Inline MCP via extensions: Pass inline skillsets with abilities that reference an MCP server URL directly in the conversation request.
  • Dynamic tool discovery: The platform queries the MCP server at runtime to discover available tools and their parameters.
  • Secret-backed authentication: Reference a platform secret by ID to pass OAuth tokens or API keys to the MCP server securely.
  • Multi-server support: Add multiple inline skillsets to connect a single agent to several MCP servers in one request.
  • Streaming support: MCP tool calls stream through the same ResponsePromise.stream() pattern as all other conversation events.
  • Audit trail: Every MCP tool invocation is logged so you can trace what your agent did and why.

Getting Started

npm install @chatbotkit/sdk

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: process.env.CHATBOTKIT_API_SECRET,
})

const response = client.conversation.complete(null, {
  model: 'claude-sonnet-4-6',
  messages: [{ type: 'user', text: 'List my recent Notion pages' }],
  extensions: {
    skillsets: [
      {
        name: 'Notion Tools',
        description: 'Tools for managing Notion workspace via MCP',
        abilities: [
          {
            name: 'Load Notion Tools',
            description: 'Load MCP tools for Notion workspace management',
            instruction: [
              '```mcp/install',
              'url: https://mcp.notion.com/mcp',
              'prefix: notion',
              '```',
            ].join('\n'),
          },
        ],
      },
    ],
  },
})

for await (const event of response.stream()) {
  if (event.type === 'token') {
    process.stdout.write(event.data.token)
  }
}

The instruction field uses the mcp/install template format with the server URL and an optional prefix. For servers that require authentication, add a headers block with Authorization: ${SECRET_DEFAULT} and reference a platform secret via linkedSecretId. Browse the MCP Server Integration feature page to learn how to expose your own skillsets as MCP tools.

mcpsdkintegrationstoolsdevelopment