Connect Textmagic to Claude: Sync Contacts, Send MMS & View Analytics

If you need to connect Textmagic to Claude to automate two-way SMS communication, manage contact lists, or orchestrate marketing campaigns, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Textmagic'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 ChatGPT, check out our guide on connecting Textmagic to ChatGPT or explore our broader architectural overview on connecting Textmagic to AI Agents.

Giving a Large Language Model (LLM) read and write access to an enterprise communication platform like Textmagic is an engineering challenge. You have to handle API authentication, map complex JSON schemas to MCP tool definitions, and deal with specific telecom API quirks. Every time the API updates, 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 Textmagic, connect it natively to Claude Desktop, and execute complex communication workflows using natural language.

The Engineering Reality of the Textmagic 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 telecommunication APIs is painful.

If you decide to build a custom MCP server for Textmagic, you own the entire API lifecycle. Here are the specific challenges you will face:

MMS and Attachment Statefulness Unlike basic REST endpoints where you POST a JSON body, sending an MMS in Textmagic requires a multi-step workflow. You cannot simply send an image URL in the message body. You must first upload the file via a dedicated attachment endpoint, which returns an ID or a shortcode link. Then, you must pass that specific reference into the message creation payload. LLMs struggle to infer these multi-step dependencies unless the MCP tool definitions explicitly instruct them on the sequence.

Strict Formatting and Data Types Telecom APIs are notoriously strict about phone number formatting. Textmagic expects numbers in international E.164 format. If an LLM hallucinates a local format or includes invalid characters (like parentheses or hyphens), the request will fail. Furthermore, list assignments and bulk updates often require comma-separated ID strings rather than standard JSON arrays, requiring your MCP server to translate the LLM's natural data structures into Textmagic's expected format.

Transparent Rate Limiting Textmagic enforces rate limits to prevent spam and platform abuse. It is critical to understand how a managed platform handles these limits. Truto does not retry, throttle, or apply backoff on rate limit errors. When Textmagic returns an HTTP 429 Too Many Requests error, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit data into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Your AI agent or framework is fully responsible for reading these headers and executing its own retry and exponential backoff logic.

Fragmented Pagination Models Textmagic uses specific pagination models across different endpoints. If you expose raw parameters like page and limit to Claude without guardrails, the model will frequently guess cursor values or misunderstand how to iterate through pages. Truto normalizes this across all endpoints into a standard limit and next_cursor schema, explicitly instructing the LLM to pass cursor values back unchanged.

How to Generate a Textmagic MCP Server with Truto

Truto dynamically generates MCP tools based on the documentation and schema definitions of the Textmagic API. You do not need to write custom integration code. You connect a Textmagic account, and Truto exposes its endpoints as a JSON-RPC 2.0 MCP server. You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

This is the fastest method for internal tooling or quick prototyping.

1. Log into your Truto dashboard.
2. Navigate to the Integrated Accounts page and select your connected Textmagic account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read methods, apply specific tags, or set an expiration date).
6. Click Create and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/abc123def456).

Method 2: Via the Truto API

For production use cases where you are provisioning MCP servers dynamically for your customers or automated deployment pipelines, use the REST API. This generates a secure token, stores it in a distributed edge key-value store, 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": "Textmagic Claude Server",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The API returns a payload containing the MCP server URL. This URL contains a cryptographic token that securely identifies the exact Textmagic account environment.

{
  "id": "mcp_01H...",
  "name": "Textmagic Claude Server",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6g7h8..."
}

How to Connect the Textmagic MCP Server to Claude

Once you have your Truto MCP server URL, you must configure Claude to use it. You can do this through the Claude application UI or by manually editing the configuration file.

Method A: Via the Claude UI (Desktop/Web)

If you are using Anthropic's hosted Claude application (or custom GPTs in ChatGPT), you can add the server directly via the interface.

1. Copy the MCP server URL from the Truto API or dashboard.
2. Open Claude and navigate to Settings -> Integrations -> Add MCP Server (or the equivalent Custom Connectors menu depending on your plan).
3. Paste the Truto MCP URL and click Add.
4. Claude will immediately handshake with the server, discover the available Textmagic tools, and make them available in your chat context.

