Connect Superchat to ChatGPT: Search Contacts & Manage Conversations

If you need to connect Superchat to ChatGPT to automate multi-channel customer communications, search contact records, or manage conversation states across WhatsApp, SMS, and email, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's tool calls and Superchat's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses Claude, check out our guide on connecting Superchat to Claude or explore our broader architectural overview on connecting Superchat to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling multi-channel inbox like Superchat is a strict engineering challenge. You have to handle OAuth 2.0 token lifecycles, map nested JSON schemas to MCP tool definitions, and deal with Superchat's specific rate limits. Every time an endpoint updates or a field is deprecated, you have to update your server code, redeploy, and test the integration. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Superchat, connect it natively to ChatGPT, and execute complex workflows using natural language.

The Engineering Reality of the Superchat API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Superchat's APIs is painful. You aren't just integrating a simple messaging app - you are integrating an omni-channel routing engine with complex state machines for conversations, temporary file access, and strict contact definitions.

If you decide to build a custom MCP server for Superchat, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with Superchat:

The Handles and Custom Attributes Maze Superchat contacts are not flat database rows. A contact relies heavily on a handles array (which contains their specific identifiers for WhatsApp, SMS, or Email) and custom_attributes. If an LLM tries to create a contact without passing a properly formatted handles object, the Superchat API will return an error. Your MCP server needs dynamic schema validation to ensure the LLM understands exactly which handle types are required before it executes the tool call.

Ephemeral File Links Exporting a conversation or retrieving a file attachment in Superchat does not return a generic binary stream. Instead, the API returns a link.url paired with a link.valid_until timestamp. If an AI agent attempts to read a file, it must process that temporary link immediately before it expires. If your MCP server doesn't expose these temporal constraints to the LLM via its tool descriptions, the model will hallucinate persistent access and fail on subsequent operations.

Rate Limits and Standardized Passthrough Superchat enforces strict rate limits on conversation retrieval and message sending. A critical architectural truth: Truto does not retry, throttle, or apply backoff on rate limit errors. When the Superchat upstream API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (your AI agent orchestrator or ChatGPT client) is entirely responsible for reading these headers and implementing its own retry or exponential backoff logic.

Generating the Superchat MCP Server

Instead of writing custom JSON-RPC handlers and OAuth flows, Truto dynamically generates your MCP server using Superchat's API documentation. The tool generation is documentation-driven - Truto derives the available tools from the integration's resource endpoints and human-readable schema descriptions.

You can generate an MCP server for Superchat via the Truto UI or programmatically via the API. Both methods yield a secure URL containing a cryptographic token that authenticates the client and scopes the available tools.

Method 1: Via the Truto UI

For quick testing or internal deployment, you can generate the server directly from the dashboard.

1. Navigate to the integrated account page for your connected Superchat instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select the desired configuration (e.g., allowed methods like read or write, specific tags).
5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123def456...).

Method 2: Via the Truto API

