TrueDialog MCP

MCP, the Model Context Protocol, is how an AI client reaches the tools and data it needs to actually do something. tdmcp is the plumbing between any MCP-speaking client and the TrueDialog SMS API: thirty years of carrier infrastructure, opt-out handling, two-way conversations, RCS, MMS, and short-code traffic, exposed as a small set of well-named tools.

Authentication is OAuth 2.1, not pasted credentials. You authorize once, in your browser, against auth.tdmcp.com — signing in with the same TrueDialog login you use for the portal. Your AI client only ever holds a short-lived bearer token, never your password, and sends it on each call. The connector validates the token and resolves your TrueDialog access server-side over a private back-channel. Nothing long-lived lands in your client config.

The runtime is unremarkable on purpose: Azure Container Apps behind a managed front-door, AMD64 containers, FastMCP serving Streamable HTTP, no sticky sessions. Terraform for the lot. Nothing surprising, nothing in the hot path that you didn't put there.

---

Endpoint: https://connect.tdmcp.com. Streamable HTTP, stateless. The same transport also answers at https://connect.tdmcp.com/mcp — a compatibility alias for clients that assume the /mcp path convention; either URL works. Authentication is OAuth 2.1 — your client discovers it automatically and walks you through a browser sign-in. There are no keys or headers to paste.

How authorization works

Every client below follows the same four steps, and most of it happens for you:

1. You add connect.tdmcp.com to your client.
2. The client finds the OAuth server at auth.tdmcp.com and registers itself automatically (dynamic client registration, PKCE).
3. A browser window opens. You sign in with your TrueDialog credentials.
4. Your client receives a token and you're connected. It refreshes on its own — you won't sign in again until the session expires.

In Claude (Desktop app or claude.ai), open Customize → Connectors and click + → Add custom connector. Give it a name and the endpoint URL:

add custom connector

Name:   TrueDialog
URL:    https://connect.tdmcp.com/

Click Add, then Connect. A browser window opens for the TrueDialog sign-in; approve it and the nine tools appear — Claude registers itself with the OAuth server automatically, nothing to paste. On Team/Enterprise an Owner has to enable it for the org first (Organization settings → Connectors → Add → Custom → Web); after that each member adds it from Customize → Connectors.

---

Each MCP tool maps to a specific TrueDialog API surface. They're deliberately small and obvious; the agent's reasoning lives in the prompt, not in the tool list. Nine tools in all — six read-only, three that write.

1. whoami Returns the user and account behind your authorized session. Useful as a one-shot auth check. Read-only.
2. list_accounts Lists every account your login can see. Multi-tenant operators will care; single-account users won't. Read-only.
3. get_account_info Fetches a single account record. Defaults to the authenticated account. Read-only.
4. list_channels Lists the channels — long code, short code, RCS, email, voice — on an account. Call it to find the channel id before send_sms. Read-only.
5. get_contact Looks up a contact by id. Read-only.
6. search_contacts Substring match across phone numbers and email addresses. Read-only.
7. create_contact Creates a contact from a phone number or email (at least one is required). If that number or email is already on a contact, TrueDialog rejects the create and points you at update_contact — it won't silently make a duplicate.
8. update_contact Updates a contact's phone, email, or name. It reads the record first and rewrites only the fields you pass, so TrueDialog's overwrite-everything update doesn't wipe the rest — a read-modify-write, so it needs contact-read permission on top of manage, and it isn't atomic against a concurrent edit. A write.
9. send_sms Sends an outbound SMS to one or more numbers. A real send: by default it reaches live phones (pass execute=false for a dry run). Auto-resolves a sending channel if you don't name one. One-way — it doesn't read replies.

Talk to it.

You don't call these tools by name — you just ask, and the agent picks the right ones. A few things to try once you're connected:

• “Who am I connected as?” confirms auth
• “What channels are set up on my account?” reads channels
• “Text +1 512 555 0142: your table for four is confirmed for 7pm.” one send, one recipient
• “Find the contact for 512 555 0142 and let them know their order shipped.” looks up + sends

