MCP 服务器

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

什么是 MCP？

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

列出和浏览您的项目
创建和修改架构元素
生成文档
回答关于您架构的问题

支持的工具

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

身份认证

MCP 服务器需要 API 密钥进行身份认证。根据您使用的工具：

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

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

设置

Antigravity

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

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

重启 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

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

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

重启 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

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

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

Warp

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

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

重启 Warp 以应用更改

Windsurf

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

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

重启 Windsurf 以应用更改。

可用工具

连接后，您的 AI 助手可以使用以下工具：

项目管理

工具	描述
`list_projects`	列出所有项目
`get_project`	获取项目详情
`create_project`	创建新项目

架构元素

工具	描述
`list_systems`	列出项目中的系统
`create_system`	创建新系统
`list_containers`	列出系统中的容器
`create_container`	创建新容器
`list_components`	列出容器中的组件
`create_component`	创建新组件

关系

工具	描述
`list_relationships`	列出关系
`create_relationship`	创建关系

文档

工具	描述
`list_adrs`	列出架构决策记录
`create_adr`	创建新 ADR
`list_docs`	列出文档
`create_doc`	创建文档

对话示例

探索架构

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

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

创建元素

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

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

文档

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

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

端点

流式 HTTP（MCP）

https://api.archyl.com/mcp

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

故障排除

连接失败

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

认证失败

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

工具未找到

确保使用了正确的工具名称
检查您的 API 密钥是否具有所需权限

Antigravity 相关问题

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

OpenAI Codex 相关问题

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

Warp 相关问题

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

最佳实践

描述要具体

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

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

审查变更

始终审查 AI 创建的元素：

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

用于探索

MCP 非常适合：

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

MCP 服务器 - Archyl Docs