MCPサーバー

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

MCPとは？

Model Context Protocol（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サーバーに 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

1. Claude Desktopの設定を開く
2. Developer → MCP Servers に移動
3. 「Add Server」をクリックして追加:

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

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

Warp

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

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

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

Windsurf

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

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

Windsurfを再起動して変更を適用します。

ツールリファレンス

サーバーは181のツールを公開しています。予測しやすい命名規則に従っているため、アシスタントは通常、適切なツールを推測できます:

プロジェクトスコープのツールの多くは projectId を受け取り、要素スコープのツールは elementId と elementType（C4レベル: 1 = システム、2 = コンテナ、3 = コンポーネント、4 = コード）を受け取ります。まずアシスタントに list_projects を呼び出すよう依頼してください。必要なIDはそこから取得されます。

クライアントはこの一覧を tools/list 経由で自動的に検出するため、常にサーバーと同期しています。以下の表は、何を依頼すべきかを人が判断するためのものです。

ツールプロファイル

189 個のツールは、限定されたタスクを行うコーディングエージェントに必要な数を超えており、すべてを公開するとコンテキストを消費します。MCP の URL に ?profile=coding を付ける(またはヘッダー X-Archyl-Tool-Profile: coding を送る)と、タスクに絞ったコンテキスト、Harness ワークセッションのループ、適合性/差分チェックの 16 ツールに絞り込めます。パラメータを省略する(または profile=full を使う)と完全なカタログになります。

エージェントコンテキスト (4)

まずはここから: 何度も呼び出す代わりに、1回の呼び出しでアシスタントにアーキテクチャの全体像を伝えられます。

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)

会話の例

アーキテクチャの探索

あなた: 「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を選択した決定を記録しています...」

コードを書く前に

あなた: 「チェックアウトフローにレート制限を追加しようとしています。何を知っておくべきですか？」

AI: find_relevant_contextとimpact_ofを使用 「チェックアウトはAPI GatewayとOrdersサービスに関わります。ゲートウェイの変更は下流の6つのコンテナに影響します。ADR-014ではスロットリングにRedisを使用することがすでに定められており、コンフォーマンスルールによりレガシーのSessionストアへの新規依存は禁止されています...」

ガバナンスのチェック

あなた: 「ドキュメント化されたアーキテクチャからドリフトしていますか？」

AI: get_drift_scoreとrun_conformance_checkを使用 「ドリフトスコアは82%です（先月の91%から低下）。違反が2件あります: Searchサービスが直接Ordersデータベースを呼び出しており、Paymentsが未承認のHTTPクライアントを使用しています...」

エンドポイント

Streamable HTTP（MCP）

https://api.archyl.com/mcp

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

トラブルシューティング

接続に失敗する場合

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

認証に失敗する場合

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

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

• 正しいツール名を使用しているか確認してください — ツールリファレンスを参照するか、クライアントにツール一覧の更新を依頼してください
• 一部のクライアントは tools/list をキャッシュします。アップグレード後はクライアントを再起動してください

書き込みツールが拒否される場合

• create_*、update_*、delete_*、import_dsl には書き込みスコープを持つAPIキーが必要です。読み取り専用のキーでは list_* と get_* しか呼び出せません
• サブスクリプションプランを確認してください: 一部の機能（Webhook、マーケットプレイス連携、マネージドエージェントの実行）はプランによって制限されています

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は以下の用途に最適:

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