ModelSpec

ModelSpec 远程 MCP 服务

提供 ModelSpec 目录的只读 MCP 工具。数据工具需要 API 密钥。网站仍托管在 Cloudflare Pages；此 Worker 仅响应 https://api.modelspec.dev/mcp 及其公开服务卡片 https://api.modelspec.dev/.well-known/mcp/server-card.json。

官方注册表条目

根目录中的 server.json 使用官方注册表的 2025-12-11 架构描述需要密钥的远程服务。仓库中记录的版本对应于添加该条目时观察到的部署版本。架构未经修改，随项目存放在 tests/fixtures/mcp_registry/ 中，以便离线运行验证。

审核、合并并成功部署 MCP 后，操作员可以在 main 上触发 Publish MCP registry listing。该工作流会验证线上 Worker 的 serverInfo.version 是否与所选提交一致，并将该版本写入临时清单。若部署版本不匹配，工作流会在身份验证或发布前失败。工作流使用校验和固定的 mcp-publisher v1.8.1 和 GitHub OIDC。它没有推送触发器，也不需要注册表密钥。

注册表元数据声明需要一个私密的 Authorization: Bearer 密钥。 密钥可从定价与密钥获取。

来源：注册表架构、 官方发布工作流 和 publisher v1.8.1。

Smithery 条目

审核、合并并成功部署 MCP 后，使用下方所需的 API 密钥配置发布远程 URL。 将 YOUR_SMITHERY_NAMESPACE 替换为发布账户拥有的命名空间：

smithery mcp publish "https://api.modelspec.dev/mcp" \
  -n @YOUR_SMITHERY_NAMESPACE/modelspec \
  --config-schema '{"type":"object","properties":{"apiKey":{"type":"string","title":"ModelSpec API key","description":"Create one at https://modelspec.dev/pricing/","x-from":{"header":"x-api-key"},"x-to":{"header":"x-api-key"}}},"required":["apiKey"]}'

