需要让支持 MCP 的 Agent 通过工具连接检索火山引擎文档、查询 API 或操作云资源时，可以使用 ve mcp。服务由火山引擎 CLI 启动，支持本地 stdio 和 HTTP 传输；可用能力以所安装 CLI 版本为准。

适用场景

MCP 适合在 Agent 中配置工具服务，由 Agent 发现并调用可用工具。终端操作、自动化脚本或能够执行命令的 Agent 也可以直接使用 CLI。连接 ve mcp 不要求先安装全部 Skills；Skills 可另行提供任务流程与专业知识。

可用工具

工具	用途
list_services	列出当前 CLI 支持的云服务及 service code。
list_apis	查询指定服务支持的 API。
get_api_parameters	查询 API 请求参数、类型、必填项和示例。
search_docs	检索公开的火山引擎文档，可按服务筛选；无需云账号凭证。
fetch_docs	读取检索结果中的文档 URL，可分段获取正文；无需云账号凭证。
call_api	调用当前 CLI 支持的 API；受云凭证、IAM 权限和本地安全策略约束。

这些工具不等于覆盖全部云 API，也不表示 ve tosutil、ve arkcli 等产品 CLI 的所有命令均已暴露为 MCP 工具。

本地接入

上表六项工具、call_api 的 yes 确认参数，以及公开文档检索与读取流程已在 ve 1.2.2 上验证。旧版本即使能启动 MCP，也可能缺少工具或参数。先安装或更新火山引擎 CLI，再检查版本和 MCP 命令帮助；升级已有 ve 的方法见“安装与配置”：

在 Agent 的 MCP 设置中添加本地 stdio 服务，启动命令使用 ve，参数使用 mcp。客户端通过标准输入输出与进程通信，无需填写 HTTP 地址。

配置项	填写方式
传输方式	stdio
启动命令	ve；如果客户端找不到 PATH 中的命令，填写实际安装的绝对路径。
启动参数	mcp
指定云账号配置	需要固定 Profile 时，使用 mcp、--profile、已存在的 Profile 名称作为参数。不要把凭据直接写入对话。

不同 Agent 的配置文件字段不同，按客户端的本地 MCP 设置方式填写。保存后重新加载连接，确认能列出上述六项工具，并检查 call_api 的参数定义是否包含 yes。若只有四项工具、缺少 search_docs 或 fetch_docs，或没有所需确认参数，先升级 ve 并重启 MCP；只重装 Skills 或 Plugin 不会升级正在运行的 MCP 进程。指定不存在的 Profile 会导致服务启动失败。

以 Claude Code 为例，在终端添加用户级连接并检查连通性：

用户级连接对该用户的项目生效。已有同名连接时修改现有配置，不必重复添加。若找不到 ve，把命令中的 ve 换成实际可执行文件的绝对路径。显示 Connected 后，继续执行下方工具调用验证；连接状态不代表云账号已授权。

Codex

已安装 Codex CLI 时，在终端添加本地连接并检查配置：

连接保存到当前 Codex 用户配置中，默认位于 ~/.codex/config.toml；设置了 CODEX_HOME 时使用对应目录。检查输出中的启动命令为 ve、参数为 mcp、传输方式为 stdio。如果 Codex 运行环境找不到 ve，将添加命令中的 ve 替换为实际可执行文件的绝对路径。

已有名为 volcengine 的连接时，先检查并修改该项，不重复添加或覆盖其他 MCP 连接。重新启动 Codex，在新会话中列出火山 MCP 工具，再按下方“完成一次调用验证”执行文档搜索和正文读取。codex mcp list 仅用于检查配置，不能单独证明连接成功或云账号已授权。

凭证与地域

查询公开文档不需要云账号凭证；call_api 需要云凭证。其解析顺序为显式 --profile、CLI 当前 Profile、VOLCENGINE_PROFILE 或 VOLCSTACK_PROFILE、SDK 默认凭证链，最后才是 HTTP 请求中的 X-Volcengine-Credentials。stdio 不接收 HTTP Header。

每次 call_api 都会重新读取 CLI 配置；在同一运行环境执行 ve login、切换当前 Profile 或更新凭证后，后续调用读取最新配置。显式 --profile 固定的是配置名称，不冻结其中的凭证。先确认 MCP 进程运行用户和配置位置，不能仅凭另一个终端登录成功就判断服务已获授权。