Method B: Via Manual Config File

If you are running Claude Desktop and prefer to manage your connections via code, you can edit the claude_desktop_config.json file. Because Truto MCP URLs natively support Server-Sent Events (SSE), you will use the official @modelcontextprotocol/server-sse package as the transport layer.

Edit your configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

Restart Claude Desktop. The model will automatically connect, list the tools, and expose them to your AI agent.

Essential Textmagic MCP Tools for Claude

Truto automatically generates tools for every documented endpoint in the Textmagic API. By injecting specific descriptions, Truto teaches Claude exactly how to structure its requests. Here are the core hero tools you will use most often.

textmagic_contacts_search

Searching for contacts is the foundation of any targeted communication workflow. This tool allows Claude to query Textmagic contacts by phone number, list ID, tags, or free-text search strings. It returns complete contact profiles including custom fields and list memberships.

"Search Textmagic for a contact with the phone number +14155552671. If you find them, tell me their first name, company name, and what lists they currently belong to."

create_a_textmagic_message

This is the primary tool for dispatching SMS or MMS messages. Claude can send messages to individual phone numbers, contact IDs, or entire list IDs. It supports advanced parameters like scheduling (rrule), specifying the sender ID, and attaching MMS media links.

"Send a text message to contact ID 837492. The message should say: 'Hi there, your support ticket has been resolved. Please reply if you need anything else.' Use our default shared sender ID."

create_a_textmagic_mms_attachment

Because Textmagic requires attachments to be uploaded before sending, this tool is critical for rich media workflows. Claude uses this to upload a file (up to 10 MB, supporting formats like JPG, PNG, PDF, or CSV) to Textmagic. The tool returns an href or resource link that Claude can then embed into the create_a_textmagic_message payload.

"I need to send a product brochure. Upload this PDF to Textmagic as an MMS attachment. Once you have the attachment link, tell me the resource ID so we can draft a new message to our VIP list."

list_all_textmagic_stats_messagings

For operational oversight, your AI needs to monitor campaign health. This tool fetches messaging statistics grouped by day, month, or year. It returns granular data including delivery rates, reply rates, total costs, and exactly how many messages were accepted, buffered, or rejected.

"Pull the messaging statistics for the last 7 days. Summarize our overall delivery rate, our total spend, and tell me if we had any rejected messages."

list_all_textmagic_chats

Textmagic organizes two-way communication into chats. This tool allows Claude to list all active conversations, filtering by unread status, phone number, or specific assignees. This is vital for building an AI agent that acts as a triage assistant for inbound customer replies.

"Fetch the 5 most recent unread chats in Textmagic. For each chat, give me the phone number, the time of the last message, and the current status."

create_a_textmagic_list_contact

List management in Textmagic requires replacing the entire member set for a list. This tool assigns specified contacts to a list, overwriting the previous members. Claude can use this to bulk-assign segments based on campaign logic.

"Take these three contact IDs (104, 105, 106) and assign them to list ID 88. This should reset the list to only contain these three contacts."

To view the complete inventory of available endpoints and their exact JSON schema requirements, visit the Textmagic integration page.

Workflows in Action

MCP tools are powerful because they allow Claude to chain multiple API operations together autonomously. Here is how these tools behave in real-world scenarios.

Scenario 1: Support Inbox Triage and Reply

Support teams often need to find a specific user's conversation, review the context, and send an immediate response. Instead of manually navigating the Textmagic interface, an operator can ask Claude to handle it.

"Find the active chat for phone number +12125550198. Read the last message they sent, and then send a reply saying: 'We have received your request and our technical team is looking into it now. We will update you shortly.'"

How the agent executes this:

1. list_all_textmagic_by_phones: Claude calls this tool, passing the phone number to locate the specific chat ID and metadata.
2. list_all_textmagic_chat_messages: Claude queries the chat ID to retrieve the recent message history, reading the inbound text to understand the user's issue.
3. create_a_textmagic_message: Claude constructs the outbound reply, targeting the user's phone number, and dispatches the SMS.

