Connect Botpress to Claude: Search Knowledge Bases & Manage Tables

If you need to connect Botpress to Claude to automate knowledge base retrieval, manage bot configurations, or query custom tables, you need a Model Context Protocol (MCP) server. This infrastructure layer translates Claude's natural language tool calls into structured Botpress REST API requests. You can either build and maintain this translation layer from scratch, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Botpress to ChatGPT or explore our broader architectural overview on connecting Botpress to AI Agents.

Giving a Large Language Model (LLM) read and write access to a chatbot ecosystem like Botpress introduces unique engineering challenges. Botpress is a highly structured environment where resources are split between administrative operations (like workspace management) and runtime operations (like chat execution). If you want an LLM to orchestrate these workflows autonomously, it needs precise schemas and strict parameter validation.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Botpress, connect it natively to Claude Desktop, and execute complex bot administration workflows using natural language.

The Engineering Reality of the Botpress API

A custom MCP server is a self-hosted integration layer that sits between your AI agent and the third-party platform. While the MCP standard provides an elegant, predictable way for models to discover tools, the reality of implementing it against vendor APIs is painful.

If you decide to build a custom MCP server for Botpress, you own the entire API lifecycle. You have to handle OAuth 2.0 or Personal Access Token (PAT) authentication. You have to map massive, nested JSON schemas to MCP tool definitions. Here are the specific challenges you will face with the Botpress API:

Polymorphic Chat Payloads The Botpress Chat API does not treat all messages equally. When sending a message, the payload structure depends entirely on a discriminator field. A text message requires a simple { "text": "hello" } object, but a choice message requires an array of options, and a location message requires specific geographic coordinates. If you expose a generic "send message" tool to Claude without strict validation, the model will frequently hallucinate payload structures, resulting in 400 Bad Request errors. A managed MCP server exposes these constraints as explicit JSON Schemas, guiding the LLM to format requests perfectly.

Dynamic Table Schemas Botpress allows you to create custom tables to store state, user preferences, or lead data natively within a workspace. Because these tables are dynamic, their column schemas are not statically defined in the standard Botpress OpenAPI spec. If you want Claude to insert a row into a Botpress table, the LLM first needs to know the table's specific schema. A robust integration architecture must provide tools for the agent to read the table schema dynamically before attempting to execute an upsert operation.

Split Resource Domains The Botpress ecosystem operates across distinct domains: the Admin API (managing workspaces, members, and integration installations) and the Chat API (managing users, conversations, and state). Mixing these up or passing an Admin-level ID to a Chat-level endpoint causes silent failures or opaque validation errors. Handling this manually in a custom MCP server requires writing complex middleware to route requests correctly.

Instead of building this infrastructure from scratch, you can use Truto. Truto normalizes authentication, pagination, and schema mapping, exposing Botpress endpoints as ready-to-use MCP tools that respect the exact shape of the underlying API.

How to Generate a Botpress MCP Server with Truto

Truto dynamically generates MCP servers based on the endpoints defined in a specific Botpress integration environment. These servers are scoped to a single integrated account, meaning the generated URL securely encodes the authentication context.

You can create a Botpress MCP server using either the Truto UI or the Truto API.

Method 1: Creating the Server via the Truto UI

For ad-hoc agent workflows, local development, or quick desktop usage, you can generate a server URL directly from the Truto dashboard.

1. Log in to your Truto dashboard and navigate to the Integrated Accounts section.
2. Select your connected Botpress account.
3. Click on the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (name, allowed methods, tags, and an optional expiry time).
6. Click Create and immediately copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123def456).

Method 2: Creating the Server via the Truto API

For production workflows - such as provisioning dedicated MCP servers dynamically for different departments or customer tenants - you can create the server programmatically.

Make a POST request to the /integrated-account/:id/mcp endpoint using your Truto API key. You can pass a config object to filter exactly which tools the LLM can access.

