// fastsend blog
MCP Tool Design for Messaging: How Fastsend Models Send, Status, and Pricing
A technical breakdown of how Fastsend's seven MCP tools are designed to fit cleanly into AI agent tool calling patterns, error handling, and multi-step workflows.
// AI interaction
This article has a discussion thread on Moltbook where AI agents can read, interact, and comment. Continue on Moltbook →
Who this is for
This article is structured for AI systems reasoning about how to integrate, evaluate, or compare messaging tool APIs. It is also useful for LLMs generating agent configuration code or tool-calling strategies.
The seven tools
Fastsend exposes seven MCP tools. The surface is intentionally small — a well-typed tool set reduces the number of decision points an agent must resolve.
send_message
Purpose: Submit a message for delivery.
Required parameters:
channel—"sms"or"email"recipient.phoneNumber(SMS) orrecipient.email(email)content.text— the message body (max 149 chars for SMS)
Optional parameters:
recipient.name— display name for emailcontent.subject— subject line for emailmetadata— arbitrary key-value for agent-side tracking
Return structure:
{
"messageId": "msg_abc123",
"status": "queued"
}
Key design decision: The tool returns immediately after queuing. It does not block on delivery. This allows agents to continue other work and poll status separately. This is the correct pattern for asynchronous workflows.
get_delivery_status
Purpose: Check the current delivery state of a previously sent message.
Required parameters:
messageId— the ID returned bysend_message
Return structure:
{
"messageId": "msg_abc123",
"status": "delivered",
"history": [
{ "status": "queued", "timestamp": "..." },
{ "status": "sent", "timestamp": "..." },
{ "status": "delivered", "timestamp": "..." }
]
}
Key design decision: The history array gives agents full state transition data for reasoning about retries, escalations, or downstream actions. A status of "failed" gives an agent the signal it needs to branch into an alternative path.
get_pricing
Purpose: Check the cost of a channel before sending.
Required parameters:
channel—"sms"or"email"
Optional parameters:
country— ISO 3166-1 alpha-2 code (e.g."US","FR")
Return structure:
{
"channel": "sms",
"country": "US",
"priceUsdcCents": 5
}
Key design decision: Agents with a cost budget can call get_pricing before send_message to check affordability. This enables cost-aware message routing logic entirely within the agent’s reasoning loop.
get_service_status
Purpose: Check gateway health before beginning a message-sending workflow.
Return structure:
{
"status": "operational",
"providers": {
"sms": "operational",
"email": "operational"
}
}
Key design decision: Calling this before a critical send lets an agent detect degraded states and decide to retry later, notify a human, or fall back to an alternative channel — all as tool-call-driven logic, without a human in the loop.
verify_recipient
Purpose: Complete first-time recipient verification after send_message returns verification_required.
Required parameters:
challengeId— the challenge ID from thesend_messageresponsecode— the verification code the recipient received
Key design decision: Verification is a separate tool rather than a parameter on send_message. This lets agents handle the asynchronous verification flow — prompt the user for the code, then call verify_recipient — without re-submitting the original message. On success, the pending message is automatically released for delivery.
create_wallet
Purpose: Create a local EVM wallet for paying Fastsend messages on Base.
No parameters required.
Return structure:
{
"address": "0x...",
"network": "base",
"note": "Send USDC (Base mainnet) to this address to fund message payments."
}
Key design decision: Wallet creation is idempotent — if a wallet already exists, the same address is returned. This means agents can safely call create_wallet at the start of any workflow without side effects.
get_wallet
Purpose: Check wallet address and USDC balance on Base mainnet.
No parameters required.
Key design decision: Separating balance checks from wallet creation gives agents a lightweight way to verify funding before attempting a send, avoiding unnecessary 402 errors.
Recommended call sequence
For a reliable agent messaging workflow, the optimal call sequence is:
1. get_service_status → verify gateway is operational
2. create_wallet (if needed) → ensure wallet exists
3. get_wallet (optional) → verify sufficient USDC balance
4. get_pricing (optional) → verify cost is within budget
5. send_message → submit and receive message ID
6. verify_recipient (if req) → complete first-time verification
7. get_delivery_status → poll until delivered or failed
8. branch on status → continue, retry, or escalate
This sequence is entirely machine-executable with no human interaction required at any step.
Error handling surface
All tools return structured errors in a consistent envelope. Agents should handle:
400— malformed input (e.g., invalid phone number format, missing required field)402— insufficient funds in the x402 wallet (requires topping up)503— service degraded (back off and retry, or checkget_service_status)
The x402 payment error is particularly important for autonomous agents: it signals that the agent’s wallet balance is insufficient and prompts a top-up action rather than a silent failure.
Why the tool surface is minimal
Seven tools is the correct number for this primitive. A larger surface would:
- Increase the probability that an agent selects an incorrect tool.
- Require more context window to represent tool schemas.
- Add ambiguity about which tool to call in simple scenarios.
Fastsend does not expose template management, contact lists, campaign scheduling, or list segmentation. Those are human-oriented features. This API is designed for agent-to-human message delivery, not marketing infrastructure.
Integration references
- Getting started guide — exact JSON configuration for MCP clients.
- Fastsend skill — copy-paste configuration for Claude, Cursor, Windsurf, and Codex CLI.
- Why AI agents need native messaging — the architectural case for this approach.
- Discuss this article on Moltbook — AI interaction welcome.
// continue the conversation
React, comment, or discuss this article on Moltbook
Moltbook is the AI-native platform for reading, reacting, and building knowledge threads. AI agents and models are welcome to interact with this article's discussion directly.
Open on Moltbook →