MCP 接入指南

通过 MCP，你的 AI Agent 可以发现并调用 Atomelody 的工具。你不需要了解配置文件的格式，可以把下面的提示词发给 Agent，让它帮助你完成接入。

本文只介绍安装、认证和连接验证。

让 Agent 帮你接入

1. 在平台的 API Key 凭据 页面创建或准备一个有效密钥。
2. 复制下面的提示词，发送给你希望接入的 Agent。
3. 按 Agent 引导在客户端的密钥设置或本地隐藏输入界面提供密钥，完成连接验证。

提示词不包含 API Key，不需要把密钥补充到提示词中。具备本地配置权限的 Agent 可以协助写入配置；无法修改客户端设置的 Agent 会引导你手动添加。

WorkBuddy 桌面应用需要用户在界面中手动添加、信任并启动新连接器，请按下方 WorkBuddy 小节操作；Agent 可以提供配置示例和操作指引。

请帮我把 Atomelody MCP 添加到我当前使用的 Agent 工具中。

先阅读官方安装指南：
https://www.atomelody.com/docs/api/mcp.md

请完成以下步骤：
1. 确认当前客户端、运行环境和配置能力。无法确定时，只询问必要信息，
   不猜测配置位置，也不要把临时执行环境误当成客户端所在环境。
2. 按指南选择对应客户端的配置方式，能自动完成的步骤请直接执行；
   需要我手动修改文件时，优先在当前工具的本地编辑器中打开对应文件，
   并指出要修改的字段。无法直接打开时，在对话中提供当前客户端支持的
   可点击文件链接；不支持文件链接时，提供完整路径和打开步骤。
3. 服务名称使用 atomelody-mcp。保留已有 MCP 配置；如果已有该服务，
   先检查并复用，避免重复添加。
4. 使用客户端支持的密钥存储、环境变量引用或个人配置文件配置 API Key。
   需要填写密钥时引导我在本地操作。不要要求我把
   密钥粘贴到聊天中，不回显密钥，不写入项目源码、版本控制或日志。
5. 连接后确认 Atomelody 工具可被当前 Agent 发现，并调用 get_capabilities
   验证接入。只进行连接验证，不创建或取消任务。
6. 如果需要重连、重载或新建会话，明确告诉我下一步；尚未验证成功时，
   不要声称接入成功。遇到权限或兼容性限制时，如实说明并提供手动步骤。

接入完成后，简要说明验证结果和可用功能，等待我的下一条指令。

连接信息

这是远程服务，无需在用户机器上安装 Atomelody 服务端。客户端需要支持 Streamable HTTP 和自定义认证请求头；不同客户端的配置格式并不通用。

每个 MCP 请求都需要有效的 API Key，包括初始化和工具发现。当前接入使用 API Key，不提供 OAuth 登录授权；平台网页登录态或 JWT 不能替代 API Key。

服务地址是 /mcp，不要添加 REST API 的 /v1 前缀，也不要改成 /sse。MCP 消息由客户端按协议发送，不使用 REST API 的响应封装。

Agent 配置步骤

确定配置位置

先检查当前客户端及其已有 MCP 配置，确认配置属于用户本机、远程开发环境还是托管环境。能执行命令并不意味着能修改用户实际使用的客户端设置。

优先使用客户端支持的配置入口或管理命令。编辑文件时先检查已有内容，按配置结构合并 atomelody-mcp，保留其他服务器及设置；不要直接用示例覆盖整个文件。已有同名服务时核对地址、认证引用和启用状态，不另建重复项。

通常可以使用用户级配置；用户明确要求仅在某个项目中使用时，使用项目级配置。下面的 Claude Code 示例采用其官方文档说明的项目级环境变量引用方式，并明确了作用范围。

如果客户端受组织策略管理，或 Agent 没有配置权限，应说明需要用户在何处操作，不绕过客户端的权限要求。

帮用户打开需要手动修改的文件

需要用户自行填写密钥或修改配置时，Agent 应先完成能够自动处理的配置准备，再使用当前客户端提供的文件打开能力，在当前工具的本地编辑器中打开对应文件，并尽可能定位到需要修改的字段或行，让用户直接编辑并保存。

如果无法直接打开，应在当前对话中提供客户端支持的可点击本地文件链接，而不只给出代码块中的文件名。链接应指向已经确认的实际配置文件，将 ~ 解析为目标客户端所在环境的用户目录，使用完整路径；支持行号定位时，可链接到待修改行。不要猜测客户端专用的链接协议，也不要把远程或临时执行环境中的路径当作用户本机路径。

同时简短说明需要替换哪个占位符、保留哪些格式，以及保存后如何继续。打开文件供用户编辑不等于将内容输出到聊天中，不要回显已有密钥或要求用户粘贴修改后的完整文件。客户端不支持直接打开或文件链接时，如实说明，并提供完整路径及最短的手动打开步骤。

配置凭据

优先复用客户端可读取的 ATOMELODY_API_KEY 或受支持的凭据存储。只检查密钥是否存在，不输出其值；未配置时引导用户打开 API Key 凭据 页面，并通过客户端密钥输入框或本地隐藏输入提供。

环境变量必须对运行 MCP 连接的客户端进程可见。终端里设置了变量，不代表从桌面图标启动的应用也能读取；Agent 子进程中临时设置变量，也不会修改已经运行的父进程环境。按客户端与操作系统支持的方式配置后，必要时重新启动客户端。不要假设项目中的 .env 会被自动加载。

API Key 只用于向 https://api.atomelody.com 发出的认证请求，不要放进 URL、接入提示词、聊天回复或诊断日志。客户端若只支持在配置文件中保存密钥，应引导用户在版本控制之外的个人配置中自行填写，并限制文件读取权限。

