Vantage MCP Server

关于

Vantage MCP 服务提供用于列出、查询和创建 Vantage 资源的工具。工具定义见 /src/tools；完整工具列表、提示词示例和产品详情请参阅 Vantage MCP 文档。

此仓库支持两种部署模式：

模式	适用场景
托管（远程）MCP — 由 Vantage 管理，地址为 https://mcp.vantage.sh/mcp	适合大多数用户和团队。通过 OAuth 登录，无需运行本地服务。
自托管（本地）MCP — 通过 npx -y vantage-mcp-server 或此仓库使用 stdio	适用于 API 令牌认证、隔离网络环境或为此代码库做贡献。

除非有特定的自托管需求，否则请从托管 MCP 开始使用。

设置说明

通用说明

托管 MCP 服务使用 Streamable HTTP 和 OAuth 2.1。连接客户端后，浏览器窗口会提示你登录 Vantage — 使用你在 console.vantage.sh 使用的同一账户。

服务 URL： https://mcp.vantage.sh/mcp

旧版 SSE 连接： /sse 端点已弃用，在为期 60 天的迁移期内仍可使用，该迁移期将于 2026 年 11 月 30 日结束，届时旧版 SSE 端点将停止服务。如果你的客户端使用 https://mcp.vantage.sh/sse，请将其服务 URL 更新为 https://mcp.vantage.sh/mcp；如果客户端询问传输方式，请选择 Streamable HTTP，然后重新连接，并根据提示登录。部分客户端在连接时会显示弃用警告，其他客户端则不会。

原生支持远程 MCP 的客户端可以直接连接该 URL。对于仅支持 stdio 的客户端，请使用 mcp-remote 桥接工具（见下方的 Visual Studio Code）。

API 令牌认证： 客户端和脚本可以通过发送 Vantage API 令牌（包括服务令牌），在无需 OAuth 的情况下向托管端点进行身份验证：

Authorization: Bearer <your_vantage_api_token>

Core 会在每次工具调用时验证令牌及其权限。读取操作需要 read 范围；修改操作需要相应的写入权限。无效或已撤销的令牌可以初始化 MCP，但其工具调用会返回 Core 的授权错误。

Claude Code

claude mcp add --transport http vantage https://mcp.vantage.sh/mcp

然后在 Claude Code 会话中运行 /mcp，完成 OAuth 流程。

Codex

codex mcp add vantage --url https://mcp.vantage.sh/mcp

如果 Codex 提示你进行身份验证，请运行 codex mcp login vantage。

Cursor

推荐的安装方式是使用 Vantage 官方插件 — 在 Cursor 聊天面板中运行：

/add-plugin vantage

如需手动配置（例如，将 .cursor/mcp.json 提交到代码库）：

{
  "mcpServers": {
    "VantageMCP": {
      "url": "https://mcp.vantage.sh/mcp"
    }
  }
}

打开 Cursor Settings → Tools & MCP → New MCP Server 编辑 mcp.json，或在项目根目录中创建 .cursor/mcp.json。

Claude

Claude.ai（Team / Enterprise）： Settings → Connectors → Add custom connector — 输入 https://mcp.vantage.sh/mcp。

Claude Desktop： Settings → Connectors — 使用相同的 URL 添加自定义连接器。

Goose

1. Extensions → Add custom extension
2. 类型： Streamable HTTP
3. 端点： https://mcp.vantage.sh/mcp

Goose 连接时，完成 OAuth 流程。

Visual Studio Code

{
  "mcpServers": {
    "vantage": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.vantage.sh/mcp"]
    }
  }
}

或者使用命令面板：MCP: Add Server → Command (stdio)，然后输入：

npx -y mcp-remote https://mcp.vantage.sh/mcp

Windsurf

在 Cascade → MCP servers → Add custom server 下添加：

{
  "mcpServers": {
    "vantage": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.vantage.sh/mcp"]
    }
  }
}

Zed

在 Zed 设置中添加：

{
  "context_servers": {
    "vantage": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.vantage.sh/mcp"],
      "env": {}
    }
  }
}

其他客户端

对于任何仅支持 stdio 的 MCP 客户端，请使用：

• 命令： npx
• 参数： -y mcp-remote https://mcp.vantage.sh/mcp

如需了解其他客户端（包括通过 Vantage 应用使用 ChatGPT），请参阅 MCP 客户端列表和 Vantage MCP 文档。

授权

配置客户端后，可能需要重启客户端。系统会打开一个浏览器窗口，供你进行 Vantage OAuth 身份验证——登录并点击 Allow Access。你可以随时在 Vantage Settings → API Access Tokens → MCP Server Token 下撤销访问权限。

尝试使用如下提示词：“在 Vantage 中，我可以访问哪些工作区？”