---

Files ride on the email tools. inbox_send_message and inbox_reply_to_message each take an attachments list; inbox_forward_message instead carries the original files itself (include_attachments, on by default). Every entry in an attachments list names exactly one source of bytes, and which source you pick is the difference between a file that arrives and a file that doesn't.

Those tools belong to the Inbox pack, which is enabled per deployment. The connector at connect.tdmcp.com currently advertises the nine TrueDialog tools above; attachments arrive with the email tools, wherever the Inbox pack is switched on.

1. attachment_id Names an attachment the platform already holds, on a message in this inbox — the ids come from inbox_get_thread. The server re-attaches the stored bytes itself, so nothing base64 passes through the model. This is the answer for anything that isn't tiny, and the natural path whenever the bytes are already on the thread you're replying to. filename and content_type are inherited from the stored bytes, and can be overridden. It lifts the transcription limit, not the size cap. (Forwards don't even need it: inbox_forward_message carries the original attachments by default.)
2. upload_id Names bytes already staged in storage — the path for a genuinely new large file. POST to /v1/inboxes/{inbox_id}/attachments/uploads with the file's name, MIME type and exact byte length; PUT the raw bytes to the presigned upload_url it returns; then quote the upload_id in your send. Wherever the Inbox pack is on, inbox_create_attachment_upload does the first step and returns the upload_id and upload_url. No tool does the PUT, so an agent whose only reach is this connector still cannot stage new bytes; the upload has to come from a client or app that can PUT out-of-band.
3. content Inline base64, supplied with filename and content_type. Reliable only for very small files — roughly 2 KB, about 2,700 base64 characters — because the whole string has to be emitted character-for-character in the tool call, and one wrong character fails the send with an opaque base64 padding error. It's a reliability ceiling, not a validated limit: nothing rejects you at 2 KB. The send is accepted and fails later, during decoding.

What the server enforces

Three bounds, all checked server-side:

1. 10 MB per message, totalled across every entry whatever its form — referenced bytes count in full, exactly like inline ones. Referencing saves you transcribing a file; it doesn't make the file smaller.
2. 10 MB per file, applied to the declared size_bytes when the upload slot is minted — so no URL capable of storing an oversize object is ever issued.
3. 100 entries in one attachments list.

The total is checked from stored metadata before a byte is fetched, and again once everything is resolved, so an over-cap send is refused with a 422 rather than partly delivered. Split a set that exceeds either bound across several sends.

The three forms mix freely inside one list. Presigned upload URLs are short-lived — 15 minutes by default — and the PUT has to send exactly the Content-Type and Content-Length you were handed, because the signature covers both. An upload is single-use: the first send that references it consumes it. GET …/attachments/uploads/{upload_id} tells you whether the slot is still pending, when it expires and which message consumed it; it does not check that your PUT landed. A send before the bytes are there is refused with a 422 and does not spend the upload, so you can retry once the PUT finishes. Reading the other direction, inbox_get_attachment returns an attachment's bytes base64-encoded.

---

The MCP server is the on-ramp. The interesting product work is on top of it: an agent runtime that turns SMS conversations into outcomes.

When an SMS reply lands, wake the right agent with full conversation context: the outbound that triggered it, the customer's history, the goal of the thread. Webhooks, but for agents.

Sell goals, not minutes. Multi-turn appointment confirmation and reschedule, NPS deepening on low scores, B2B lead qualification, support triage. The agent runs the conversation end-to-end.

TrueDialog's compliance IP applied to the reply layer. "Don't text me at night" becomes a quiet-hours offer, not a full unsubscribe. TCPA-defensible audit trail comes for free.

Don't replace your support reps. Assist them. Drafted replies, thread summaries, suggested next-best-action, all surfaced inside the agent console they already use.

---

Stack

FastMCP / httpx / Python 3.14
Azure Container Apps / ACR / Static Web Apps / Azure DNS
Terraform / Docker

License

MIT.

Set in

Lato, JetBrains Mono.