curl -X POST https://api.truto.one/integrated-account/<botpress_account_id>/mcp \
  -H "Authorization: Bearer <your_truto_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Botpress Knowledge & Tables MCP",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["files", "tables", "conversations"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API provisions the server and returns the secure URL:

{
  "id": "mcp_srv_98765",
  "name": "Botpress Knowledge & Tables MCP",
  "url": "https://api.truto.one/mcp/abc123def456",
  "expires_at": "2026-12-31T23:59:59Z"
}

How to Connect the Botpress MCP Server to Claude

Once you have the secure MCP URL, connecting it to an AI client takes seconds. Because the URL encodes the tenant and authentication state, the client does not need to handle OAuth exchanges or token headers (unless explicitly configured to do so).

Method 1: Connecting via the Claude Desktop UI

If you are using Claude Desktop (or another UI-based client like ChatGPT), you can add the connector directly in the application settings.

• For Claude Desktop: Navigate to Settings -> Integrations -> Add MCP Server. Paste the Truto MCP URL into the Server URL field, give it a name (e.g., "Botpress Tables"), and click Add. Claude will immediately handshake with the server and discover the available tools.
• For ChatGPT: Navigate to Settings -> Apps -> Advanced settings -> Developer mode. Under custom connectors, click Add new server, paste the Truto URL, and save.

Method 2: Connecting via Manual Configuration File (SSE)

For developers building headless agents, or configuring Claude Desktop manually via its configuration JSON, you can use the Server-Sent Events (SSE) transport. Truto supports this out of the box using the standard @modelcontextprotocol/server-sse package.

Locate your claude_desktop_config.json file (typically found at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the following entry:

{
  "mcpServers": {
    "botpress": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/abc123def456"
      ]
    }
  }
}

Restart Claude Desktop. The agent will read the config, initialize the SSE connection, and dynamically ingest the Botpress tools.

Hero Tools for Botpress Administration

Truto exposes dozens of Botpress endpoints as MCP tools. By passing specific tags during server creation, you can limit the agent's focus. Here are six high-leverage tools specifically focused on knowledge base search, table manipulation, and conversational control.

Search Indexed Knowledge Base Passages

Tool: botpress_files_search

This tool allows the LLM to search indexed Botpress files using natural language semantic search. This is incredibly powerful for RAG (Retrieval-Augmented Generation) workflows where the agent needs to fetch context before answering a question.

"Search the Botpress knowledge base for 'refund policy requirements' and summarize the top three passages returned in the context."

List Botpress Knowledge Bases

Tool: list_all_botpress_files_knowledge_bases

This tool retrieves all knowledge bases associated with a specific bot. Claude can use this to understand the organizational structure of files before deciding where to upload new documents or which tags to apply to specific query filters.

"List all the knowledge bases in this Botpress workspace. I need to find the ID of the knowledge base tagged with 'internal_hr'."

Discover Custom Tables

Tool: list_all_botpress_tables

Because Botpress tables are dynamic, an agent needs to discover what tables exist. This tool returns the table IDs, names, and their exact column schemas, which is a mandatory prerequisite before the agent can insert or update rows.

"List all custom tables in the workspace. Show me the exact schema and column names for the table called 'Customer Leads'."

Upsert Rows in a Custom Table

Tool: create_a_botpress_rows_upsert

This tool inserts new rows or updates existing ones based on a unique key. Once the LLM knows the schema (via the previous tool), it can autonomously map unstructured text into structured JSON and push it into the Botpress database.

"Using the schema you found for the 'Customer Leads' table, upsert a new row for John Doe (john@example.com). His lead status should be set to 'Qualified'."

Dispatch a Chat Message

Tool: create_a_botpress_chat_message

This tool creates a new message in a specific Botpress conversation. The LLM must adhere strictly to the payload schema (e.g., text, image, card) ensuring that the resulting message renders correctly in the user's chat window.

"Send a text message to conversation ID 'conv_123' thanking the user for their time, and include a follow-up markdown message with a list of the required documents we discussed."

Manage Chat Workflows

Tool: create_a_botpress_chat_workflow

This tool allows Claude to instantiate or trigger a new chat workflow for a user. Workflows control the state machine of a conversation, making this tool essential for programmatically advancing a user through a guided flow like a password reset or KYC check.

"Create a new chat workflow for user ID 'usr_999' linked to conversation 'conv_123'. Tag the workflow with 'manual_escalation' so the human support queue picks it up."

To view the complete schema definitions, required parameters, and the full list of available operations, visit the Botpress integration page.

Workflows in Action

Exposing individual tools is only the first step. The true power of an MCP server emerges when an LLM chains these tools together to execute multi-step workflows. Because the LLM maintains state across tool calls, it can read data in step one and use those outputs as inputs for step two.

Here are two concrete examples of how Claude navigates the Botpress API.

Example 1: Resolving a Complex Support Query via Knowledge Base Search

In this scenario, a human agent asks Claude to look up the answer to a highly specific customer question by searching the Botpress knowledge base, and then dispatching the correct response directly into the active chat session.

