Use mails.ai with the Vercel AI SDK

This guide connects the Vercel AI SDK to the hosted mails.ai MCP server at https://api.mails.ai/mcp. It sends your API key in the Authorization header and gets the tools that key may call, as any other MCP client does (the tool list). With a test key (mk_test_…), the tools run in the sandbox and no email leaves mails.ai.

Before you start

The sample reads your key from MAILS_API_KEY. The framework also needs a key for its model provider, set the way its own documentation says.

export MAILS_API_KEY=mk_test_xxxxxxxx

The sample asks the agent to email reply@test.mails.ai. Nothing sent to that address leaves mails.ai, and it answers, so your agent gets a reply.received event back.

The TypeScript sample runs as an ES module with tsx. In a new folder:

npm init -y
npm pkg set type=module
npm install --save-dev tsx

Install

npm install ai @ai-sdk/mcp

Write the agent

createMCPClient turns the server’s tools into AI SDK tools. By default generateText stops once the model calls a tool; stopWhen: isStepCount(5) lets it read the tool’s result and write its answer. Close the client when the response is done.

Save this as agent.ts. The model string is the one the AI SDK’s own examples use; use the model your project already does.

import { createMCPClient } from "@ai-sdk/mcp";
import { generateText, isStepCount } from "ai";

const mcpClient = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.mails.ai/mcp",
    headers: { Authorization: `Bearer ${process.env.MAILS_API_KEY}` },
  },
});

try {
  const { text } = await generateText({
    model: "anthropic/claude-sonnet-5.5",
    tools: await mcpClient.tools(),
    stopWhen: isStepCount(5),
    prompt: "Email reply@test.mails.ai to say the report is ready.",
  });
  console.log(text);
} finally {
  await mcpClient.close();
}

Run it with npx tsx agent.ts.

Next steps