---

自托管（本地）MCP

如果需要使用 API 密钥进行身份验证而不使用 OAuth，或者要基于此仓库进行开发，请使用自托管模式。

npm 软件包（推荐用于自托管）

无需安装任何内容——配置 MCP 客户端以运行已发布的软件包：

{
  "mcpServers": {
    "Vantage": {
      "command": "npx",
      "args": ["-y", "vantage-mcp-server"],
      "env": {
        "VANTAGE_TOKEN": "<your_vantage_api_token>"
      }
    }
  }
}

在 Vantage 控制台中创建令牌。需要 Node.js 20+。

从此仓库运行（贡献者）

如需开发 MCP 服务本身：

git clone https://github.com/vantage-sh/vantage-mcp-server
cd vantage-mcp-server
npm install

配置客户端以运行本地入口点（替换 <path_to_repository> 和 <personal_vantage_api_token>）：

{
  "mcpServers": {
    "Vantage": {
      "command": "npx",
      "args": ["tsx", "<path_to_repository>/src/local.ts"],
      "env": { "VANTAGE_TOKEN": "<personal_vantage_api_token>" }
    }
  }
}

或者直接使用仓库中已安装的二进制文件：

{
  "mcpServers": {
    "Vantage": {
      "command": "<path_to_repository>/node_modules/.bin/tsx",
      "args": ["<path_to_repository>/src/local.ts"],
      "env": { "VANTAGE_TOKEN": "<personal_vantage_api_token>" }
    }
  }
}

在终端中测试：npm run local（需要在环境中设置 VANTAGE_TOKEN）。

---

本地开发

如需在本地开发托管 Worker：

cp .dev.vars.example .dev.vars.development
# Edit .dev.vars.development — set VANTAGE_MCP_TOKEN to your API token
npm run dev

Wrangler 会在 http://localhost:8787（默认值）提供 Worker 服务。设置 VANTAGE_MCP_TOKEN 可在本地测试时绕过 OAuth。

---

运行评测

每个工具都会通过一个直接提示词和一个推断提示词进行测试。两次运行都会加载目标工具和四个干扰工具，然后可以在不同模型上重放相同的测试用例。评测结果会以 JSON 文件的形式提交，因此无需重新运行整个测试套件；GitHub Pages 会根据这些文件重新构建报告。有关方法和完整工作流，请参阅 evals.md。

新工具必须在 evals/cases/<resource>/<tool>.eval.ts 下附带测试用例。编写规范：.agents/skills/writing-evals/SKILL.md。

在本地查看评测结果

npm run eval:site
open evals/site/index.html

无需模型 API 密钥。已发布的报告位于 https://vantage-sh.github.io/vantage-mcp-server/。

运行新评测

在 .env 中设置 ANTHROPIC_API_KEY 和/或 OPENAI_API_KEY，然后运行：

npm run eval -- --tool <your-tool> --model gpt-5.6-sol-high

必须指定 --model（运行 npm run eval -- --list-models 可查看模型目录）。这会写入 evals/results/<model>/<resource>/<tool>.json，并保持所有其他结果文件不变。提交生成的新 JSON 文件。

覆盖评测结果

使用相同的 --tool 和 --model 重新运行。该组合对应的 JSON 文件会被替换。更改工具的描述、架构或提示词后，请执行此操作——除非你也想刷新基线，否则无需重新运行所有模型。

---

可用脚本

• npm run dev — 启动 Wrangler 开发服务器
• npm run local — 在本地运行 stdio MCP 服务
• npm run inspect — 启动 MCP 检查器
• npm run test — 运行 Vitest
• npm run format / npm run lint:fix — 使用 Biome 进行格式化和 lint 检查
• npm run type-check — 进行 TypeScript 检查
• npm run cf-typegen — 生成 Cloudflare Worker 类型
• npm run generate-tools-index — 工具更改后重新生成 src/tools/index.ts
• npm run generate-resources-index — 资源更改后重新生成 src/resources/index.ts
• npm run eval — 运行工具选择评测（npm run eval -- --tool <name> --model gpt-5.6-sol-high）
• npm run eval:site — 合并已存储的 JSON，并写入 evals/site/index.html
• npm run eval:view — 打开 promptfoo 本地结果查看器

---

贡献指南

1. Fork 此仓库并创建分支：git checkout -b feature/my-feature。
2. 进行更改。
3. 在本地验证：

   npm run format
   npm run lint:fix
   npm run type-check
   npm test -- --run
   

4. 提交拉取请求。

添加工具、评估或资源时，请参阅 AGENTS.md 了解相关约定。

---

许可证

有关商业和非商业许可的详细信息，请参阅 LICENSE.md。