# 方舟文档 MCP
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
Ark Docs MCP 是方舟官方提供的远程 [Model Context Protocol](https://modelcontextprotocol.io/) Server。在支持 MCP 的 AI 编程助手（TRAE、Cursor、Claude Code、VS Code、Windsurf、OpenClaw 等）中完成配置后，AI 助手即可在编码上下文中直接检索方舟平台的**文档、API 参考、代码示例、模型信息**，降低幻觉、避免使用过时参数与已下线接口。
> **注意**
>
> **域名迁移通知**：Ark Docs MCP 已启用新域名 `https://mcp.ark-doc-resources.cn/mcp/`，原公测域名 `https://sd6j8o9hu8aldae0o6es0.apigateway-cn-beijing.volceapi.com/mcp` 将于 **2026-08-17** 下线停止服务。请在此前将 MCP 配置更新为新域名，避免服务中断。
## 接入方式
### 一键安装（推荐）
主流客户端支持通过 URL 协议直接唤起安装：
[安装到 TRAE CN（中国版）](trae-cn://trae.ai-ide/mcp-import?type=http&name=ark-docs-mcp&config=eyJ1cmwiOiJodHRwczovL21jcC5hcmstZG9jLXJlc291cmNlcy5jbi9tY3AvIn0=)
[安装到 TRAE（国际版）](trae://trae.ai-ide/mcp-import?type=http&name=ark-docs-mcp&config=eyJ1cmwiOiJodHRwczovL21jcC5hcmstZG9jLXJlc291cmNlcy5jbi9tY3AvIn0=)
[安装到 VS Code](vscode:mcp/install?%7B%22name%22%3A%22Ark%20Docs%20MCP%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.ark-doc-resources.cn%2Fmcp%2F%22%7D)
[安装到 Cursor](cursor:mcp/install?%7B%22name%22%3A%22Ark%20Docs%20MCP%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.ark-doc-resources.cn%2Fmcp%2F%22%7D)
[安装到 Windsurf](windsurf:mcp/install?%7B%22name%22%3A%22Ark%20Docs%20MCP%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.ark-doc-resources.cn%2Fmcp%2F%22%7D)
OpenClaw 等 AI Agent 安装
将以下内容发送给 AI Agent，由其完成安装。
```Plain Text
帮我安装方舟文档MCP
{
"mcpServers": {
"ark-docs-mcp": {
"url": "https://mcp.ark-doc-resources.cn/mcp/"
}
}
}
```
### 手动配置
在客户端的 MCP 配置文件中新增一条 server 条目：
```JSON
{
"mcpServers": {
"ark-docs-mcp": {
"url": "https://mcp.ark-doc-resources.cn/mcp/"
}
}
}
```
- Cursor / Windsurf：写入 `~/.cursor/mcp.json` / `~/.codeium/windsurf/mcp_config.json`
- Claude Code：写入 `~/.claude.json` 或项目 `.mcp.json`
- VS Code（GitHub Copilot MCP）：写入 workspace `.vscode/mcp.json`
- TRAE：设置面板 > MCP > 新增
保存后重启客户端，AI 助手的工具列表中即会出现 `ark-docs-mcp` 提供的 `ark_*` 工具。
## 工具列表
Ark Docs MCP 目前提供以下只读工具，按用途分为**文档 / API / 代码 / 模型** 四类。用户无需关心具体工具的调用参数，AI 助手会自主拉取工具列表并按需调用。
|分类 |工具 |描述 |
|---|---|---|
|文档 |`ark_search_docs` |检索方舟平台文档 |
|文档 |`ark_list_docs` |列出全部方舟平台文档 |
|文档 |`ark_fetch_doc` |拉取指定文档的完整正文 |
|API |`ark_list_apis` |列出方舟平台全部 API 端点 |
|API |`ark_get_spec` |获取指定 API 的参数定义与结构 |
|代码 |`ark_search_examples` |检索方舟官方多语言代码示例 |
|模型 |`ark_list_models` |按能力、状态、价格、限速等维度筛选模型 |
|模型 |`ark_get_model` |获取指定模型的完整元数据 |
## 典型示例
完成接入后，可在 AI 助手中直接使用自然语言触发以下能力。以下场景均由 AI 助手自主编排 `ark_*` 工具，无需手工指定具体工具调用序列。
### 报错排障
用户提问示例："调用 `chat/completions` 接口返回 401，请查询方舟文档定位可能原因。"
AI 助手行为：检索方舟文档中相关的错误码说明 > 深读命中文档 > 给出可能原因与修复步骤。
### 生成 API 调用代码
用户提问示例："使用 Python 编写调用 Ark `chat/completions` 的代码，要求启用流式返回，并参考官方最新示例。"
AI 助手行为：获取 API 参考 > 检索官方 Python 示例 > 依据规范与示例结构组装代码，避免虚构参数。
### 模型选型
用户提问示例："请检索支持 vision、低延迟、成本敏感的方舟模型，并输出对比表。"
AI 助手行为：按能力 / 状态 / 价格维度筛选候选模型 > 逐个拉取完整元数据 > 输出对比表，标注成本、限速、能力差异。
### 模型升级 / 迁移
用户提问示例："项目内使用的 `<待下线模型 ID>` 已在下线名单，请先给出迁移清单，不要直接修改代码。"
AI 助手行为：定位下线模型对应的推荐替换 > 确认新模型能力兼容 > 拉取新模型的调用示例 > 输出迁移清单。
## 使用限制
- **只读**：不提供任何写入或状态修改能力，读取失败不会产生副作用
- **无鉴权**：当前所有工具公开可用，无需 API Key
- **上下文预算**：`ark_get_spec` 强制按 `service` 或 `api_path` 过滤、`ark_fetch_doc` 支持分块拉取，避免单次调用返回超大 payload 占用 LLM 上下文
- **数据时效**：文档与模型元数据随方舟平台发布同步；若客户端缓存陈旧，重启 MCP session 即可刷新
## 附录：System Prompt 与服务元数据
面向 Agent Skill / System Prompt 开发者
### 服务元数据
- **接入点**：`https://mcp.ark-doc-resources.cn/mcp/`
- **协议**：MCP 2024-11-05；传输方式 Streamable HTTP
- **鉴权**：无需 API Key
- **数据时效**：实时，与方舟平台发布同步
### System Prompt 模板
以下段落可直接嵌入 AI 助手的 System Prompt 或 Skill 定义的 `instructions` 字段，用于约束工具调用时机与调用规范，减少凭训练知识作答与虚构参数：
```text
你已接入 ark-docs-mcp 工具集。请遵循以下调用约束：
1. 当用户提问涉及方舟平台的概念、API、报错排障、模型选型、
模型迁移时，必须先调用 ark-docs-mcp 检索方舟官方文档，
不得仅凭训练知识作答。
2. 生成方舟 API 调用代码前，必须先调用 ark_get_spec 获取
对应 API 参考；若未获取到 spec，拒绝生成代码。
3. 检索代码示例时，将目标语言（Python / Go / Java / cURL 等）
写入 query，避免返回非期望语言的示例。
4. 使用 ark_fetch_doc 拉取长文档时，若返回 has_more=true，
持续按 chunk_start += chunk_count 拉取直至完整。
```
参照上述模板落地时，可依据业务的规范化程度自行删改条款。