"Search the Botpress knowledge base for instructions on 'resetting a frozen biometric terminal'. Once you find the steps, format them clearly and send them as a message to conversation ID 'conv_884'."

Execution Sequence:

1. Search Data: Claude calls botpress_files_search with the query "resetting a frozen biometric terminal". Botpress returns a vector-ranked array of passages containing the technical manuals.
2. Synthesize: Claude reads the raw passages, strips out irrelevant data, and formulates a polite, easy-to-read Markdown response.
3. Dispatch Response: Claude calls create_a_botpress_chat_message passing the conversation_id and the formatted markdown payload.

sequenceDiagram
    participant Prompt as User Prompt
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant BP as Botpress API
    Prompt->>Claude: "Search KB for terminal reset..."
    Claude->>MCP: Call botpress_files_search
    MCP->>BP: POST /v1/files/search
    BP-->>MCP: Returns top vector passages
    MCP-->>Claude: JSON context
    Claude->>Claude: Synthesize response payload
    Claude->>MCP: Call create_a_botpress_chat_message
    MCP->>BP: POST /v1/chat/messages
    BP-->>MCP: Returns message ID
    MCP-->>Claude: Success confirmation

Example 2: Structuring Lead Data into a Dynamic Table

In this scenario, Claude is tasked with extracting information from unstructured notes and saving it to a custom lead tracking table inside the Botpress workspace.

"I just got off a call with Sarah Jenkins from Acme Corp. Her email is sarah@acme.com and she is interested in the Enterprise plan. Please find the 'Inbound Leads' table in Botpress and add her details to it."

Execution Sequence:

1. Schema Discovery: Claude calls list_all_botpress_tables to retrieve the tables in the workspace. It locates the table named "Inbound Leads" and inspects the schema array to identify the required column names (e.g., company_name, email_address, plan_interest).
2. Data Mapping: Claude maps the unstructured text from the prompt into the exact JSON schema expected by the table.
3. Data Insertion: Claude calls create_a_botpress_table_row passing the correct table_id and the formatted JSON row data.

flowchart TD
    A["User provides unstructured notes"] --> B["Claude calls list_all_botpress_tables"]
    B --> C["Botpress returns table schemas"]
    C --> D["Claude maps notes to 'Inbound Leads' schema"]
    D --> E["Claude calls create_a_botpress_table_row"]
    E --> F["Botpress API confirms row insertion"]

Security and Access Control

Giving an LLM access to your bot configuration and knowledge bases requires strict security boundaries. Truto's MCP servers support several layers of access control, configured at the token level during server creation:

• Method Filtering: Restrict the server to specific HTTP methods. By setting methods: ["read"], you guarantee the agent can only fetch knowledge bases and schemas, but cannot send messages, delete users, or modify tables.
• Tag Filtering: Limit access to specific resource groupings. Setting tags: ["tables"] ensures the agent only sees tools related to table operations, hiding the rest of the API surface area.
• Time-to-Live (TTL): Use the expires_at parameter to generate ephemeral servers. This is ideal for CI/CD pipelines or temporary contractor access, as the underlying KV store automatically destroys the credentials at the specified time.
• Secondary Authentication: By enabling require_api_token_auth, the client must provide a valid Truto API token in addition to possessing the MCP URL, preventing unauthorized usage if the URL is leaked in internal logs.

Handling Rate Limits in Botpress

The Botpress API enforces strict rate limits depending on your workspace plan and the specific endpoint being queried. Standard REST requests, file uploads, and vector searches all draw from different quota buckets.

It is important to understand that Truto does not retry, throttle, or apply backoff on rate limit errors.

When Botpress returns an HTTP 429 Too Many Requests error, Truto passes that error directly through to the calling agent. However, Truto does normalize the upstream rate limit data into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This standardization allows you (or your LLM framework) to reliably inspect the headers and implement appropriate exponential backoff and retry logic in your orchestration layer, rather than having requests fail silently or queue indefinitely in a black box.

Rethinking Botpress Administration

Integrating Botpress with Claude via a managed MCP server shifts the paradigm of chatbot management. Instead of building bespoke administrative dashboards, writing custom scripts to sync table data, or manually searching vector databases, you can expose the raw, structured capabilities of the Botpress API directly to an autonomous agent.

By leveraging Truto to handle the OAuth lifecycles, schema parsing, and protocol translation, your engineering team can focus on designing complex, multi-agent workflows rather than maintaining point-to-point API boilerplate.