地域依次取 call_api 的 region 参数、启动参数 --region、所选 Profile 的地域、VOLCENGINE_REGION；均未配置时使用 cn-beijing。涉及云资源时应明确目标地域，避免依赖默认值。

完成一次调用验证

先让 Agent 执行公开文档查询，例如：

检查三个结果：能发现工具；search_docs 返回与问题相关的标题和摘要；fetch_docs 返回对应正文与可核对的来源。仅有 Connected、工具列表或非空返回，均不足以判断任务完成。结果不相关时，尝试更短的关键词，并使用已确认的文档 service code 限定范围；不要默认文档检索的 service code 与 CLI 命令名完全相同。

需要验证云 API 时，先在 MCP 所在机器、运行用户及同一 Profile 或凭证环境中，通过 ve sts GetCallerIdentity 检查身份；MCP 显式指定 Profile 时，检查命令也使用同一 Profile。已有有效的 AK/SK、STS 或其他受支持凭证时，无需额外执行 ve login；仅在选择 Console Login 且会话缺失或过期时重新登录。随后让 Agent 调用 call_api，传入 service: "sts"、api: "GetCallerIdentity"、parameters: {}，核对业务结果。返回 no active session 时，检查当前所选凭证链中的 Console Login 会话，不把它当作 MCP 连接失败，也不要覆盖其他有效凭证。其他资源查询再通过 list_services、list_apis 和 get_api_parameters 确认接口、地域与参数。有效空结果与认证失败应分别处理。

操作确认与错误处理

call_api 在解析凭证和发送请求之前检查本地安全策略。命中 deny 时不会发送云端请求；命中 confirm 时要求 Agent 说明目标与影响，等待你明确同意后，使用 yes: true 按原参数重试。该参数不能绕过 deny。一次性使用批准依赖 Agent 遵守规则，不是布尔参数本身提供的强制保证。

现象	检查内容
无法启动或列出工具	检查 Agent 实际启动的 ve 路径、版本、参数、Profile 和传输方式。若提示 missing tool, toolName=search_docs，或只有四项工具，先升级实际使用的 ve，再重启 MCP，重新检查六项工具与 call_api 的 yes 参数。不要仅重装 Skills 或反复修改云账号凭据。
文档可以查，云 API 调用失败	MCP 运行环境中的云凭证、账号、地域、IAM 权限及业务错误。
命中本地安全策略	查看 deny 或 confirm 结果；按策略与用户授权处理，不把策略拦截当作网络故障。
HTTP 返回 401 或 403	检查 MCP 访问令牌、issuer、audience、有效期或 scope；这与火山云 API 的凭证错误属于不同环节。

进阶：HTTP 连接

客户端支持 Streamable HTTP 时，可以启动本地 HTTP 服务：

该示例的端点为 http://127.0.0.1:8888/mcp，仅指客户端可访问的这台机器，不是官方托管地址。服务也支持兼容的 HTTP+SSE，按当前工具与客户端文档选择。

需要让其他机器访问时，应部署服务及相应的认证和 TLS。ve mcp 可作为 OAuth Resource Server，但不签发 Token，也不提供客户端注册和 Token Endpoint；OAuth 控制 MCP 访问，云 API 仍使用独立的云凭证配置。stdio 不能与 --oauth 同时使用。

传输协议、凭证优先级、地域、安全策略与 OAuth 部署参数见CLI MCP 官方说明。

其他 MCP 服务

需要其他工具服务时，可从智能体工具商店选择。它们可能使用独立的运行环境、凭据和计费方式，按提供方说明接入，不与 ve mcp 的配置混用。

与方舟和 Managed Agents 的关系

ve mcp 的工具清单不代表 Ark CLI 全部能力。方舟模型接入、用量账单及 Managed Agent 管理可按Ark 场景说明使用 CLI，不要求先建立 MCP 连接。

Ark CLI 自身的 MCP 配置、当前 Code Agent 连接的 ve mcp，以及云端 Managed Agent 使用的外部 MCP，需要分别核对。连接成功只证明对应连接可用；还应检查工具列表、认证和实际调用结果，不在文档或日志中暴露 MCP 凭据。

火山引擎 Agent Toolkit