tdmcp / no. 001 / filed under: agentic infrastructure / 2026
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.
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 per request. The deployed server holds no credentials. Every call carries TrueDialog username/password or API-key headers supplied by the caller, mapped server-side onto the TrueDialog API's Basic-auth handshake. Per-request also means one deployment can route to staging or production based on a single header.
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.
Log into ui.truedialog.com. Either your portal username and password or your API key, secret, and account id will work. The server accepts both.
Pick your client below, paste the snippet, fill in the placeholders. No secrets sit on our server. Jump to setup.
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.
Endpoint: https://connect.tdmcp.com. Streamable HTTP. Stateless.
Pass credentials per request as one of two header sets, your pick:
| Purpose | Headers | Notes |
|---|---|---|
| Auth: API key | X-TD-Api-Key, X-TD-Api-Secret, X-TD-Account-Id | Long-lived. Preferred for production. |
| Auth: Username | X-TD-Username, X-TD-Password | Bootstraps the account id via /userinfo on first call. |
| Environment (optional) | X-TD-Base-Url | Defaults to production (api.truedialog.com). Set to point at staging or another environment per client. |
Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS,
or the equivalent path on Windows. Add an entry under mcpServers:
{
"mcpServers": {
"truedialog": {
"type": "http",
"url": "https://connect.tdmcp.com",
"headers": {
"X-TD-Username": "YOUR_TD_USERNAME",
"X-TD-Password": "YOUR_TD_PASSWORD"
}
}
}
}Restart Claude Desktop. The truedialog server should appear with eight tools.
One CLI command. Run from a shell that already has your TD env vars set
(for example after set -a; source .env; set +a):
claude mcp add --scope user --transport http truedialog \
https://connect.tdmcp.com \
--header "X-TD-Username: $TD_USERNAME" \
--header "X-TD-Password: $TD_PASSWORD"Then /mcp inside Claude Code lists the tools.
In ChatGPT, open Settings → Connectors → Add custom connector. Choose MCP, then paste:
Name: TrueDialog
URL: https://connect.tdmcp.com
Authentication: Custom headers
X-TD-Username: YOUR_TD_USERNAME
X-TD-Password: YOUR_TD_PASSWORDWorkspace plans expose connectors in the model picker. Personal plans may require enabling MCP under Beta features.
In Microsoft Copilot Studio, create a custom connector / declarative agent referencing the MCP endpoint:
endpoint: https://connect.tdmcp.com
transport: streamable-http
headers:
X-TD-Username: YOUR_TD_USERNAME
X-TD-Password: YOUR_TD_PASSWORDM365 Copilot's MCP support is in active rollout; if your tenant isn't seeing the option yet, wait a release or use the Power Automate connector path instead.
Gemini's MCP support is shipping incrementally across Studio, Workspace, and the API. Once it's available in your tier, point it at the same endpoint and headers:
url: https://connect.tdmcp.com
headers:
X-TD-Username: YOUR_TD_USERNAME
X-TD-Password: YOUR_TD_PASSWORDSnippet will be tightened once Google publishes the final config schema.
To verify before wiring up a client, hit tools/list directly:
curl -sS -X POST https://connect.tdmcp.com \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H "X-TD-Username: $TD_USERNAME" \
-H "X-TD-Password: $TD_PASSWORD" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
| sed -n 's/^data: //p' | jqReturns the tool catalog as plain JSON. Useful as a smoke test when something looks wrong client-side.
The server defaults to production (api.truedialog.com).
Add an X-TD-Base-Url header to any of the client configs
above to redirect this client to a different TD environment. Auth
headers are unchanged; the credentials need to be valid in whichever
environment you point at.
{
"mcpServers": {
"truedialog": {
"type": "http",
"url": "https://connect.tdmcp.com",
"headers": {
"X-TD-Username": "YOUR_TD_USERNAME",
"X-TD-Password": "YOUR_TD_PASSWORD",
"X-TD-Base-Url": "https://staging-api.truedialog.com/api/v2.1/"
}
}
}
}Drop the X-TD-Base-Url line to switch
back to production. The same header works in every client.
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.
Returns the user and account behind the supplied credentials. Useful as a one-shot auth check.
All accounts visible to the credentials. Multi-tenant operators will care; single-account users won't.
Single account record. Defaults to the authenticated account.
Discover the channels (long code, short code, RCS, email, voice) configured on the account.
Look up a contact by id.
Substring match across phone numbers and email addresses.
Create a new contact. Either a phone number or an email address is required.
Push an outbound SMS. Auto-resolves a sending channel if you don't pass one.
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.
FastMCP / httpx / Python 3.14
Azure Container Apps / ACR / Static Web Apps / Azure DNS
Terraform / Docker
MIT.
Fraunces, Public Sans, JetBrains Mono.