把 MCP 工具当作 API Contract：记录你的智能体能做什么
几个月前我们发布了 API Contracts：把 OpenAPI、gRPC、GraphQL 和 AsyncAPI 规范直接关联到实现和消费它们的 C4 元素。想法很简单——一个接口精确、可被机器读取的描述，应该存在于你的架构之内，而不是在一个没人更新的 Notion 页面里。
还有一个接口我们没有覆盖。最新的那一个。你的服务越来越多地不是向其他服务、而是向 AI 智能体暴露的那一个——MCP。
一个 MCP 服务器会发布一组工具——每个都有名称、描述,以及用于其输入的 JSON Schema。这就是一份契约。它正是决定一个智能体被允许对你的系统做什么的契约。而直到今天,它在你的架构文档里完全不可见。
现在不再如此。MCP 现在是 Archyl 中一等的 API Contract 类型——继 HTTP、gRPC、GraphQL 和 AsyncAPI 之后的第五种。
难点：MCP 工具不存在于某个文件里
另外四种契约类型共享一个假设——仓库里有一个规范文件。openapi.yaml。schema.graphql。你把 Archyl 指向它，我们就渲染它。
MCP 打破了这一点。MCP 服务器的工具定义在代码里，而完整、权威的列表只存在于运行时——当客户端调用 tools/list 并取回每个工具的 schema 时。并没有一个可供指向的通用 mcp.yaml。
所以我们做了两个入口。
添加 MCP 契约的两种方式
粘贴它。 如果你已经有 tools/list 的输出，粘贴进来。Archyl 会校验它,并把每个工具——它的描述,以及它的输入参数渲染成一张易读的表格。
或者直接给我们 URL。 告诉 Archyl 你的 MCP 服务器在哪里,可选地加上一个访问令牌(作为请求头或查询参数),然后点击发现工具。Archyl 会连接、执行握手,并自动拉取每一个工具和参数。无需复制粘贴,也没有需要手工维护的文件。
实时发现如何工作——以及为什么安全
发现发生在你的浏览器中,而不是我们的服务器上。当你点击发现工具时,你的浏览器直接与你的 MCP 服务器通信。
这个选择很重要:
- 你的令牌永远不会离开你的浏览器。 Archyl 存储发现到的工具和连接信息——URL、传输方式、令牌放在哪里——但绝不存储令牌本身。
- 服务器端不会触及你的网络。 由于调用源自你的机器,无法把它指向别人的内部服务。整一类 SSRF(服务器端请求伪造)风险在这里根本不存在。
- 它能触及 localhost 和私有服务器。 在测试一个跑在你笔记本上或网络内部的服务器?它能工作,因为是你的浏览器看得到它。
唯一的取舍是 CORS:第三方服务器必须允许 Archyl 的来源,你的浏览器才能读取响应。对于你掌控的服务器,这只是一行配置;其余的,粘贴选项始终都在。
像其他契约一样,关联到你的架构
一旦进来,MCP 契约的行为就和其他契约一样。把它关联到托管该服务器的 container 或组件。浏览每个工具及其输入 schema。当服务器变化时重新发现它。它会显示在你的 REST 和 GraphQL 契约旁边,因为对于调用它的智能体来说,它是一个同样真实的 API。
这让你的 MCP 契约变成了真正新颖的东西:一张关于你的 AI 智能体被允许对系统某一部分做什么的地图——已记录、已关联、可审阅。
我们也用在自己身上
Archyl 本身就是一个 MCP 服务器——有 178 个工具,让你能从 Claude Code、Cursor 或任意 MCP 客户端来驱动你的架构。我们创建的第一个 MCP 契约就是我们自己的:把 Archyl 指向它自己的端点,发现全部 178 个工具,并关联到平台。我们的智能体接口面如今会自我记录。
试一试
打开任意项目,进入 API Contracts,新建一个,选择 MCP。粘贴你的 tools/list,或者填入一个 URL 并点击发现工具。
你的服务早已在和智能体对话。现在,你的架构知道它们在说什么。