MCP 服务器

Archyl 提供模型上下文协议（MCP）服务器，允许 AI 助手与您的架构文档进行交互。这使得强大的 AI 驱动的架构探索和文档编写成为可能。

什么是 MCP？

模型上下文协议（MCP）是一个开放协议，使 AI 助手能够安全地访问外部工具和数据源。通过 Archyl 的 MCP 服务器，您的 AI 助手可以：

• 浏览和查询您的项目及其完整的 C4 模型
• 创建和修改架构元素、关系和图表
• 读取和编写 ADR、文档、API 契约和事件通道
• 在编写代码之前检查合规性规则、漂移评分、DORA 指标和归属信息
• 跟踪发布、变更请求、评论和历史记录

支持的客户端

Archyl 的 MCP 服务器支持以下客户端：

• Antigravity - Google 的 AI 驱动 IDE
• Claude Code - Anthropic 的 CLI 工具
• Claude Desktop - Claude 的桌面应用程序
• Cursor - AI 优先的代码编辑器
• OpenAI Codex - OpenAI 的 AI 编程助手
• VS Code - 配合 GitHub Copilot Chat
• Warp - 集成 AI 的现代终端
• Windsurf - Codeium 的 AI 驱动 IDE

身份认证

API 密钥（推荐）

大多数客户端使用 API 密钥进行身份认证。根据您使用的工具：

• 支持自定义头的工具（Claude Code、Cursor、Warp、Windsurf、Antigravity）：使用 X-API-Key 头
• 不支持自定义头的工具（Claude Desktop、VS Code、OpenAI Codex）：在 URL 中使用 ?apiKey=YOUR_API_KEY 查询参数

从您的个人资料 → API 密钥页面生成 API 密钥。

密钥的权限范围决定了助手能做什么：只读密钥可以调用所有 list_* 和 get_* 工具，而 create_*、update_*、delete_* 和 import_dsl 需要具有写入权限范围的密钥。给您的智能体一个只读密钥，是让它探索您的架构而无法修改架构的最简单方式。

OAuth 2.1

服务器还实现了带动态客户端注册的 OAuth 2.1，适用于通过浏览器登录而非粘贴密钥进行连接的客户端（mcp:read 和 mcp:write 权限范围与上述 API 密钥权限范围一致）。将此类客户端指向同一端点，它会通过以下地址自动发现认证流程：

https://api.archyl.com/.well-known/oauth-authorization-server
https://api.archyl.com/.well-known/oauth-protected-resource

设置

Antigravity

1. 打开 Antigravity 并点击 Agent 面板中的 "..." 菜单
2. 选择 "MCP Servers" > "Manage MCP Servers" > "View raw config"
3. 添加到 ~/.gemini/antigravity/mcp_config.json：