sequenceDiagram
  participant User
  participant Claude as Claude Desktop
  participant Truto as Truto MCP Server
  participant Textmagic as Textmagic API

  User->>Claude: "Find chat for +12125550198 and reply..."
  Claude->>Truto: Call list_all_textmagic_by_phones
  Truto->>Textmagic: GET /api/v2/chats/by-phone
  Textmagic-->>Truto: Chat ID: 55432
  Truto-->>Claude: JSON-RPC result
  Claude->>Truto: Call list_all_textmagic_chat_messages (id: 55432)
  Truto->>Textmagic: GET /api/v2/chats/55432/messages
  Textmagic-->>Truto: Message history array
  Truto-->>Claude: JSON-RPC result
  Claude->>Truto: Call create_a_textmagic_message
  Truto->>Textmagic: POST /api/v2/messages
  Textmagic-->>Truto: 201 Created (Message ID)
  Truto-->>Claude: JSON-RPC result
  Claude-->>User: "Reply sent successfully."

Scenario 2: Marketing Campaign Execution

Marketing operations require coordinating media assets and distribution lists. An AI agent can orchestrate this entire flow, ensuring assets are uploaded before messages are sent.

"I want to run a promo to our VIP list (List ID: 402). First, upload this 'promo_banner.jpg' as an MMS attachment. Then, send a message to the VIP list saying 'Flash Sale! Use code VIP20 today.' Make sure the message includes the attachment link."

How the agent executes this:

1. create_a_textmagic_mms_attachment: Claude executes the upload process for the image file. Textmagic returns a resource payload containing a specific href URL for the media.
2. create_a_textmagic_message: Claude creates the outbound message payload. It sets the target to the VIP list ID, writes the text copy, and maps the href URL from the previous step into the attachment parameter. Textmagic processes the bulk send asynchronously.

Security and Access Control

Giving an AI agent write access to your communication infrastructure requires strict security guardrails. Truto MCP servers provide four layers of security configuration to ensure agents only do what they are authorized to do.

• Method Filtering (config.methods): You can restrict an MCP server to specific operation types. Setting methods: ["read"] ensures the agent can query contacts and read chats (list, get), but strictly blocks it from sending messages, updating lists, or deleting data (create, update, delete).
• Tag Filtering (config.tags): Integration resources in Truto are tagged by functional area. You can restrict an MCP server to only expose tools tagged with "reporting" or "contacts", hiding administrative tools entirely.
• Expiration (expires_at): You can assign a strict time-to-live (TTL) to an MCP server. Once the expires_at timestamp passes, the distributed edge store automatically drops the token, and any active scheduled alarms clean up the database records. This is ideal for granting a temporary agent access for a specific audit task.
• Dual Authentication (require_api_token_auth): By default, the cryptographically secure MCP URL is sufficient for connection. For zero-trust environments, you can enable require_api_token_auth: true. This forces the Claude client to pass a valid Truto API bearer token in the headers alongside the connection URL, ensuring only authenticated engineers can invoke the tools.

{
  "name": "Read-Only Analytics Agent",
  "config": {
    "methods": ["read"],
    "tags": ["analytics", "reporting"],
    "require_api_token_auth": true
  },
  "expires_at": "2026-12-31T23:59:59Z"
}

Moving Beyond Custom Code

Building a custom MCP server for Textmagic requires writing pagination logic, parsing messy API schemas, and maintaining infrastructure just to get a basic agent working. The telecommunications layer is constantly evolving, and your engineering team should not be responsible for tracking Textmagic's endpoint updates.

Using a managed MCP architecture dynamically translates Textmagic's documentation and resource schemas directly into AI-ready tools. You define the security boundaries, and the platform handles the protocol lifecycle. If Textmagic throws a 429 rate limit, the platform passes the standardized headers to your agent so it can intelligently back off.

Stop writing boilerplate integration code and start building agentic workflows.