Verlon AI MCP

@verlon-ai/mcp

适用于 Verlon AI 的 Model Context Protocol 服务。它将你的 Verlon 资源（门、日志、建议、实验）作为 MCP 工具提供，让编码 Agent（Claude Code、Cursor、Cline 及任何兼容 MCP 的客户端）能够直接检查和管理你的 AI 基础设施。

状态： 0.4.0 — 已在 MCP Registry 中列出，名称为 ai.verlon/mcp。提供 6 个只读工具（list_gates、get_gate、list_logs、get_recommendations、list_experiments、list_models），以及一个写入工具 switch_model；只有使用 --enable-writes 时才会注册。更多写入功能（create_gate、update_gate、run_chat、start_experiment）将在未来版本中推出，并受同一标志控制。

安装

你无需直接安装它。MCP 客户端（Claude Code、Cursor 等）会通过 npx 将其作为子进程启动。将下面的代码片段添加到客户端的 MCP 配置中。

Claude Code

将其添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或操作系统中的对应文件：

{
  "mcpServers": {
    "verlon": {
      "command": "npx",
      "args": ["-y", "@verlon-ai/mcp"],
      "env": {
        "VERLON_API_KEY": "sk-vrln-..."
      }
    }
  }
}

然后重启 Claude Code。verlon 服务应会显示在工具列表中，Claude 可以针对你的账户调用 verlon:list_gates。

Cursor

将其添加到 Cursor MCP 配置中（Settings → Features → MCP Servers）：

{
  "mcpServers": {
    "verlon": {
      "command": "npx",
      "args": ["-y", "@verlon-ai/mcp"],
      "env": {
        "VERLON_API_KEY": "sk-vrln-..."
      }
    }
  }
}

其他任何兼容 MCP 的客户端

此服务通过 stdio 使用 MCP 通信。在子进程环境中设置 VERLON_API_KEY，并启动 npx -y @verlon-ai/mcp。

工具

默认工具集为只读；原因请参阅安全说明。只有在服务启动时使用 --enable-writes，才会注册写入工具。

工具	输入	返回内容
list_gates	无	账户中的所有门 — id、名称、描述、模型、taskType、taskSubtype、createdAt
get_gate	gateId（UUID）	完整的门配置 — 模型、备用链、任务类型、支出限额、子门、编排
list_logs	gate?、since?（ISO 8601）、success?、limit?（1-100，默认 20）	最近的请求日志 — 时间戳、门、模型、成本、延迟、成功/失败
get_recommendations	gateId（UUID）	Cortex 智能分析报告 — 主题、偏移检测、优化建议。如果尚未生成报告，则为 { report: null }
list_experiments	gateId?、status?、projectId?	实验（影子 + 拆分）— id、名称、状态、测试类型、变体、目标指标、配置
list_models	provider?（openai、anthropic、google、mistral、…）	门可路由到的聊天模型，包含实时定价（每 1M 个令牌的 USD 价格）和能力评分

写入工具（仅限 --enable-writes）

工具	输入	功能
switch_model	model（来自 list_models 的 id）、gateId?	切换编码门路由到的模型。更改会在任何正在运行的会话的下一轮生效，无需重启。省略 gateId 时，目标为账户的 Claude Code 连接器门。此操作幂等；更改仅涉及一个可还原的字段。

配置

环境变量	必需	默认值	说明
VERLON_API_KEY	是	—	你的 Verlon API 密钥（sk-vrln-...）。
VERLON_BASE_URL	否	https://api.verlon.ai	用于可自托管 Verlon 的覆盖值。

CLI 标志

标志	用途
--enable-writes	注册支持写入的工具（目前为 switch_model）。默认只读 — 配置不当的 Agent 无法意外销毁资源。
--help、-h	打印用法说明。

安全说明

默认只读是经过深思熟虑的选择。MCP 客户端（Claude Code、Cursor 等）可以看到此服务的工具，并可能在用户请求让这些工具显得相关时自主调用它们。默认只读意味着，即使是目标不一致的 Agent，也只能查看你的账户，无法修改账户。只有在了解相关影响后，才选择启用写入工具（--enable-writes）。目前唯一的写入工具是 switch_model，这是首个写入功能，并被刻意限制到最小范围：在一个 gate 上修改一个可撤销的字段。目前尚未开放创建、更新或删除资源的功能。

开发

npm install
npm test          # vitest
npm run build     # tsc → dist/

发布（维护者）

该软件包会同时发布到 npm 和 MCP Registry：发布到 npm 时使用 @verlon-ai/mcp（自动发布，并附带来源证明），发布到 MCP Registry 时使用 ai.verlon/mcp（手动发布）。Registry 会在接受发布前验证 npm 版本是否存在，因此始终先发布到 npm。

每次发布流程

在三个文件中同步更新版本号——如果不一致，CI 会失败：

文件	字段
package.json	version
server.json	version 和 packages[0].version
src/server.ts	VERLON_MCP_VERSION 常量

然后：

# 1. Merge the bump to main (CI enforces the lockstep), then tag:
git tag v0.4.1 && git push origin v0.4.1
# The publish workflow runs `npm publish --provenance` automatically.

# Wait ~30s for npm CDN; verify:
npm view @verlon-ai/mcp version   # should print the new version

# 2. MCP Registry publish (manual — needs mcp-publisher + DNS-verified ai.verlon namespace)
npm run publish:mcp

一次性设置（Registry 发布）

# Install the MCP Registry publisher (NOT npm — it's a prebuilt binary)
brew install mcp-publisher

# DNS-verify the verlon.ai domain (required to publish under the ai.verlon namespace)
mcp-publisher login --help   # follow the DNS verification flow it prints
# Add the TXT record on verlon.ai; verify with `dig TXT verlon.ai +short`

验证

# All three versions match?
npm view @verlon-ai/mcp version
jq -r .packages[0].version server.json
grep VERLON_MCP_VERSION src/server.ts

# Registry listing live?
curl 'https://registry.modelcontextprotocol.io/v0/servers?search=verlon' | jq

# End-to-end smoke against the published artifact
VERLON_API_KEY=sk-vrln-... npx @modelcontextprotocol/inspector npx -y @verlon-ai/mcp

许可证

MIT — 详见 LICENSE。