Claude、Cursor、VS CodeなどのAIアシスタントをアーキテクチャドキュメントに接続

MCPサーバー

Archylは、AIアシスタントがアーキテクチャドキュメントと対話できるModel Context Protocol（MCP）サーバーを提供しています。これにより、AIを活用したアーキテクチャの探索とドキュメント作成が可能になります。

MCPとは？

Model Context Protocol（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パネルのMCPServerの「...」メニューをクリック
「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サーバーに url ではなく serverUrl を使用します。

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の設定を開く
Developer → MCP Servers に移動
「Add Server」をクリックして追加:

{
  "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」を検索して「Edit in settings.json」をクリック
以下を追加:

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

Warp

Warpを開き、Settings > MCP Servers に移動
「Add Server」をクリックして設定を貼り付け:

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

Warpを再起動して変更を適用

Windsurf

~/.codeium/windsurf/mcp_config.json のMCP設定ファイルを開く:

{
  "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`	ドキュメントを作成

会話の例

アーキテクチャの探索

あなた: 「ECプロジェクトにはどんなシステムがありますか？」

AI: list_systemsツールを使用 「ECプロジェクトには4つのシステムがあります: Web Store、Payment Service、Inventory System、Notification Service...」

要素の作成

あなた: 「Web Storeシステムにセッション管理用のRedis Cacheという新しいコンテナを追加して」

AI: create_containerツールを使用 「Web StoreシステムにRedis Cacheコンテナを作成しました。説明は「セッション管理用のインメモリキャッシュ」です。」

ドキュメント作成

あなた: 「MongoDBよりもPostgreSQLを選択した理由についてADRを作成して」

AI: create_adrツールを使用 「ADR-001: データベース技術の選定を作成しました。ACIDコンプライアンスとクエリの柔軟性を理由にPostgreSQLを選択した決定を記録しています...」

エンドポイント

Streamable HTTP（MCP）

https://api.archyl.com/mcp

このエンドポイントを使用して、AIアシスタントをArchylのアーキテクチャドキュメントに接続します。Streamable HTTPトランスポートプロトコルをサポートしています。

トラブルシューティング

接続に失敗する場合

APIキーが有効か確認
エンドポイントURLが正しいか確認
ネットワーク接続を確認

認証に失敗する場合

ヘッダー対応ツール: X-API-Key ヘッダーが正しく設定されているか確認
ヘッダー非対応ツール: URLに ?apiKey= クエリパラメータが含まれているか確認
APIキーの有効期限が切れていないか確認

ツールが見つからない場合

正しいツール名を使用しているか確認
APIキーに必要な権限があるか確認

Antigravity固有の問題

設定に url ではなく serverUrl を使用していることを確認
設定ファイルの場所は ~/.gemini/antigravity/mcp_config.json

OpenAI Codex固有の問題

~/.codex/config.toml のTOML構文が正しいことを確認
テーブル名として [mcp_servers.archyl] を使用

Warp固有の問題

Settings > MCP Servers で設定を管理
設定変更後にWarpを再起動

ベストプラクティス

具体的に指示する

AIにアーキテクチャの変更を依頼する際は、具体的に:

プロジェクト名を含める
要素タイプを指定する
説明を提供する

変更を確認する

AIが作成した要素は必ず確認:

名前と説明が正確か確認
リレーションシップが正しいか検証
必要に応じて更新

探索に活用する

MCPは以下の用途に最適:

大規模なアーキテクチャの素早い探索
初期ドキュメントの生成
システムに関する質問への回答

MCPサーバー - Archyl Docs