Skip to navigation
Integrations

Claude Agent SDK

Give your Claude agent its own email inbox

Getting started

The Claude Agent SDK is Anthropic’s framework for building agents on Claude, available for TypeScript and Python. It connects to external tools through MCP, and AgentMail runs a hosted MCP server, so a Claude agent gets a full email inbox with a few lines of configuration and no extra packages.

To give your Claude agent an email inbox, add the AgentMail server at https://mcp.agentmail.to/mcp to the mcpServers option of query(), authenticate with your AgentMail API key in the x-api-key header, and allow the AgentMail tools with allowedTools. There is no AgentMail package to install or update: the server always exposes the current tool set.

Use cases

  • Give agents their own inboxes: Provision a dedicated email address per agent so it can send and receive mail independently.
  • Triage and reply: Read recent threads and reply inside the same thread, with threading handled automatically.
  • Stage and send: Compose drafts iteratively and send them when they’re ready.
  • Inbound-driven agents: Pair the server with AgentMail webhooks so your agent reacts the moment mail arrives.
  • Durable email identity: Give long-running Claude agents an address they keep across sessions, so contacts and threads persist between runs.

Prerequisites

  1. An AgentMail account with an API key from the AgentMail Console.
  2. The Claude Agent SDK (@anthropic-ai/claude-agent-sdk for TypeScript or claude-agent-sdk for Python) and an Anthropic API key.

Setup

Install the Claude Agent SDK for your language:

npm install @anthropic-ai/claude-agent-sdk

Set your API keys:

export AGENTMAIL_API_KEY=your-api-key
export ANTHROPIC_API_KEY=your-anthropic-api-key

Quickstart

Connect the AgentMail MCP server and allow its tools:

import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
  prompt: "Create an inbox for yourself, then check it for new messages and reply to anything urgent.",
  options: {
    mcpServers: {
      agentmail: {
        type: "http",
        url: "https://mcp.agentmail.to/mcp",
        headers: { "x-api-key": process.env.AGENTMAIL_API_KEY! },
      },
    },
    allowedTools: ["mcp__agentmail__*"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Configuring the connection

Authentication

Pass an API key from the AgentMail Console in the x-api-key header, as in the quickstart. The MCP server also supports OAuth sign-in, but that flow is for end-user clients like Claude Desktop. For agents built with the SDK, use the API key header.

Allowing tools

AgentMail tools surface in the SDK as mcp__agentmail__<tool_name>, for example mcp__agentmail__send_message. The mcp__agentmail__* wildcard in allowedTools auto-approves every AgentMail tool.

allowedTools is required. Without it, Claude sees the AgentMail tools but can’t call them.

For production, list only the tools the agent needs:

allowedTools: ["mcp__agentmail__send_message", "mcp__agentmail__list_messages"],

Available tools

The server exposes 43 tools covering inboxes, threads, messages, drafts, attachments, allow and block lists, and agent sign-up. See the MCP integration for the full list.

Claude Code

If you use the Claude Code CLI rather than the SDK, add the same server with one command:

claude mcp add --transport http agentmail https://mcp.agentmail.to/mcp

See MCP setup for Claude Code for details.

Resources