mcpField
A
agentmail-mcp

agentmail-mcp

github.com/agentmail-toAgent 工作流251.2k 次安装2 天前更新
代码仓库

关于 agentmail-mcp

用于将客户端连接到 AgentMail 托管 MCP 服务的配置与使用技能，涵盖 OAuth 和 API 密钥认证、客户端配置、工具发现及验证。

主要功能

  1. 01托管 Streamable HTTP 端点
  2. 02OAuth 与 API 密钥认证说明
  3. 03MCP 客户端配置示例
  4. 04实时发现工具目录
  5. 05连接验证与故障排查

适用场景

  1. 01将 MCP 客户端连接到 AgentMail
  2. 02为客户端选择认证方式
  3. 03查看可用的邮件和 AgentID 工具
  4. 04排查连接或认证问题

MCP 相关

说明客户端如何连接 AgentMail 托管的 Streamable HTTP MCP 服务或 stdio 桥接程序，并完成认证和工具发现。该服务提供邮件与 AgentID 工作流等工具组。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/agentmail-to/agentmail-skills --skill agentmail-mcp

安装后在 Claude Code 中输入/agentmail-mcp确认已加载。

详细介绍

AgentMail MCP

优先使用托管的 Streamable HTTP 服务：

https://mcp.agentmail.to/mcp

这样可以避免运行本地 Node.js 进程，也无需等待已发布本地 MCP 软件包较慢的更新周期。

Claude Code、Codex 和 Cursor

使用 OAuth。不要在配置中填写空的 API 密钥。

{
  "mcpServers": {
    "agentmail": {
      "type": "http",
      "url": "https://mcp.agentmail.to/mcp"
    }
  }
}

Claude Code 也可以直接安装：

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

首次连接时，请在浏览器中完成登录。多组织 OAuth 会话可以使用服务的组织选择工具。

Claude.ai、Claude Desktop 和 ChatGPT 连接器

这些应用会将该服务添加为连接器，并在浏览器中完成 OAuth。无需 API 密钥。

  • **Claude.ai 和 Claude Desktop：**依次打开设置 → 连接器 → 添加自定义连接器。将其命名为 AgentMail，将 URL 设为 https://mcp.agentmail.to/mcp，然后点击连接，并在 console.agentmail.to 登录。
  • **ChatGPT：**开启设置 → 安全与登录 → 开发者模式（如果使用工作区计划，管理员必须先允许）。然后打开 ChatGPT 插件，点击 +，将 URL 设为 https://mcp.agentmail.to/mcp，选择 OAuth，并在 console.agentmail.to 登录。在聊天中，从开发者模式下的 + 菜单选择 AgentMail。

在 Claude.ai 中添加的连接器不会同步到 Claude Code；请在那里单独添加。

各客户端配置

在客户端的 MCP 配置文件中添加相同的 type: http 服务条目：

  • Cursor：.cursor/mcp.json
  • VS Code：.vscode/mcp.json
  • Windsurf：其 MCP 配置文件
  • Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%/Claude/claude_desktop_config.json（Windows）

身份验证选项

  • OAuth — 基于浏览器的登录，适用于支持远程 MCP OAuth 的客户端。使用不带凭据的基础 URL。
  • x-api-key header — 推荐用于不支持 OAuth 的客户端（见下文）。
  • Authorization: Bearer <am_...> header — 某些客户端要求使用的另一种 header 格式。
  • apiKey query param — 支持但不推荐；优先使用 header，以免密钥出现在日志或历史记录中。

对于无法完成 OAuth 的 Streamable HTTP 客户端，请导出 AGENTMAIL_API_KEY 并将其作为 header 发送：

{
  "mcpServers": {
    "agentmail": {
      "type": "http",
      "url": "https://mcp.agentmail.to/mcp",
      "headers": {
        "x-api-key": "${env:AGENTMAIL_API_KEY}"
      }
    }
  }
}

如果支持 header 身份验证，请避免在查询字符串中使用凭据。

工具发现

MCP 客户端会从托管运行时实时获取工具目录和架构；请勿依赖复制的工具数量。同一份生成的契约也发布在 https://github.com/agentmail-to/agentmail-mcp/blob/main/mcp-manifest.json — 请以托管运行时和该清单为权威目录。OAuth 会话可能会显示基础工具集之外的额外组织选择工具。

目录涵盖的不仅是邮件。用户询问连接器能做什么时，请引导他们查看以下类别：

  • 收件箱、会话、消息、草稿、附件以及允许/屏蔽列表 — 相关邮件工作流见同级的操作技能。
  • AgentID 应用和账户 — list_apps、search_apps、get_app、connect_app、authorize_inbox 和 list_accounts 可为第三方应用中的 Agent 创建账户（例如“在 Firecrawl 创建账户”），并显示各收件箱是否已有账户。authorize_inbox 会使用应用的 Sign in with AgentID 页面显示的身份验证令牌，完成该页面发起的登录，包括未在 AgentID 注册的应用。目录中的应用可以用 slug（firecrawl）指定，list_apps 可按类别筛选。该工作流请使用 agentmail-agentid 技能。
  • Agent 注册 — agent_attach_human 和 agent_verify 可解除未验证的 Agent 组织所受的限制。

Stdio 兼容性

对于仅支持 stdio 的客户端，请使用受支持的 npm 或 PyPI agentmail-mcp 软件包。两者都是连接同一托管运行时的轻量 stdio 桥接程序：它们会动态发现工具，本身不包含独立的 AgentMail 工具逻辑。

验证

  1. 安装插件后，重启客户端或打开新会话。
  2. 检查客户端中的 MCP 状态并完成身份验证。
  3. 调用 list_inboxes 进行只读冒烟测试。调用 list_apps 确认 AgentID 工具已公开。
  4. 确认读取、写入和破坏性工具注解会触发预期的审批行为。

故障排查

  • 404 通常表示 URL 缺少 /mcp。
  • 已发布清单中的工具或参数未出现在会话中（例如，list_apps 没有 category）：托管服务不会通知目录变更，因此会话会保留连接时的工具列表。请开启新会话或重新连接连接器。
  • 使用 API 密钥身份验证时出现“Invalid API key”或 401，通常表示密钥错误、已撤销、缺少必要权限，或客户端进程无法使用 AGENTMAIL_API_KEY。
  • 使用 OAuth 时出现“Unauthorized”或 401，通常表示登录未完成或会话已过期——删除任何 apiKey 查询参数，让客户端改为完成基于浏览器的 OAuth 流程。
  • 请使用完整的 am_ 密钥值，并优先选择范围最小且适用的组织、pod 或收件箱范围。
  • 对于仅支持 stdio 的客户端，请参阅上文的 Stdio 兼容性。

评论

支持 Markdown