内容基准：vgpu v0.4.0 ＋官方 MCP 参考与仓库源码。本篇是 vgpu 系列第 2 篇，讲 MCP：把 vgpu 的文档与可信示例变成 agent 的结构化工具。MCP 协议本身的科普见 docs/code 的 MCP 入门。

vgpu MCP 用法：hosted HTTP vs local stdio，与"下载边界"设计

vgpu 把第 1 篇讲的 docs + examples 两套能力，用 MCP 暴露成两个 typed 工具：

docs：查 vgpu 文档。操作 = search / resolve / list / grep / symbols / read
examples：查可信示例。操作 = search / show / read /（本地限定）download

核心设计取向：MCP 是只读的信息接口；唯一的写操作 download 被显式、按需地"圈地"授权。这一篇把两种 transport、接入配置、安全边界讲透。

1. 两种 transport，先分清楚

	Hosted HTTP	Local stdio
地址 / 命令	`https://vgpu.sh/api/mcp`	`npx -y vgpu mcp`
鉴权	无	无
状态	无状态，只读	无状态（起一个进程）
文档来源	当前稳定版（网站上部署的那版）	你装的那个 vgpu 包随包文档
离线示例缓存（`offline: true`）	不支持	支持
下载示例（`download`）	永远不暴露	Linux/macOS 下显式开边界才暴露
协议	Streamable HTTP，现代 MCP（2026-07-28）	stdio

一句话选型：只想检索 → hosted HTTP（一行接入，零配置）；要让 agent 用的文档和项目版本对齐、或用离线缓存、或要下载示例 → local stdio。

2. 快速接入：hosted HTTP

2.1 自动检测（推荐）：`add-mcp`

# 全局给本机所有已检测到的 MCP 客户端加上 hosted VGPU
npx -y add-mcp https://vgpu.sh/api/mcp -g

# 去掉 -g = 只给当前项目配

安装器会先让你审一遍它探测到的客户端再写配置，无需任何 vgpu 账号/鉴权。

2.2 手动配 Claude Code（本博客环境）

claude mcp add --transport http vgpu https://vgpu.sh/api/mcp

然后开一个新会话，或在会话里跑 /mcp，确认 vgpu server 与 docs、examples 两个工具已就位。

2.3 手动配 Cursor / Codex / 通用

Cursor 写进项目的 .cursor/mcp.json（或全局 MCP 配置）：

{
  "mcpServers": {
    "vgpu": {
      "url": "https://vgpu.sh/api/mcp"
    }
  }
}

Codex CLI：

codex mcp add vgpu --url https://vgpu.sh/api/mcp
codex mcp list

其它带"Add MCP server"表单的客户端，填：Name vgpu、URL https://vgpu.sh/api/mcp、Transport Streamable HTTP、Authentication 无。协议版本若被询问，选 automatic / modern，别选 legacy session-based HTTP（vgpu 有意拒绝旧会话式 HTTP——无状态端点可能被任意部署实例服务）。

发现层：https://vgpu.sh/.well-known/mcp.json 会公告这个端点（agents.md 里同样给了它）。

3. 工具语义：两个只读工具怎么用

`docs`

操作	干什么	主要入参
`search`	按概念找相关文档	`query`
`resolve`	把符号/文档目标解析成精确路径	`target`
`list`	浏览包与虚拟文档路径	`path`（默认 `/`）
`grep`	精确模式搜索（可限包、忽略大小写）	`pattern`
`symbols`	列出/搜索索引过的 API 符号	`query`、`package`
`read`	读取解析后的 guide/API 页	`target`

`examples`

操作	干什么	主要入参
`search`	按主题找示例	`query`
`show`	看示例 manifest 与文件清单	`id`
`read`	读示例里某个已校验文件	`id`、`path`
`download`	把可信示例发布到本地已批准边界内	`id`、相对 `destination`；仅 local stdio

分页细节：read 都支持 UTF-16 的 offset/limit（limit 默认且上限 65536 code units）；内容没读完时返回 truncated: true + nextOffset，用 nextOffset 接着请求。

可信细节：示例 manifest/文件沿用 CLI 那套 sha256 完整性校验与兼容性检查；可 pin 不可变小写 sha256 revision；local stdio 下 search/show/read 还可传 offline: true 禁止联网、只读已验证缓存。

怎么用（agent 的自然语言示例）

"在 VGPU 文档里搜 render pipeline，并总结配置步骤。"
"解析 texture 类型对应的 API reference 并读它。"
"找 gradient 相关的示例，看最好的那个 manifest 与文件。"
"读 gradient 示例的入口源码，解释它是怎么工作的。"

典型 doc 流：search/resolve → read；典型 example 流：search → show（看 manifest）→ read（挑文件）。

4. 本地 stdio：版本对齐 + 离线 + 下载

# 只读、随包文档、支持离线缓存
npx -y vgpu mcp

