# Vercel AI SDK email tool: an MCP inbox for agents

> Give a Vercel AI SDK agent an inbox with createMCPClient. The exact TypeScript to wait for mail, read a screened safe view and reply from generateText.

Source: https://trotta.email/integrations/vercel-ai-sdk

The Vercel AI SDK connects to Trotta Mail with createMCPClient from @ai-sdk/mcp. Give it the URL https://api.trotta.email/mcp and an API key, then hand the tools to generateText or streamText. Your agent can wait for mail, read a screened safe view, send and reply, and dangerous mail is held for a human.

Updated November 20, 2026

## Install and connect

Install the AI SDK and its MCP client, the `@ai-sdk/mcp` package. Trotta Mail is a remote MCP server, so there is no server to run.

```bash
npm install ai @ai-sdk/mcp
```

Connect over HTTP with your key as a bearer header, then hand the tools to `generateText` or `streamText`. The code follows the [AI SDK docs](https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools), checked on 2026-11-20.

```typescript
import { createMCPClient } from "@ai-sdk/mcp";

const client = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.trotta.email/mcp",
    headers: { Authorization: `Bearer ${process.env.TROTTA_MAIL_API_KEY}` },
  },
});

const tools = await client.tools();
// When you are done: await client.close();
```

## A complete example: inbox, wait, read, reply

This example gets an inbox, waits for a message, reads it and replies. Every Trotta Mail integration page runs the same four steps, so you can compare them. Step 1 is one HTTP call. The model takes steps 2 to 4 with tools.

### 1. Get an inbox

One call creates an inbox and an API key, with no account and no key.

```bash
curl -X POST https://api.trotta.email/v1/agents/signup \
  -H "Content-Type: application/json" \
  -d '{"name": "riley"}'
```

The response carries `api_key`, `inbox.address` and a `claim_url` for the human responsible for the agent. The key is shown once. Put it in `TROTTA_MAIL_API_KEY`.

### 2 to 4. Wait, read and reply

`generateText` runs one step unless you set `stopWhen`. Waiting, reading and replying take several tool calls, so the example allows eight steps. The model line takes any model the AI SDK supports, with that provider's key in your environment.

`agent.ts`:

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

const client = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.trotta.email/mcp",
    headers: { Authorization: `Bearer ${process.env.TROTTA_MAIL_API_KEY}` },
  },
});

try {
  const tools = await client.tools();
  const { text } = await generateText({
    model: "anthropic/claude-sonnet-5.5", // any model the AI SDK supports
    tools,
    stopWhen: isStepCount(8),
    prompt: "Wait for the next message in my inbox, read it, and reply in one line.",
  });
  console.log(text);
} finally {
  await client.close();
}
```

Run it, then send a mail to the inbox address. The model calls `wait_for_message`, then `read_message`, then `reply_to_message`. Outgoing mail is screened too: a reply that contains a secret is not sent.

Before a human claims the agent, it can receive from anyone and reply to anyone whose mail to it arrived authenticated. To write to new addresses, a human opens the `claim_url`.

## What your agent reads

Your agent reads screened mail: a tool result from Trotta Mail is never the raw email. Three things come back instead.

- **A verdict.** Every message carries one, decided before the message is readable: `deliver`, `flag`, `hold` or `reject`, with a one-sentence summary.
- **The safe view.** Only content a human could see. Hidden text is removed, instructions aimed at a model are replaced by a note, and risky links are defanged.
- **Held mail, withheld.** A dangerous message waits outside the inbox for a human. The tool returns `withheld: true` and the reason in fixed words, and nothing the sender wrote.

Screening before delivery matters in a multi-step call, where each tool result becomes input to the next model step. An instruction hidden in an email would land in that input like any other text. Trotta Mail takes it out, or holds the whole message, before any step reads it.

No filter catches everything, so treat mail content as data, never as instructions. The verdict and the safe view are described in [Concepts](https://trotta.email/docs/concepts).

## Going further

- [MCP](https://trotta.email/docs/mcp): every tool the server offers.
- [Webhooks](https://trotta.email/docs/webhooks): a signed event posted to your route when mail arrives.
- [Live events](https://trotta.email/docs/events): the same events over a stream, when you have no public endpoint.
- [Pods](https://trotta.email/docs/pods): one isolated workspace per customer.
- [Domains](https://trotta.email/docs/domains): agent inboxes on your own domain, on paid plans.
- [The TypeScript SDK](https://trotta.email/integrations/typescript): the same inbox from plain code, with no model in the loop.

## Questions

### How do I send email from a Vercel AI SDK agent?

Connect the Trotta Mail MCP server with createMCPClient and pass client.tools() to generateText or streamText. The send_message and reply_to_message tools send mail, and each message is screened before it leaves.

### Why does my agent stop after one tool call?

generateText and streamText run a single step by default. Set stopWhen, for example isStepCount(8), so the model can wait, read and reply in one call.

### Does it work with streamText?

Yes. client.tools() returns AI SDK tools, so they work with generateText and streamText alike. Close the client when the response has finished.

### Can the model read mail that was held?

No. A held message comes back withheld, with the reason in fixed words and nothing its sender wrote. A human releases it, and the agent then receives it as an ordinary message.

### Is Trotta Mail made by Vercel?

No. Trotta Mail is an independent product that works with the Vercel AI SDK as a remote MCP server. It is not made or endorsed by Vercel.

## Sources

- [AI SDK docs: Model Context Protocol (MCP)](https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools)
- [Trotta Mail guide for agents (llms.txt)](https://api.trotta.email/llms.txt)

## Related

- [MCP](https://trotta.email/docs/mcp) Docs
- [An email MCP server for any MCP client](https://trotta.email/integrations/mcp) Integrations
- [An email inbox for TypeScript and Node.js agents](https://trotta.email/integrations/typescript) Integrations
- [Give an AI agent an email address](https://trotta.email/learn/give-an-ai-agent-an-email-address) Guides
- [Email API for AI agents](https://trotta.email/learn/email-api-for-ai-agents) Guides
- [Hidden text in email](https://trotta.email/threats/hidden-text-in-email) Threat library

Give your agent an inbox of its own. One call, or one minute in the console.

[Get an inbox](https://trotta.email/signup) [Read the docs](https://trotta.email/docs)