{
  "mcpServers": {
    "archyl": {
      "serverUrl": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

4. 重启 Antigravity 以应用更改

注意：Antigravity 对 HTTP 类型的 MCP 服务器使用 serverUrl 而非 url。

Claude Code

在项目根目录创建 .mcp.json 文件：

{
  "mcpServers": {
    "archyl": {
      "type": "http",
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

运行 Claude Code — 它会自动检测 MCP 服务器。

Claude Desktop

1. 打开 Claude Desktop 设置
2. 导航到开发者 → MCP 服务器
3. 点击"添加服务器"并添加：

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp?apiKey=YOUR_API_KEY"
    }
  }
}

4. 重启 Claude Desktop

注意：Claude Desktop 远程连接器不支持自定义头，因此 API 密钥必须作为 URL 查询参数传递。

Cursor

在项目中创建 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

重启 Cursor 以加载 MCP 服务器。

OpenAI Codex

打开或创建 ~/.codex/config.toml 并添加：

[mcp_servers.archyl]
url = "https://api.archyl.com/mcp?apiKey=YOUR_API_KEY"

重启 Codex CLI 或 IDE 以应用更改。

VS Code

1. 打开 VS Code 设置（Cmd/Ctrl + ,）
2. 搜索 "MCP" 并点击 "在 settings.json 中编辑"
3. 添加：

{
  "mcp": {
    "servers": {
      "archyl": {
        "url": "https://api.archyl.com/mcp?apiKey=YOUR_API_KEY"
      }
    }
  }
}

Warp

1. 打开 Warp 并前往设置 > MCP 服务器
2. 点击"添加服务器"并粘贴配置：

{
  "archyl": {
    "url": "https://api.archyl.com/mcp",
    "headers": {
      "X-API-Key": "YOUR_API_KEY"
    }
  }
}

3. 重启 Warp 以应用更改

Windsurf

打开 MCP 配置文件 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "archyl": {
      "serverUrl": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

重启 Windsurf 以应用更改。

工具参考

服务器提供 189 个工具。它们遵循可预测的命名规范，因此助手通常能够猜到正确的工具：

大多数项目范围的工具需要 projectId；元素范围的工具需要 elementId 和 elementType（C4 层级：1 = 系统，2 = 容器，3 = 组件，4 = 代码）。请先让您的助手调用 list_projects —— 它会从中获取所需的 ID。

您的客户端会通过 tools/list 自动发现此列表，因此它始终与服务器保持同步。下面的表格供人工查阅，以决定应该提出什么请求。

工具配置文件

189 个工具超出了执行限定任务的编码代理所需——全部公开会消耗上下文。在 MCP URL 后附加 ?profile=coding(或发送 X-Archyl-Tool-Profile: coding 请求头),即可将工具面缩减为 16 个:任务聚焦的上下文、Harness 工作会话循环以及一致性/差异检查。省略该参数(或使用 profile=full)则获得完整目录。

智能体上下文 (4)

从这里开始：这些工具只需一次调用，就能让助手掌握整体架构全貌，无需多次调用。

Harness 工作会话 (8)

面向编码代理的受治理工作循环:声明一个工作单元以获取聚焦的上下文和建议性锁,工作期间发送心跳,并以可开启架构变更请求的结果收尾。 另有项目记忆:为后续工作者记住事实,并召回先前会话学到的内容。

项目 (7)

组织与团队 (5)

C4 元素 (15)

系统（第 1 层）、容器（第 2 层）、组件（第 3 层）和代码元素（第 4 层）。

关系 (4)

图表布局与叠加层 (5)

文档 (11)

架构决策记录 (6)

API 契约 (8)

OpenAPI、gRPC、GraphQL、AsyncAPI 和 MCP 工具契约。

事件通道 (8)

流程与白板 (8)

评论与讨论 (11)

归属 (6)

技术与技术雷达 (10)

发布与环境 (10)

架构变更请求 (6)

合规性规则 (9)

漂移检测 (4)

DORA 指标、ROI 与预测 (4)

历史记录与时间旅行 (5)

洞察 (3)

市场与小组件 (15)

Webhook (7)

组织级架构 (9)

跨项目视图和组织级制品。

架构即代码 (1)

对话示例

探索架构

您："我的电商项目中有哪些系统？"

AI：使用 list_systems 工具 "您的电商项目有 4 个系统：网上商店、支付服务、库存系统和通知服务……"

创建元素

您："在网上商店系统中添加一个名为 Redis 缓存的新容器，用于会话存储"

AI：使用 create_container 工具 "我已经在网上商店系统中创建了 Redis 缓存容器，描述为'用于会话存储的内存缓存'。"

文档

您："为我们选择 PostgreSQL 而非 MongoDB 的决策创建一个 ADR"

AI：使用 create_adr 工具 "我已经创建了 ADR-001：数据库技术选型，记录了选择 PostgreSQL 的决策，因为它具有 ACID 合规性和灵活的查询能力……"

编写代码之前

您："我准备为结账流程添加限流功能。我需要了解什么？"

AI：使用 find_relevant_context 和 impact_of 工具 "结账流程涉及 API 网关和订单服务。修改网关会影响 6 个下游容器。ADR-014 已经规定使用 Redis 进行限流，并且有一条合规性规则禁止新增对旧版会话存储的依赖……"

治理检查

您："我们是否偏离了已记录的架构？"

AI：使用 get_drift_score 和 run_conformance_check 工具 "漂移评分为 82%（上个月为 91%，有所下降）。存在两处违规：搜索服务直接调用订单数据库，支付服务使用了未经批准的 HTTP 客户端……"

端点

流式 HTTP（MCP）

https://api.archyl.com/mcp

使用此端点将您的 AI 助手连接到 Archyl 的架构文档。它支持流式 HTTP 传输协议。

故障排除

连接失败

• 检查您的 API 密钥是否有效
• 确保端点 URL 正确
• 检查网络连接

认证失败

• 对于支持自定义头的工具：验证 X-API-Key 头是否正确设置
• 对于不支持自定义头的工具：验证 URL 中的 ?apiKey= 查询参数
• 确保您的 API 密钥未过期

工具未找到

• 确保使用了正确的工具名称 —— 参见工具参考，或让您的客户端刷新其工具列表
• 某些客户端会缓存 tools/list；升级后请重启客户端

写入工具被拒绝

• create_*、update_*、delete_* 和 import_dsl 需要具有写入权限范围的 API 密钥 —— 只读密钥只能调用 list_* 和 get_*
• 检查您的订阅套餐：某些功能（Webhook、市场连接、托管智能体运行）受套餐限制

Antigravity 相关问题

• 确保在配置中使用 serverUrl（而非 url）
• 配置文件位置为 ~/.gemini/antigravity/mcp_config.json

OpenAI Codex 相关问题

• 确保 ~/.codex/config.toml 中的 TOML 语法正确
• 使用 [mcp_servers.archyl] 作为表名

Warp 相关问题

• 导航到设置 > MCP 服务器管理配置
• 更改配置后重启 Warp

最佳实践

描述要具体

当要求 AI 修改架构时，请具体说明：

• 包含项目名称
• 指定元素类型
• 提供描述

审查变更

始终审查 AI 创建的元素：

• 检查名称和描述是否准确
• 验证关系是否正确
• 根据需要进行更新

用于探索

MCP 非常适合：

• 快速探索大型架构
• 生成初始文档
• 回答有关系统的问题