Claude Code / Cursor 等用 JSON 形状的客户端，配 command 而非 url：

{
  "mcpServers": {
    "vgpu": {
      "command": "npx",
      "args": ["-y", "vgpu", "mcp"]
    }
  }
}

Codex 用 TOML：

[mcp_servers.vgpu]
command = "npx"
args = ["-y", "vgpu", "mcp"]

裸 stdio 不广告 download。要开下载（仅 Linux/macOS），起服务时选一个"输出边界"，三种写法等价：

# ① 项目级：由 MCP host 从活动项目目录拉起进程（Claude Code 用 .mcp.json、Cursor 用 .cursor/mcp.json）
npx -y vgpu mcp --project-from-cwd

# ② 固定项目：绝对目录
npx -y vgpu mcp --output-dir /absolute/path/to/project

# ③ host 管理的环境变量
VGPU_MCP_OUTPUT_DIR=/absolute/path/to/project npx -y vgpu mcp

--output-dir/VGPU_MCP_OUTPUT_DIR 必须是已存在的绝对目录（会做 symlink 解析与规范化）；CLI 显式参数优先于环境变量；--output-dir 不能和 --project-from-cwd 同时用。

agent 提交的下载目标必须是该边界下的规范化相对路径：

{
  "operation": "download",
  "id": "gradient",
  "destination": "examples/gradient"
}

成功后会返回规范化后的绝对 destination。以下一律拒绝：绝对路径、./.. 片段、编码路径、反斜杠、控制字符、symlink 祖先、边界目录本身、已存在的目录。vgpu 用锁协调并发写入者；MCP 永不暴露人类 CLI 的 --force 行为；失败/取消的暂存目录会被清理。

⚠️ 并发注意（官方原文提醒）：Node 对目录没有"原子 no-replace rename"，所以发布最终目录期间，不要允许另一个进程并发抢占同一个 destination。

Windows 说明：即使配了输出边界，local stdio 在 Windows 上仍保持只读——CLI 在 Windows 无法给出同样安全的发布保证，于是干脆不广告写操作，好让一份跨平台共享配置不至于暴露一个跑不通的下载。

5. 安全检查表（值得抄的"写操作边界"设计）

远端配置只信官方 https://vgpu.sh/api/mcp；无需 token/header。
hosted HTTP 只读：不能执行示例代码、不能碰你的文件系统、不能发布示例目录。
local stdio 不发布到项目里，除非用户可控的启动命令显式选了输出边界；agent 只能在边界内选一个新的相对子目录。
MCP 客户端若支持，给文件系统工具开着 human confirmation；生成代码先审再跑。
下载会校验 manifest + 文件哈希、用锁协调写入者、清理失败暂存目录。

对要自己写 MCP server 的人，这就是一份"只读工具 + 圈地式写工具"的模板：读全开、写按需、路径规范化、拒绝穿越、用锁并发、永远不暴露 force。

6. 对照表：按需选 transport

你的需求	推荐配置
只检索/阅读文档或示例	Hosted HTTP `https://vgpu.sh/api/mcp`
文档要和装的那个包版本一致	裸 local stdio
用之前校验过的示例缓存干活	裸 local stdio + `offline: true`
下载进"当前活动项目"	local stdio + `--project-from-cwd`
下载进某个固定项目	local stdio + `--output-dir /absolute/path`

排障速查

症状	查什么
连不上 hosted HTTP	确认 URL 无误；协议选 automatic/modern；旧会话式 HTTP 会被拒
连上了但没工具	重载/重启客户端，确认 `docs`、`examples` 都在工具列表
没有 `download`	用 Linux/macOS 的 local stdio，并配 `--project-from-cwd` / `--output-dir` / `VGPU_MCP_OUTPUT_DIR`；hosted、裸 stdio、Windows 一律只读
`offline` 被拒	用 local stdio（hosted 部署在远端，没有本地缓存可选）
读取结果被截断	用返回的 `nextOffset` 再次 `read`
destination 被拒	换一个不含 `.`/`..`/反斜杠/编码分隔符、且不存在的规范化相对目录

参考与来源

官方文档 MCP 参考、CLI 参考的 mcp 段、agents.md
上一篇 Agent 与 Skill、下一篇 CLI 与示例

1. 两种 transport，先分清楚​

2. 快速接入：hosted HTTP​

2.1 自动检测（推荐）：add-mcp​

2.2 手动配 Claude Code（本博客环境）​

2.3 手动配 Cursor / Codex / 通用​

3. 工具语义：两个只读工具怎么用​

docs​

examples​

怎么用（agent 的自然语言示例）​

4. 本地 stdio：版本对齐 + 离线 + 下载​

5. 安全检查表（值得抄的"写操作边界"设计）​

6. 对照表：按需选 transport​

排障速查​

参考与来源​