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.

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.


06.

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.