Mastra

The hosted MCP server, as a Mastra agent’s tools.

A Mastra agent can hold a Pidgeon inbox through the hosted MCP server. Mastra's MCPClient connects to a remote MCP server with a header, so there is no Pidgeon package to install. The tools, their descriptions and their defaults are the server's own.

bash

npm install @mastra/core @mastra/mcp zod

Mastra needs Node 22.13 or later, and zod 4.

Connecting

The key goes in a header. listTools() returns every tool as pidgeon_<tool>, and the agent gets the ones you hand it:

typescript

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

const mcp = new MCPClient({
servers: {
  pidgeon: {
    url: new URL('https://pidgeon.ai/api/mcp'),
    requestInit: { headers: { Authorization: `Bearer ${process.env.PIDGEON_API_KEY}` } },
    timeout: 300_000,
  },
},
});

const { pidgeon_list_threads, pidgeon_get_thread, pidgeon_await_message } = await mcp.listTools();

const agent = new Agent({
id: 'inbox-assistant',
name: 'Inbox assistant',
instructions: 'You work one Pidgeon inbox.',
model: 'openai/gpt-5-mini',
tools: { pidgeon_list_threads, pidgeon_get_thread, pidgeon_await_message },
});

const result = await agent.generate('Summarise the five newest conversations.', { maxSteps: 8 });
console.log(result.text);
await mcp.disconnect();

Raise the timeout. await_message holds one request open until mail arrives — 50 seconds by default, at most 280 — and returns it with extracted.codes and extracted.links already pulled out (Verification codes). Mastra ends a tool call after 60 seconds unless the server, or the whole client, is given a timeout in milliseconds, so a wait set longer than a minute fails without it.

Name the tools it may call. Hand the agent the tools the job needs rather than everything listTools() returns. An agent that only reads never sees send_message.

Bodies arrive cleaned by Pidgeon Firewall: hidden text removed and fake chat turns marked. The model can ask for body: "original" when it needs the HTML.

The key is the whole of the access control

Nothing in Mastra decides what the agent may reach. The key does, on the server, as it does for any other caller. Give it the narrowest one the job needs:

One address. A key lists the addresses it reaches, so an agent holding a key for support@yourdomain.com cannot read payroll@.
The lowest level that does the job. An agent that triages needs read, and a read key cannot send, whatever the prompt says. One that answers needs send.
An end date. A key with expires_at stops working on its own.

The program below mints exactly that: one address, send, an hour. Authentication covers narrowing a key by hand.

Waiting for a code

When the agent is about to cause the mail — submitting a form, sending a message — the right order is to take a cursor first: await_message with after: "now" and timeout: 1 returns at once with a cursor. Then it submits the form, then it waits with that cursor as after. The mail cannot arrive before the wait starts, and an older email cannot be taken for it. The tool's description tells the model this, and the program below says it in the task as well.

The whole program

The program makes an address that expires in an hour and a key for that address alone, and gives the agent only the key. The agent takes a cursor, emails itself a sign-in code, waits for it from the cursor, and answers with what it read; the program then reads the message back with its own key, because the agent's word is not proof.