tdmcp.

tdmcp / no. 001 / filed under: agentic infrastructure / 2026

TrueDialog,
plumbed into
every agent.

An MCP server for the TrueDialog SMS API. One HTTPS endpoint. Bring your own credentials. Compatible with every major AI client, deployed on Azure, no SDK to install.


01.

The plumbing.

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.


02.

Quick start.

  1. i

    Have your TrueDialog login ready.

    You'll sign in with your ui.truedialog.com username and password when your client walks you through authorization — the same account you use in the portal. No API keys to copy, nothing to paste.

  2. ii

    Add the connector.

    Pick your client below, point it at connect.tdmcp.com, and approve the browser sign-in. No secrets live in your client config. Jump to setup.

  3. iii

    Send something.

    Ask your agent to "use the truedialog whoami tool." If you see your TrueDialog account back, you're wired. From there, every other tool works the same way.


03.

Configure your client.

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.


04.

Tools.

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

05.

Attachments.

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. An agent whose only reach is this connector cannot originate one — no tool is exposed over MCP for either step. The field is accepted and forwarded for clients and apps that can PUT out-of-band and already hold one.

  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, and GET …/attachments/uploads/{upload_id} will tell you whether your PUT landed. Reading the other direction, inbox_get_attachment returns an attachment's bytes base64-encoded.


06.

What's next.

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.

i.

Reply-aware runtime.

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.

ii.

Outcome-driven conversations.

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.

iii.

Opt-out intelligence.

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.

iv.

SMS copilot for humans.

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.


07.

Colophon.

Stack

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

License

MIT.

Set in

Lato, JetBrains Mono.