Connect Botpress to ChatGPT: Manage bots, workspaces, and analytics

You want to connect Botpress to ChatGPT so your AI agents can read bot logs, orchestrate workspace billing, analyze engagement metrics, and inject real-time conversational data into your workflows. If your team uses Claude, check out our guide on connecting Botpress to Claude or explore our broader architectural overview on connecting Botpress to AI Agents.

Giving a Large Language Model (LLM) read and write access to your Botpress infrastructure is an engineering challenge. Botpress is a complex orchestration engine in its own right. Exposing its configuration APIs, analytics endpoints, and polymorphic messaging structures to an AI model requires building a translation layer.

You either spend weeks building, hosting, and maintaining a custom Model Context Protocol (MCP) server, mapping massive JSON schemas for every Botpress resource, or you use a managed infrastructure layer to handle the boilerplate for you. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Botpress, connect it natively to ChatGPT, 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 translates an LLM's generic tool calls into strict REST API requests. While the open MCP standard provides a 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.

Here are the specific integration challenges that break standard CRUD assumptions when working with the Botpress API:

Polymorphic Message Payloads

Sending a message in Botpress is not as simple as passing a text string to a generic endpoint. The Botpress message payload is highly polymorphic, utilizing a strict type discriminator. An LLM must format the JSON body completely differently depending on whether it is sending text, markdown, an image, a card, a carousel, or a location. If your MCP server does not expose these deeply nested, conditional JSON schemas accurately, ChatGPT will hallucinate the payload structure and fail validation.

Asynchronous File Indexing

When you interact with the Botpress Knowledge Base, uploading or modifying a file passage (botpress_file_passages_bulk_update) does not happen synchronously. The endpoint returns immediately with the file status set to indexing_pending. The indexing completes asynchronously, transitioning to indexing_completed or indexing_failed. Your AI agent needs to be aware of this state machine. If your custom server assumes immediate consistency, the LLM will try to query the knowledge base before the vectors are built, resulting in empty responses and confusing workflow failures.

Granular Workspace Usage Aggregation

Retrieving analytics and usage metrics requires aggregating data across multiple dimensions. The API separates bot analytics from workspace-level usage (e.g., invocation_calls, ai_spend, bot_count). Querying this requires providing strict date parameters (startDate, endDate) and knowing exactly which usage type to request. Mapping these distinct endpoints into unified tools that an LLM can easily reason about requires substantial schema engineering.

Rate Limits and the 429 Reality

Botpress strictly enforces rate limits on its admin and chat endpoints to protect platform stability. If an AI agent attempts to iterate over hundreds of bot logs or paginate through thousands of table rows too quickly, it will hit an HTTP 429 Too Many Requests response.

It is critical to understand how managed infrastructure handles this: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Botpress API returns HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Your AI agent or MCP client is fully responsible for reading these headers and implementing its own retry or exponential backoff logic.

How to Generate a Managed MCP Server for Botpress

Instead of building this infrastructure from scratch, you can use Truto to dynamically generate an MCP server mapped directly to your connected Botpress account. Truto handles the OAuth authentication lifecycle, schema generation, and JSON-RPC translation automatically.

There are two ways to generate a Botpress MCP server in Truto: via the UI, or programmatically via the API.

Method 1: Via the Truto UI

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected Botpress integration.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (Name, allowed methods, specific tags, and optional expiration).
6. Click Create and immediately copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123def456...).

Method 2: Via the Truto API

For platform engineers who want to automate server generation for their users, you can provision an MCP server via a simple POST request to the Truto API.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Botpress Analytics & Admin MCP",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["analytics", "bots", "workspaces"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API will securely generate a unique hash and return the ready-to-use URL:

{
  "id": "mcp_srv_987654",
  "name": "Botpress Analytics & Admin MCP",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8...",
  "expires_at": "2026-12-31T23:59:59Z"
}

How to Connect the MCP Server to ChatGPT

Once you have your Truto MCP server URL, connecting it to ChatGPT takes less than a minute. You can do this via the ChatGPT UI for immediate conversational access, or via a manual configuration file for programmatic dev environments.

Option A: Via the ChatGPT UI

1. Open ChatGPT and navigate to Settings.
2. Click on Apps, then select Advanced settings.
3. Toggle on Developer mode (MCP support requires this feature flag).
4. Under the MCP servers / Custom connectors section, click Add new server.
5. Enter a Name (e.g., "Botpress Admin").
6. Paste the Truto MCP URL into the Server URL field.
7. Click Save.

ChatGPT will perform an initialization handshake, download the Botpress tool schemas, and immediately make them available to your agent.

Option B: Via Manual Config File (Claude Desktop Parity)

If you are running local agents, custom frontends, or matching the Claude Desktop configuration pattern for a unified local environment, you can configure your MCP client using a standard JSON setup. You will use the official Server-Sent Events (SSE) proxy command.

Add the following to your MCP client configuration file:

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

Restart your client, and the Botpress tools will be registered over the SSE transport layer.

Hero Tools for Botpress Automation

Truto dynamically generates specific, schema-validated tools for every Botpress endpoint. Here are the highest-leverage tools available for your AI agents to manage Botpress infrastructure.

botpress_admin_bots_get_logs

Retrieve real-time and historical execution logs for a specific bot. This is critical for AI agents acting as DevOps assistants to debug conversation failures, routing errors, or workflow crashes.

"Fetch the error logs for bot ID bot-7781 over the last 2 hours. Identify any recurring workflow failures and summarize the error messages."

botpress_files_search