For production workflows, you can programmatically provision MCP servers for your end users. The API validates the configuration, stores the token in distributed storage, and returns a ready-to-use URL.

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": "Superchat Automation Agent",
    "config": {
      "methods": ["read", "write", "custom"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response contains the secure URL you will pass to your client:

{
  "id": "mcp_8a9b0c",
  "name": "Superchat Automation Agent",
  "url": "https://api.truto.one/mcp/abc123def456..."
}

Connecting the MCP Server to ChatGPT

Once you have your Truto MCP URL, you need to register it with your client. ChatGPT acts as the orchestrator, reading the JSON Schema definitions exposed by Truto to understand how to format its API calls.

Method A: Via the ChatGPT UI

If you are using ChatGPT Plus, Team, or Enterprise, you can connect the remote server directly via the interface.

1. Open ChatGPT and navigate to Settings -> Apps -> Advanced settings.
2. Enable Developer mode (this makes the MCP features visible).
3. Under the custom connectors section, click Add a new server.
4. Enter a name (e.g., "Superchat Ops").
5. Paste your Truto MCP URL into the Server URL field.
6. Save the configuration.

ChatGPT will immediately send an initialize JSON-RPC request to the URL, discover the Superchat tools, and make them available in your chat window.

Method B: Via Manual Config File

If you are running a custom AI agent framework or a desktop client that uses standard MCP configuration files (like Cursor or Claude Desktop), you can connect the server using a Server-Sent Events (SSE) transport wrapper. Add this to your mcp_config.json:

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

High-Leverage Superchat Tools for ChatGPT

Truto exposes Superchat endpoints as explicitly named, snake_case tools. The schemas dictate exactly which query parameters and body arguments the LLM must provide. Here are the most powerful tools available for Superchat automation.

list_all_superchat_search_contacts

Standard list endpoints are useful, but searching is essential for agentic behavior. This tool allows the LLM to search the Superchat workspace by specific fields like mail or phone using specific operators. It returns the contact ID, which is a prerequisite for fetching their specific conversations.

"Search Superchat for a contact with the email address billing@example.com. If you find them, tell me their internal contact ID and return any custom attributes attached to their profile."

create_a_superchat_contact

This tool registers a new contact in the Superchat CRM. The LLM must construct a strict handles array (e.g., specifying the channel type and value like a phone number or email address) to ensure the contact can actually receive messages.

"Create a new Superchat contact for Jane Doe. Her email is jane.doe@acmecorp.com and her phone number is +15550198. Add a custom attribute indicating she is a 'VIP Customer'."

get_single_superchat_conversation_by_id

Conversations are the core state unit in Superchat. This tool retrieves the full context of a thread, including its status (open, closed, snoozed), assigned users, labels, and the specific inbox routing. AI agents use this tool to determine the context before drafting a reply.

"Fetch the details for conversation ID 'conv_889900'. Tell me what channel this conversation is taking place on (WhatsApp or Webchat) and list all the internal users currently assigned to it."

create_a_superchat_message

This is the execution engine. This tool allows the LLM to send an outbound message. It requires the from channel ID, the to recipient ID, and the message content. For threaded replies, the LLM must also supply the in_reply_to parameter.

"Send a message to contact ID 'cont_12345' using our primary WhatsApp channel. The message should say: 'Hello! We have received your refund request and our team is reviewing it now.'"

update_a_superchat_conversation_by_id

Support workflows require updating state, not just sending text. This tool allows the agent to change a conversation's status, apply labels (like 'urgent' or 'billing'), assign different team members, or set a snoozed_until timestamp.

"Update conversation ID 'conv_889900'. Change its status to 'snoozed', set the snoozed_until timestamp for 24 hours from now, and add the label 'awaiting-customer-reply'."

get_single_superchat_file_by_id

When a customer uploads an image or PDF via WhatsApp, Superchat stores it as a file record. This tool retrieves the file metadata and, critically, the temporary link.url and link.valid_until timestamp so the agent can subsequently download and parse the attachment.

"Look up file ID 'file_776655'. Check its mime type. If it is a PDF, extract the temporary download URL and tell me exactly when that link expires."

To view the complete schema definitions, pagination parameters, and the full list of available tools, review the Superchat integration page.

Workflows in Action

Individual tools are useful, but the real power of an MCP server emerges when an LLM orchestrates multiple API calls sequentially to resolve complex workflows. Here is how specialized AI personas use the Superchat MCP server in production.

Scenario 1: The Support Triage Agent

In a high-volume omni-channel support environment, stale conversations clog up the inbox. An AI agent can periodically audit the queue and automate follow-ups.

"Find the conversation with ID 'conv_33445'. If the status is open and it has been more than 48 hours since the last message, send a polite follow-up asking if they still need help. If you send the message, update the conversation status to snoozed for another 24 hours."

Execution Steps:

1. The agent calls get_single_superchat_conversation_by_id to check the current status and extract the channel/recipient details.
2. Seeing the conversation is stale, the agent calls create_a_superchat_message with the extracted channel routing data to send the follow-up text.
3. The agent calls update_a_superchat_conversation_by_id to transition the state to snoozed and sets the snoozed_until timestamp.

Result: The customer receives a native WhatsApp follow-up, and the conversation is cleared from the active human agent queue until tomorrow.

Scenario 2: The VIP Sales Outreach Assistant

Sales teams need to rapidly transition high-intent prospects from email to direct messaging. The AI agent acts as the bridge between systems.

"Search Superchat for a contact with the email 'cto@enterprise.com'. If they exist, check if they have a WhatsApp handle on file. If they do, send them a message from our outbound sales channel introducing our new enterprise tier."

Execution Steps:

1. The agent calls list_all_superchat_search_contacts passing field=mail, operator=equals, and value=cto@enterprise.com.
2. The agent parses the returned handles array to verify the existence of a valid WhatsApp identifier.
3. The agent calls create_a_superchat_message using the designated sales channel ID to dispatch the customized introduction.

Result: The LLM successfully executes multi-step conditional logic without human intervention, ensuring messages only route to valid, verified handles.

Security and Access Control

Giving an LLM access to your live customer communications requires strict security guardrails. Truto's MCP architecture enforces security at the token level, ensuring the client only has access to the exact operations it needs.

• Method Filtering: When creating the MCP server, you can restrict the token to specific operation types. Setting config.methods: ["read"] ensures the LLM can only search contacts and read conversations, physically preventing it from creating messages or altering state.
• Tag Filtering: Integration endpoints are grouped by functional tags. You can pass config.tags: ["contacts"] to generate a server that only exposes directory tools, completely isolating the messaging infrastructure.
• Extra Authentication Layer: By default, possessing the MCP URL is enough to connect. For high-security environments, setting require_api_token_auth: true forces the client to also provide a valid Truto API token in the Authorization header, adding identity verification to the connection.
• Ephemeral Access: Setting an expires_at timestamp creates a self-destructing server. Once the timestamp passes, the underlying distributed storage automatically drops the token, immediately severing the AI agent's access to the API.

Building custom MCP servers for omni-channel platforms like Superchat is an infrastructure trap. Managing the quirks of the handles array, handling temporary file links, and writing exponential backoff logic for HTTP 429s drains engineering resources. By using Truto's dynamically generated MCP servers, you offload the API lifecycle entirely. Your AI agents get immediate, curated access to Superchat's data, backed by standardized rate limit headers and strict token-level security.