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 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.
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.
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.
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:
You add connect.tdmcp.com to your client.
The client finds the OAuth server at auth.tdmcp.com and
registers itself automatically (dynamic client registration, PKCE).
A browser window opens. You sign in with your TrueDialog credentials.
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.
One command, no headers — Claude Code runs the OAuth handshake for you:
terminal
claude mcp add --scope user --transport http truedialog https://connect.tdmcp.com/
Then run /mcp inside Claude Code and choose
Authenticate — a browser opens for the TrueDialog sign-in.
After that, the tools are live.
In ChatGPT on the web, open Settings → Connectors (labelled
Apps & connectors on newer accounts) →
Advanced settings, turn on Developer mode, then
Create a connector:
Click Create and sign in with your TrueDialog credentials in
the popup — ChatGPT registers itself with the OAuth server automatically, nothing to paste.
Eligible users enable Developer mode first (on a managed workspace, an admin may need to turn it
on for the workspace). TrueDialog publishes explicit safety annotations for all nine launch tools:
account, channel, and contact lookups are read-only; contact changes and SMS sends are writes; and
overwrites and live sends are marked destructive. ChatGPT may ask for approval based on its current
policy and the conversation context. Plan and workspace availability are controlled by OpenAI and
may change.
In Microsoft Copilot Studio, add a tool →
Model Context Protocol and point the wizard at the endpoint:
mcp connector
Server URL: https://connect.tdmcp.com/
Authentication: OAuth 2.0 — Dynamic discovery
“Dynamic discovery” means no Entra app registration —
Copilot Studio registers itself with auth.tdmcp.com over DCR.
Turn on generative orchestration so the agent can choose tools on its own, then publish the
agent to the channels you want — Teams, Microsoft 365 Copilot, or your own site.
Adding MCP tools is a Copilot Studio capability, distinct from the consumer M365 Copilot chat.
For the Gemini CLI, add the server to ~/.gemini/settings.json and let it
authorize on first use:
The first call opens the OAuth sign-in in your browser; if it doesn't, run
/mcp auth truedialog inside the Gemini CLI to start it by hand. Gemini Enterprise
wires the same endpoint through the admin connector console (set once for the org). MCP
support is landing across Gemini's surfaces on different schedules — point any
OAuth-capable one at the same endpoint.
For the OpenAI Codex CLI, add the server to ~/.codex/config.toml as a
streamable-HTTP MCP server, then log in once:
That opens the browser for the TrueDialog sign-in — Codex does OAuth 2.1
with dynamic client registration, so there's no client id to enter. oauth_resource
pins the token to connect.tdmcp.com so the gateway-fronted auth server
issues it for the right audience. On older Codex builds that don't default to the remote-HTTP
client, also add experimental_use_rmcp_client = true.
GitHub Copilot speaks MCP in the VS Code editor and the
Copilot CLI (the github.com coding agent doesn't take remote OAuth
MCP servers yet). In VS Code, add the server to
.vscode/mcp.json (workspace) or your user mcp.json:
In VS Code, the MCP view shows a Start action;
it detects the server's OAuth challenge, registers itself via dynamic client registration, and
opens a browser for the TrueDialog sign-in — no client id or token to paste. The tools then
appear in Copilot Chat's Agent mode. Remote OAuth in the Copilot CLI
is newer and less reliable for gateway-fronted servers — if the browser sign-in doesn't
complete, supply a bearer through a headers block, or track
copilot-cli#3100/#4096. Needs VS Code 1.102+
(MCP generally available) and an active Copilot plan; on Copilot Business/Enterprise
an admin must first turn on the “MCP servers in Copilot” policy (Org/Enterprise settings
→ Copilot → Policies), which is off by default, and Copilot Free can't use the CLI at all.
Cursor takes remote MCP servers over Streamable HTTP with OAuth, so one click does it
— the install link carries nothing but the endpoint:
Cursor asks once to confirm the install, and the server then shows up
under Customize in the sidebar. Its first use opens a browser for the
TrueDialog sign-in — Cursor registers itself with auth.tdmcp.com
over dynamic client registration, so there is no client id, secret or
headers block to fill in. The tools then appear in Agent mode. The install
link is just {"url": "https://connect.tdmcp.com/"}, base64-encoded —
decode it if you want to check.
No token needed to confirm the server is up and speaking OAuth. An unauthenticated
request returns a 401 that points at the OAuth metadata:
Expect HTTP/2 401 with a WWW-Authenticate: Bearer
header whose resource_metadata points at
connect.tdmcp.com/.well-known/oauth-protected-resource — fetch
that to discover the authorization server (auth.tdmcp.com). That
challenge is the smoke test. To actually list tools, add a bearer token from the OAuth
flow as Authorization: Bearer <token>; your client obtains one for you.
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.
whoami
Returns the user and account behind your authorized session. Useful as a one-shot auth check. Read-only.
list_accounts
Lists every account your login can see. Multi-tenant operators will care; single-account users won't. Read-only.
get_account_info
Fetches a single account record. Defaults to the authenticated account. Read-only.
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.
get_contact
Looks up a contact by id. Read-only.
search_contacts
Substring match across phone numbers and email addresses. Read-only.
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.
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.
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.
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.)
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.
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:
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.
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.
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.