Perform natural language semantic searches across indexed Botpress files. The LLM can pass a query string, and the endpoint returns matching text passages with scores and context. This effectively allows ChatGPT to query the bot's internal knowledge base.

"Search the Botpress knowledge base for 'refund policy processing times' and extract the specific passage that mentions SLA requirements."

list_all_botpress_bot_analytics

Retrieve performance metrics and analytics for a specific bot over a defined date range. This tool allows the LLM to build executive summaries on bot performance, message volume, and user engagement.

"Get the bot analytics for bot ID bot-9912 from October 1st to October 7th. Create a table comparing daily active users and total conversation length."

list_all_botpress_workspace_usages

List usage metrics for the current workspace. You can specify the usage type (like invocation_calls or ai_spend) and retrieve the exact quota consumption data, allowing agents to monitor billing proactively.

"Check the workspace usage for 'ai_spend' and 'invocation_calls'. Alert me if we have crossed 80% of our monthly quota."

create_a_botpress_message

Create a new message in Botpress by sending a typed payload to a conversation webhook. This tool supports all of Botpress's polymorphic payload types (text, markdown, card, carousel) and handles the strict validation required by the type discriminator.

"Send a markdown formatted message to conversation ID conv-551 that says 'Your support ticket has been escalated. An agent will review the logs shortly.'"

botpress_tables_get_or_create

Get an existing custom table or create a new one based on a provided schema. Botpress tables act as an internal database for bots. LLMs can use this tool to dynamically provision storage for lead capture, feedback surveys, or user preferences.

"Check if the 'customer_feedback' table exists. If it doesn't, create it with a schema containing columns for 'user_id', 'rating', and 'comments'."

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

Workflows in Action

Exposing Botpress to ChatGPT allows you to automate complex, multi-step orchestration workflows using pure natural language. Here is how specific personas use these capabilities in production.

Scenario 1: Automated Bot Debugging and Log Triage

Persona: Support Engineer / Bot Developer

When a bot starts hallucinating or dropping user interactions, developers usually have to dig through raw JSON logs manually. With an MCP-enabled agent, this process becomes conversational.

"Users are complaining that the e-commerce bot is failing to process returns. Fetch the logs for bot bot-ret-99 for the last 6 hours, filter for errors, and tell me which workflow ID is crashing."

How the agent executes this:

1. Calls botpress_admin_bots_get_logs passing bot_id: "bot-ret-99", timeStart: " [Timestamp 6 hours ago]", and filtering by level: "error".
2. The LLM ingests the returned array of log objects.
3. The LLM parses the workflowId and message fields from the logs, identifies the stack trace pointing to a malformed API call in the return workflow, and formats a human-readable summary for the engineer.

sequenceDiagram
    participant Dev as Support Engineer
    participant LLM as ChatGPT
    participant MCP as Truto MCP Server
    participant Upstream as Upstream API (Botpress)
    
    Dev->>LLM: "Fetch errors for bot-ret-99..."
    LLM->>MCP: Call botpress_admin_bots_get_logs
    MCP->>Upstream: GET /v1/admin/bots/bot-ret-99/logs
    Upstream-->>MCP: 200 OK (Logs Array)
    MCP-->>LLM: JSON-RPC Result (Logs Data)
    LLM->>Dev: "Workflow 'Process_Return' is failing due to a null reference exception."

Scenario 2: Conversational Usage Monitoring and Alerting

Persona: Operations Manager / IT Admin

Managing API spend and LLM invocation costs across multiple workspaces is tedious. Operations teams can use ChatGPT as an active monitoring agent.

"Check our AI spend and invocation calls for the 'Enterprise Support' workspace over the last 30 days. If the AI spend exceeds $500, list all the bots in this workspace so we can see which one is consuming the budget."

How the agent executes this:

1. Calls list_all_botpress_workspace_usages with type: "ai_spend" and the target workspace_id.
2. Calls list_all_botpress_workspace_usages again with type: "invocation_calls".
3. The LLM evaluates the returned numeric values. If the AI spend > 500, it proceeds to the next step.
4. Calls list_all_botpress_admin_bots to retrieve the roster of active bots in the environment.
5. The agent correlates the data and provides the operations manager with a unified report of spend versus active deployments.

Security and Access Control

Giving an LLM access to your administrative Botpress environment requires strict governance. Truto MCP servers provide foundational security controls to ensure models only interact with approved systems in approved ways:

• Method Filtering: Enforce read-only access by configuring the MCP server with methods: ["read", "list"]. This prevents the LLM from accidentally executing state-changing operations like deleting bots or modifying workspace billing.
• Tag Filtering: Restrict the server to specific functional domains. Setting tags: ["analytics"] ensures the LLM can only view usage data and cannot access conversation payloads or user identities.
• Enforced Expiration (expires_at): For temporary workflows - like giving a contractor agent access to debug a specific bot - set an exact ISO datetime for the MCP URL to self-destruct.
• Two-Layer Authentication (require_api_token_auth): Enable this flag to require clients to pass a valid API token in addition to the server URL. This ensures that even if an MCP URL is leaked in a configuration file, it cannot be utilized without secondary authentication.

Stop Hardcoding Integration Logic

Building a reliable bridge between ChatGPT and Botpress does not mean you have to write manual pagination logic, implement exponential backoffs for 429 errors, or update complex JSON schemas every time Botpress releases a new payload discriminator.

By leveraging Truto to auto-generate a secure, spec-compliant MCP server, you eliminate the integration boilerplate. Your engineering team can focus on orchestrating high-value AI workflows, while the underlying protocol translation is handled automatically.