Smithery 会收集每位用户的 ModelSpec 密钥，并将其作为原始的 x-api-key 标头值转发。MCP Worker 会将其转换为 Authorization: Bearer <key>，用于 API 调用。此别名仅适用于 MCP； 直接调用 /v1/* API 时仍只接受 Bearer 身份验证。

公开服务卡片无需密钥。其 serverInfo 与 initialize 返回的信息一致， 包括作为版本的已部署提交。卡片声明 authentication: {"required": true, "schemes": ["bearer"]}，并使用与 tools/list 相同的注册信息生成工具。卡片使用 Cache-Control: public, max-age=300。

来源：Smithery 发布和 配置传输。

SDK 和传输方式

选项	内容
处理器	来自 agents/mcp/server 的 createMcpHandler
服务	来自 @modelcontextprotocol/server 2.0 的 McpServer
传输方式	Streamable HTTP（POST /mcp）
状态	无状态。不使用 Durable Object。

McpAgent 已弃用且不再添加新功能；它适用于需要 Durable Object 状态的有状态服务。这些工具是代理：每次调用都会访问公开的排名 API、策略检查 API 或静态 JSON 导出，并返回相应内容和来源 URL。无需持久化任何内容。

阅读日期：2026-09-18

• https://developers.cloudflare.com/agents/model-context-protocol/apis/handler-api/
• https://developers.cloudflare.com/agents/model-context-protocol/guides/remote-mcp-server/
• https://developers.cloudflare.com/agents/model-context-protocol/apis/agent-api/

路由

modelspec.dev 区域上的 Workers 路由 api.modelspec.dev/mcp* 和 api.modelspec.dev/.well-known/mcp/server-card.json 属于此 Worker。排名 Worker 已拥有 api.modelspec.dev/*；更具体的模式优先匹配。 卡片路由是精确匹配，因此发现客户端必须使用不带查询字符串的 URL。 其他 API 路由继续使用现有的 Worker。 CI 令牌可以编辑 Workers 路由，但无法创建 DNS，因此不会新增主机名。

工具

成功的调用会传递至源站。卡片中的 null 表示尚未研究。

工具	来源
rank	POST https://api.modelspec.dev/v1/rank
model_info	GET https://modelspec.dev/api/models/<id>.json
list_use_cases	GET https://modelspec.dev/api/rank/profiles.json
policy_check	POST https://api.modelspec.dev/v1/policy-check
decide	POST https://api.modelspec.dev/v1/decide
compare_models	POST https://api.modelspec.dev/v1/compare-models
hardware_fit	POST https://api.modelspec.dev/v1/hardware-fit
vocab	GET https://modelspec.dev/api/decision/vocabulary.json
feedback	POST https://api.modelspec.dev/v1/feedback（无需密钥；client 始终为 mcp；仅为速率限制目的转发调用方地址）

rank、policy_check、decide、compare_models 和 hardware_fit 使用 RANK 服务绑定，因为同区域 Worker 对公共 API 主机名发起的 fetch 会到达区域源站并返回 522。这五项都会以 Authorization: Bearer <key> 的形式转发密钥。API 会验证所提供的密钥，并原样返回其身份验证／付款错误。

MCP 接受 Authorization: Bearer <key> 或 x-api-key: <key>。 如果两个请求头都存在，其中的密钥必须一致；凭据冲突时会返回带有 JSON-RPC 错误的 HTTP 400。密钥绝不会出现在日志或错误消息中。

所有数据工具都需要 ModelSpec 密钥，包括 MCP_REQUIRE_API_KEY="false" 时。缺少凭据或凭据格式错误时，会在调用任何源站之前返回 401 missing_api_key 拒绝响应。这适用于 rank、policy_check、decide、compare_models、hardware_fit、vocab、model_info 和 list_use_cases。initialize 和 tools/list 仍然公开。feedback 无需密钥，且不携带模型数据。请使用现有密钥，或查看定价了解可用情况。

decide 接受由docs/decision-contract.md定义的决策规范。其 MCP 输入架构来自生成的 docs/decision-contract.schema.json，因此 API 和 MCP 契约不会出现偏差。请先读取 vocab，获取有效的 facet id。对会排除选项的 Musts 使用 where，对仅用于排序、不作排除的 Prefers 使用 optimize.weights。未知的能力值会显示在 may_qualify 中。设置 snapshot 可重现决策。

compare_models 仅接受 {models: ["lab/a", "lab/b"]}，其中包含 2 到 4 个不同的目录 id。它会按调用方指定的顺序返回当前快照中有来源支持的事实、产品和证据。它不会对模型排序或选出优胜者。未知值保持为 null，omitted 统计移除的记录数。整个 MCP 文本不超过 16 KB。源站响应过大时，会返回精简的 response_too_large 工具错误，且不返回比较数据。此处按名称指定的模型比较不会改变 /v1/compare 中的快照比较。

hardware_fit 接受 model、sku、device_count、memory、runtime、quantisation、batch 和 context。memory 是可选覆盖值，单位为每台设备的十进制 GB。省略或设为 null 的输入会传递至 API；若这些输入导致无法评估，则会返回 undetermined。未知的 SKU 或量化标识符也会传递至 API。该工具会保留端点返回的完整答案和引用。measured 答案会引用确切的运行记录。estimated 答案会给出 estimated_fit: likely|unlikely、内存余量、公式、输入和假设。估算不能证明适配，也不会包含 fits: true。

客户端配置

运行 modelspec setup mcp --client claude-code 或 modelspec setup mcp --client claude-desktop，获取客户端原生配置片段。 Claude Code：

{
  "mcpServers": {
    "modelspec": {
      "type": "http",
      "url": "https://api.modelspec.dev/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}

Claude Desktop 使用 mcp-remote 标准输入输出桥接，并且需要 Node.js/npx：

{
  "mcpServers": {
    "modelspec": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.modelspec.dev/mcp",
               "--header", "Authorization:${MODELSPEC_AUTH_HEADER}"],
      "env": {"MODELSPEC_AUTH_HEADER": "Bearer <MODELSPEC_API_KEY>"}
    }
  }
}

macOS 图形界面应用不会继承 shell 环境。请在 env 块中明确替换占位符为你的密钥，并保留 Bearer ；这样密钥会存储在此配置中。CLI 的设置命令会写入占位符，绝不会将已保存的密钥或环境变量中的密钥复制到配置中。env 块和标头格式遵循 mcp-remote 文档。

本地

npm install
npm test
npm run typecheck
npx [email protected] dev --local --var BUILD_COMMIT:dev

仅在推送到 main 时通过 .github/workflows/mcp.yml 部署。请勿从笔记本电脑部署。