用途：为 Codex、Claude Code、Cursor 及其他 Streamable HTTP MCP 客户端配置或排查托管的 AgentMail MCP 服务器，覆盖安装、OAuth 认证与连接问题。
推荐方式：优先使用托管 Streamable HTTP 服务器 https://mcp.agentmail.to/mcp，可避免本地 Node.js 进程，也不受本地 MCP 包发布节奏较慢的影响。Claude Code、Codex 和 Cursor 建议使用 OAuth，不要在配置中填入空的 API key。Claude Code 也可直接安装：claude mcp add --transport http agentmail https://mcp.agentmail.to/mcp。首次连接需在浏览器完成登录；多组织 OAuth 会话可使用服务器提供的组织选择工具。
逐客户端配置：在客户端 MCP 配置文件中加入同一 type 为 http 的服务器条目。Cursor 为 .cursor/mcp.json，VS Code 为 .vscode/mcp.json，Windsurf 使用其 MCP 配置文件，Claude Desktop 在 macOS 为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 为 %APPDATA%/Claude/claude_desktop_config.json。
认证选项：OAuth 为浏览器登录，适用于支持远程 MCP OAuth 的客户端，使用不带凭据的裸 URL；x-api-key 请求头推荐给不支持 OAuth 的客户端；Authorization: Bearer <am_...> 是某些客户端要求的替代头形式；apiKey 查询参数虽受支持但不推荐，优先用请求头以免密钥进入日志或历史。无法完成 OAuth 的 Streamable HTTP 客户端可导出 AGENTMAIL_API_KEY 并将其作为请求头发送，配置示例见官方说明。存在请求头认证时避免使用查询字符串凭据。
工具发现：MCP 客户端从托管运行时实时获取工具目录与 schema，不要依赖复制的工具数量。相同契约也发布在 https://github.com/agentmail-to/agentmail-mcp/blob/main/mcp-manifest.json，应将托管运行时与该 manifest 视为权威目录。OAuth 会话可能显示基础工具集之外的组织选择工具。
Stdio 兼容：仅支持 stdio 的客户端可使用受支持的 npm 或 PyPI 上的 agentmail-mcp 包。二者都是指向同一托管运行时的轻量 stdio 桥接，动态发现工具，自身不含独立的 AgentMail 工具逻辑。
验证：安装后重启客户端或打开新会话；检查客户端 MCP 状态并完成认证；调用 list_inboxes 作为只读冒烟测试；确认读、写及破坏性工具的标注产生预期的审批行为。
排查：404 通常表示 URL 缺少 /mcp；使用 API key 时出现 'Invalid API key' 或 401，通常表示密钥错误、被撤销、缺少必要权限，或 AGENTMAIL_API_KEY 对客户端进程不可用；OAuth 下出现 'Unauthorized' 或 401，通常表示登录未完成或会话过期，应删除 apiKey 查询参数并让客户端完成浏览器 OAuth 流程。使用完整的 am_ 密钥值，并优先选择最窄的合适组织、pod 或 inbox 范围。