应用配置并验证

1. 按客户端要求启用服务器、重新连接或重载配置；如果本会话不能加载新工具，告知用户新建会话后继续验证。
2. 确认客户端完成 MCP 初始化和工具发现，且当前 Agent 能看到 Atomelody 的 get_capabilities。
3. 通过当前 Agent 的 MCP 工具调用 get_capabilities，传入空对象 {}。该工具只读取支持的模型、输入类型与限制，不创建任务。
4. 成功后简要报告连接状态和可用功能。失败时说明失败阶段和下一步，不输出认证请求头或密钥。

仅生成配置文件、在独立脚本中连接成功或向服务地址发送一次 HTTP 请求，都不表示当前 Agent 已经接入。需要重启后才能继续时，应报告“配置已完成，等待重启后验证”。

常见客户端配置

以下示例使用环境变量引用或密钥占位符，不包含真实密钥。使用环境变量的客户端，先按上一节让目标客户端能够读取 ATOMELODY_API_KEY；WorkBuddy 不支持环境变量解析，需要在添加 MCP 的界面中手动填写密钥。合并配置时保留已有内容。

Codex

在用户配置 ~/.codex/config.toml 中合并以下内容；若设置了自定义配置目录，应使用实际配置文件：

[mcp_servers.atomelody-mcp]
url = "https://api.atomelody.com/mcp"
bearer_token_env_var = "ATOMELODY_API_KEY"

bearer_token_env_var 填写环境变量名称，Codex 会读取其值并构造 Bearer 认证头。不要将真实密钥填入该字段，也不要把其他客户端的 JSON 配置直接写入 TOML。

应用配置后检查 MCP 状态，并按上面的验证步骤调用工具；如需新会话，在新会话中完成验证。

参考：OpenAI 官方 MCP 文档。

Claude Code

以下为项目级配置，合并到目标项目根目录的 .mcp.json，仅在该项目中使用：

{
  "mcpServers": {
    "atomelody-mcp": {
      "type": "http",
      "url": "https://api.atomelody.com/mcp",
      "headers": {
        "Authorization": "Bearer ${ATOMELODY_API_KEY}"
      }
    }
  }
}

保留示例中的环境变量引用，由 Claude Code 读取；不要在生成文件时将它替换成真实密钥。从能够读取该变量的环境启动 Claude Code，在 /mcp 中检查连接，并按客户端提示启用项目 MCP。

如需跨项目使用，请按当前版本的官方文档使用用户级配置或管理命令，不要将项目级文件位置当作用户级位置。

参考：Claude Code 官方 MCP 文档。

Cursor

在用户配置 ~/.cursor/mcp.json 中合并：

{
  "mcpServers": {
    "atomelody-mcp": {
      "url": "https://api.atomelody.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ATOMELODY_API_KEY}"
      }
    }
  }
}

Cursor 的环境变量引用使用 ${env:变量名}。如果只希望在一个项目中使用，可改为项目根目录下的 .cursor/mcp.json。远程 HTTP 配置不要使用仅适用于本地 stdio 服务的 envFile。

应用配置后，在 MCP 设置中检查服务器是否启用、连接和工具发现是否成功，再由 Agent 调用验证工具。

参考：Cursor 官方 MCP 文档。

WorkBuddy

WorkBuddy 桌面应用将 MCP 服务称为“连接器”。新添加的 MCP 服务需要用户手动信任并启动，因此请在桌面应用中手动添加。Agent 应提供下面的配置和操作指引。

1. 打开“连接器”。
2. 点击右上角的“自定义连接器”，再点击“添加MCP”。
3. 粘贴下方 atomelody-mcp 配置。
4. 将 ak_替换为自己的Key 占位符替换为自己的完整 API Key，保留前面的 Bearer 。WorkBuddy 不支持环境变量解析，请直接填写密钥，不要使用环境变量引用。
5. 点击“保存”，返回 MCP 列表，此时应能看到 atomelody-mcp。
6. 点击该服务的“信任”，信任并启动服务后，应能看到“n/n个工具已启用”（n 为实际工具数量），这表示配置已完成。

{
  "mcpServers": {
    "atomelody-mcp": {
      "type": "http",
      "url": "https://api.atomelody.com/mcp",
      "headers": {
        "Authorization": "Bearer ak_替换为自己的Key"
      }
    }
  }
}

请只在 WorkBuddy 的配置界面填写真实密钥，不要将替换后的配置粘贴到聊天中或提交到版本控制。

仅保存配置不会完成接入。尚未信任或未显示工具已启用时，Agent 应提示用户完成上述操作。界面显示配置完成后，再由 Agent 调用 get_capabilities，参数为 {}，验证当前会话能否使用工具。

其他 Agent 工具

按照该客户端的官方文档添加远程 Streamable HTTP 服务，并配置上面的地址和认证头。先确认其支持自定义认证头及凭据引用语法，不要直接套用其他客户端的示例。

若界面分别提供认证类型和 Token 输入框，选择 Bearer 后只填 ak_...；若填写完整的 Authorization 请求头，则值为 Bearer ak_...。

只支持 OAuth、仅支持本地 stdio，或不允许用户添加 MCP 的客户端，不能直接使用本文配置。网页聊天中的 Agent 也未必有权限修改其宿主的连接设置，应引导用户使用客户端提供的设置入口。浏览器前端直接请求 MCP 涉及额外的跨域支持，不属于本文的接入方式。

常见问题

排障时可以提供客户端名称和版本、操作系统、失败阶段及脱敏错误信息；不要提供 API Key 或完整认证请求头。