MCP 服务器

Warmbly 支持模型上下文协议（Model Context Protocol）。将任意 MCP 客户端连接到 Warmbly 服务器后，它即可在你授予的权限范围内搜索联系人、查看营销活动、读取收件箱、起草回复，以及创建营销活动和自动化流程的草稿。

• URL: https://api.warmbly.com/v1/mcp
• 传输方式：可流式传输的 HTTP
• 身份验证：OAuth 2.1 访问令牌（通过浏览器登录），或静态 API 密钥（通过 Bearer 请求头传入）。

有两种连接方式。OAuth 只需一条命令：运行 add 命令，在浏览器中批准访问后，客户端即可持有可刷新的短期令牌。API 密钥则是静态凭据方式：创建密钥并将其粘贴到客户端配置中。两种方式可访问完全相同的工具，也采用完全相同的权限检查。

通过 OAuth 连接

推荐使用此方式。无需在任何地方粘贴密钥：客户端会发现 Warmbly 的授权服务器，打开浏览器供你登录并批准权限范围，然后自行保存生成的令牌。

Claude Code

claude mcp add --transport http warmbly https://api.warmbly.com/v1/mcp

然后在 Claude Code 中运行 /mcp 并选择 Authenticate（身份验证）。浏览器打开后，登录 Warmbly，批准请求的权限范围，即可建立连接。无需配置请求头或密钥。

Claude Desktop 和 Cursor

仅使用 URL 添加服务器，客户端会在首次使用时执行 OAuth 流程：

{
  "mcpServers": {
    "warmbly": { "type": "http", "url": "https://api.warmbly.com/v1/mcp" }
  }
}

使用 API 密钥连接

希望使用静态的长期凭据，例如用于 CI、共享脚本，或不支持 OAuth 的客户端？创建 API 密钥并将其作为 Bearer 令牌发送：

Authorization: Bearer wmbly_...

Claude Code

claude mcp add --transport http warmbly https://api.warmbly.com/v1/mcp \
  --header "Authorization: Bearer wmbly_..."

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "warmbly": {
      "type": "http",
      "url": "https://api.warmbly.com/v1/mcp",
      "headers": { "Authorization": "Bearer wmbly_..." }
    }
  }
}

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "warmbly": {
      "url": "https://api.warmbly.com/v1/mcp",
      "headers": { "Authorization": "Bearer wmbly_..." }
    }
  }
}

提供哪些能力

无论使用 OAuth 令牌还是 API 密钥，服务器都只提供该凭据有权使用的工具。每个工具都会检查自身所需的权限范围；此外，OAuth 令牌或 API 密钥所属的成员在当前时点也必须具有对应的组织权限。只有读取权限的凭据只能看到读取工具，具有写入权限的凭据还会看到相应写入工具，因此 MCP 客户端只能在你明确授予的权限范围内操作。

这只是产品内置助手功能的子集。有两类操作仅限控制台，API 密钥和 OAuth 令牌始终无法访问：发送邮件（send_reply、compose_email），以及工作区治理（团队、工作区设置和账单）。这些路由仅接受会话身份验证，没有可授予的 API 权限范围，因此不会通过 MCP 提供。

每个工具都受其对应的 API 权限约束。tools/list 仅返回权限掩码允许使用的工具。无论权限范围如何，发送类工具（任何向收件人传送邮件的工具）都不会通过 MCP 提供；通过 MCP 使用助手时，只会生成草稿（draft_reply）。

有意未提供两类表单功能：品牌素材上传（徽标、封面、背景）采用多部分图片上传，并有尺寸和 MIME 类型限制，工具调用无法表达这些要求；自定义表单域名则属于整个工作区的品牌设置，并须通过 DNS 检查，因此位于设置中，不以工具形式提供。

MCP 调用与其他 API 调用遵循相同的速率限制：API 密钥按密钥限流，OAuth 令牌按用户限流。表中包含 SEND_CAMPAIGNS，是因为 set_campaign_status 和投递位置测试工具需要此权限。自行注册的 MCP 客户端永远不会获得该权限，因此只有持有此权限范围的 API 密钥或应用，才能通过 MCP 启动或停止营销活动。无论权限范围如何，向收件人发送邮件的工具（send_reply、compose_email）都不会通过 MCP 传输方式提供。

会返回密钥的工具（create_webhook 和 rotate_webhook_secret）会将密钥返回给发起调用的 MCP 客户端，也就是请求该密钥的调用方。产品内置助手始终无法看到这些值。

OAuth 发现机制

单命令连接流程采用标准 MCP 授权机制，因此任何符合规范的客户端都可以使用，无需针对 Warmbly 特别配置。请求未携带有效令牌时，/v1/mcp 会返回 401，并在 WWW-Authenticate 响应头中指向受保护资源的元数据。随后客户端依次执行：

• GET /.well-known/oauth-protected-resource：获取资源及其授权服务器（RFC 9728）。
• GET /.well-known/oauth-authorization-server：获取授权、令牌和注册端点（RFC 8414）。
• POST /v1/oauth/register：动态注册客户端，使客户端无需手动配置应用即可创建公共客户端（PKCE）的 client_id（RFC 7591）。
• 在浏览器中执行带 PKCE（S256）的授权码流程，然后调用 POST /v1/oauth/token 获取短期访问令牌和轮换式刷新令牌。

所有客户端都通过同一发现机制访问 Warmbly 的 OAuth 服务器。完整的授权服务器参考见 OAuth 2.1 页面。

另请参阅

• 智能体工具（REST）：通过普通 HTTP 提供同一工具注册表，适用于不支持 MCP 的 Hermes 和 OpenAI 风格函数调用智能体。
• OAuth 2.1：授权服务器端点、权限范围和动态注册。
• 身份验证：API 密钥与 OAuth 令牌的工作方式。
• 权限：完整的权限范围列表。
• 如果你需要反向连接，即让 Warmbly 连接到外部 MCP 服务器，请参阅连接 MCP 工具指南。