Send SMS from a Mastra agent

Register TextKit as an MCP server in Mastra and give its tools to an agent, so the agent can send texts, check delivery and work with contacts.

1. Get a test key

Create a test key on the API keys page of the console. It starts ssms_sk_test_, runs everything in the sandbox, and texts no real phone except your own verified one. Put it in your environment as TEXTKIT_API_KEY:

export TEXTKIT_API_KEY=ssms_sk_test_...

2. Add the MCP client

npm install @mastra/mcp@latest

Create the client in your Mastra project, for example mcp/textkit.ts. The key goes in requestInit.headers and stays in the environment, out of your source:

import { MCPClient } from '@mastra/mcp';

export const textkit = new MCPClient({
  id: 'textkit',
  servers: {
    textkit: {
      url: new URL('https://mcp.jointextkit.com'),
      requestInit: {
        headers: { Authorization: `Bearer ${process.env.TEXTKIT_API_KEY}` },
      },
    },
  },
});

3. Give the tools to an agent

import { Agent } from '@mastra/core/agent';
import { textkit } from '../mcp/textkit';

export const notifier = new Agent({
  id: 'notifier',
  name: 'Notifier',
  instructions: `
    You send SMS with the TextKit tools.
    Confirm the number and the wording before you send.
  `,
  model: 'openai/gpt-6.1-sol',
  tools: await textkit.listTools(),
});

Use any model string Mastra supports. Run it from a workflow, a route or a script:

const response = await notifier.generate('Text +15005550006 "Your order shipped."');
console.log(response.text);

When each of your users brings their own TextKit key, build the client per request and pass await client.listToolsets() as toolsets to generate() instead of fixing tools on the agent, then call disconnect(). The server exposes 142 tools: messages, verification, numbers, contacts, segments, broadcasts, automations and account reads. Each one is a single API call with your key, so the key's scopes, rate limits and send checks apply unchanged. The full list is on the MCP server page.

4. Check the sandbox run

+15005550006 is a sandbox number that always ends delivered, so the agent's tool call returns a message with an id starting msg_ and nothing reaches a phone. The message also shows in the console's message log, tagged Test. Ask for a text to your own number instead and, once that number is verified under Settings, it really arrives (up to 10 a day, ending "- via TextKit sandbox").

Go live

Swap the test key for a live one (ssms_sk_live_). A live text needs a number on your account: buy one and register your use case with the carriers. When the account has one number, from is optional and the text goes out from it. To limit what an agent can do with a live key, give it one with only the scopes it needs.

Sources

• Mastra: MCP overview