AIアシスタントは開発者の仕事を変革していますが、あなたのアーキテクチャドキュメンテーションを見ることはできません。MCPサーバーはそのギャップを埋めます。このガイドでは、MCPとは何か、なぜアーキテクチャにとって重要か、そしてArchylの56のMCPツールでClaudeやCursorから直接アーキテクチャをクエリ、作成、検証する方法を解説します。

MCPサーバーをアーキテクチャドキュメンテーションに活用する方法

AIコーディングアシスタントは不可欠なものになりました。Claude Codeは複雑なシステムのリファクタリングを支援します。Cursorは機能開発を加速します。GitHub Copilotは実装を提案します。しかし、これらのツールすべてに共通する盲点があります。あなたのアーキテクチャを知らないのです。

AIアシスタントに「User Serviceに新しいエンドポイントを追加して」と頼む時、あなたのUser ServiceがAuth ServiceとgRPCで通信し、PostgreSQLにデータを保存し、Kafkaにイベントをパブリッシュし、ADRに文書化された特定のセキュリティ要件を持っていることを知りません。AIは推測し、あなたが修正し、生産性向上の半分が失われます。

MCPサーバーはこれを解決します。AIアシスタントにアーキテクチャドキュメンテーションへの構造化されたアクセスを提供し、システム設計をクエリ可能でアクション可能なデータソースに変えます。このガイドでは、アーキテクチャドキュメンテーションにMCPサーバーを使用するために知るべきすべてを解説します。MCPとは何か、なぜ重要か、そしてArchylでの設定方法です。

MCP（Model Context Protocol）とは何か？

MCP（Model Context Protocol）は、AIアシスタントを外部ツールやデータソースに接続するためにAnthropicが作成したオープンスタンダードです。AIモデルが外部の機能を発見、呼び出し、結果を受け取るための構造化された方法を定義します。

MCPをユニバーサルアダプターと考えてください。MCP以前は、各AIアシスタントは外部ツールと統合するための独自の方法を持っていました。MCPはこれを標準化し、異なるAIアシスタント間で機能する単一のプロトコルを作成します。

MCPサーバーはMCPプロトコルを通じてツールのセットを公開するサービスです。各ツールには名前、説明、入力パラメータ、出力フォーマットがあります。AIアシスタントがMCPサーバーに接続すると、利用可能なツールを発見し、会話中に必要に応じてそれらを呼び出すことができます。

アーキテクチャドキュメンテーションにおいては、アーキテクチャモデルが、MCP互換のあらゆるAIアシスタントが使用できるクエリ可能で変更可能なツールのセットになることを意味します。AIはファイルをパースしたりシステム構造を推測したりする必要はなく、権威ある唯一の真実の源に直接クエリできます。

なぜアーキテクチャにMCPが必要か

アーキテクチャドキュメンテーションは、MCPが完璧に対処するいくつかのニーズの交差点にあります。

AI支援開発ではコンテキストがすべて

AI生成コードの品質は、AIが持つコンテキストの品質に直接比例します。AIアシスタントがアーキテクチャ（どのサービスが存在し、どう通信し、どの技術を使い、どの制約が適用されるか）を理解すると、システムに自然にフィットするコードを生成します。

アーキテクチャのコンテキストがなければ、AIアシスタントは仮定を立てます。サービスがgRPCを使っているのにREST APIを提案するかもしれません。アーキテクチャがサービスレイヤーを経由することを要求しているのに直接データベース接続を作るかもしれません。システムがイベント駆動通信を使っているのに同期呼び出しを提案するかもしれません。

MCPはAIアシスタントに実際のアーキテクチャへのアクセスを与え、これらのミスマッチを排除します。

アーキテクチャドキュメンテーションは構造化データ

フリーフォームのドキュメンテーション（Wiki、Confluenceページ、READMEファイル）とは異なり、C4フレームワークでモデル化されたアーキテクチャドキュメンテーションは本質的に構造化されています。システムにはコンテナが含まれます。コンテナにはコンポーネントが含まれます。要素にはテクノロジー、説明、リレーションシップがあります。ADRにはステータスと影響する要素があります。

この構造はMCPツールに自然にマッピングされます。各タイプのアーキテクチャ要素がクエリ可能なエンティティになります。各操作（list、get、create、update）がツールになります。AIアシスタントは開発者がファイルシステムをナビゲートするのと同じ方法でアーキテクチャモデルをナビゲートできます。

ドキュメンテーションは双方向であるべき

ほとんどのドキュメンテーションツールはAPIの観点からは読み取り専用です。ドキュメントを表示できますが、変更するには特定のアプリケーションを開く必要があります。MCPは双方向の対話を可能にします。AIアシスタントはアーキテクチャモデルの読み取りと書き込みの両方ができます。

これは、AIアシスタントがアーキテクチャをクエリするだけでなく、変更を提案できることを意味します -- 新しいコンポーネントの追加、リレーションシップの作成、ADRのドラフトなどです。開発者はこれらの変更をレビューして承認しますが、AIがドキュメンテーションの更新という機械的な作業を行います。

ArchylのMCPサーバー：アーキテクチャのための56のツール

Archylはアーキテクチャドキュメンテーション用の最も包括的なMCPサーバー実装の一つを提供しています。アーキテクチャモデリングの全範囲にわたる56のツールで、C4モデルのクエリからリリース管理やドリフト追跡まですべてをカバーしています。

ツールカテゴリの概要を示します。

C4モデルのクエリ

コアクエリツールにより、AIアシスタントはあらゆるレベルでアーキテクチャを探索できます。

list_systems / get_project_c4_model -- プロジェクト内のすべてのSoftware Systemを発見
list_containers / list_components -- C4階層をナビゲート
list_relationships -- 要素間の接続を理解
get_element_technologies -- 任意の要素の技術スタックを確認
get_element_owners -- 誰が何を所有しているかを把握

これらのツールにより、アーキテクチャに関する自然言語のクエリが可能になります。「Order Serviceはどのデータベースに依存しているか？」と聞くと、AIはOrder Serviceのリレーションシップをリストアップし、データベースコンテナでフィルタリングし、正確な回答を返すことができます。

アーキテクチャ要素の管理

書き込みツールにより、AIアシスタントはアーキテクチャモデルを変更できます。

create_system / update_system / delete_system -- Software Systemの管理
create_container / update_container / delete_container -- コンテナの管理
create_component / update_component / delete_component -- コンポーネントの管理
create_relationship / update_relationship / delete_relationship -- 接続の管理

これらのツールは、開発中にドキュメンテーションを最新に保つのに特に強力です。コードベースに新しいサービスを追加する際、AIアシスタントに対応するコンテナをアーキテクチャモデルに追加し、テクノロジーを設定し、適切なリレーションシップを作成するよう依頼できます -- すべてIDEを離れることなく。

Architecture Decision Records

ADRツールにより、意思決定のドキュメンテーションがAIワークフローに統合されます。

list_adrs / get_adr -- 既存の意思決定をクエリ
create_adr / update_adr -- 新しいADRの作成または既存の更新
link_adr_to_element -- 意思決定を影響する要素に接続

AIアシスタントと技術選択を議論している際、関連する意思決定のために既存のADRを確認し、現在の意思決定のために新しいADRをドラフトし、関連するアーキテクチャ要素にリンクすることができます。

APIコントラクトとEvent Channel

統合ドキュメンテーションツールはサービス境界をカバーします。

list_api_contracts / create_api_contract -- API仕様の管理
list_event_channels / create_event_channel -- 非同期通信のモデル化
link_api_contract / link_event_channel -- 仕様を要素に接続

これらのツールはアーキテクチャと実装の接続を維持します。新しいAPIエンドポイントを作成する際、AIはそのサービスにAPIコントラクトが存在するかチェックし、更新を提案できます。

ドキュメンテーションとコラボレーション

より広いドキュメンテーションツールはチームワークフローをサポートします。

create_documentation / update_documentation -- プロジェクトドキュメントの管理
create_comment / list_comments -- アーキテクチャ要素への注釈
list_flows / create_flow -- ユーザーおよびシステムフローの文書化
get_drift_score / compute_drift_score -- ドキュメンテーション精度のチェック

リリースとメトリクス

運用ツールはアーキテクチャをデリバリーに接続します。

create_release / list_releases -- デプロイメントの追跡
get_dora_metrics / get_dora_trend -- エンジニアリングパフォーマンスの測定
list_environments -- デプロイメントターゲットの把握

実例：MCPの活用

開発者がArchylのMCPサーバーを日常のワークフローで使用する具体的な例を示します。

例1：Claude Codeからシステムをクエリ

Claude Codeで作業中に、変更を加える前にアーキテクチャを理解する必要がある場合：

あなた: プロジェクトにはどんなシステムとコンテナがありますか？

Claude: アーキテクチャを確認します。
[list_systemsを呼び出し、各システムのlist_containersを呼び出す]

プロジェクト「E-Commerce Platform」には3つのシステムがあります：
1. E-Commerce Platform (software_system)
   - API Gateway (Go, Kong)
   - User Service (Go, PostgreSQL)
   - Order Service (Java, PostgreSQL)
   - Product Service (Node.js, MongoDB)
   - Notification Service (Python, Redis)
   - Event Bus (Kafka)

2. Stripe (external_system)
   - 決済処理ゲートウェイ

3. SendGrid (external_system)
   - トランザクションメールサービス

AIはハルシネーションではなく、文書化されたアーキテクチャからの実際のデータを返します。

例2：Cursorからコンポーネントを作成

サービスに新しいモジュールを追加して文書化したい場合：

あなた: API GatewayにRateLimiterコンポーネントを追加しました。
     RedisとGolangのgolang.org/x/time/rateライブラリを使用しています。
     アーキテクチャに追加できますか？

Cursor: C4モデルに追加します。
[create_componentを呼び出し、name="RateLimiter",
 container="API Gateway", technologies=["Redis", "Go"]]
[RateLimiterからRedisコンテナへの
 create_relationshipを呼び出す]

完了しました。API GatewayにRateLimiterコンポーネントを追加し、
Redisコンテナへのリレーションシップを作成しました。

IDEを離れることなく、数秒でドキュメンテーションが更新されます。

例3：リファクタリング前のドリフトチェック

大規模なリファクタリングの前に、ドキュメンテーションの精度を知りたい場合：

あなた: 現在のドリフトスコアは？文書化されていないサービスはありますか？

Claude: 確認します。
[get_drift_scoreを呼び出す]
[get_drift_detailsを呼び出す]

ドリフトスコアは78/100（良好）です。

検出された問題：
- Search Serviceは本番で稼働していますが、
  C4モデルに文書化されていません
- Analytics ServiceにはData Warehouseへの
  2つの文書化されていないリレーションシップがあります
- API Gatewayの技術リストに「Redis」が
  不足しています（最近レート制限用に追加）

修正しましょうか？

AIは何が古くなっているかを正確に特定し、自動的に修正できます。

例4：ADRのドラフト

内部サービス通信をRESTからgRPCに切り替える設計議論中：

あなた: 内部サービス通信をRESTからgRPCに切り替えることを
     検討しています。ADRをドラフトして、これに関する
     既存の意思決定があるか確認してもらえますか？

Claude: まず既存のADRを確認します。
[list_adrsを呼び出す]

関連するADRが1つ見つかりました：
- ADR-007: 「すべての内部APIにRESTを使用する」（Status: Accepted）
  これは18ヶ月前に決定されました。

それを置き換える新しいADRをドラフトします。
[create_adrを呼び出し、title="内部通信を
 RESTからgRPCに移行"]

ADR-015を作成しました：
- Context: 現在のRESTベースの通信は
  シリアライゼーションのオーバーヘッドが...
- Decision: すべての新しい内部サービス通信に
  Protocol Buffers付きgRPCを採用...
- Status: Proposed
- Supersedes: ADR-007

影響するサービスにリンクしましょうか？

AIは関連する意思決定を確認し、新しいADRをドラフトし、関連するアーキテクチャ要素にリンクすることを提案します。

例5：変更前の影響を理解する

サービスを変更する前に影響範囲を理解したい場合：

あなた: Order Serviceのデータベーススキーマを変更する必要があります。
     他に何がOrder Serviceに依存していますか？

Claude: 依存関係をトレースします。
[Order Serviceでフィルタリングしたlist_relationshipsを呼び出す]
[依存要素のget_element_ownersを呼び出す]

Order Serviceには以下の依存元があります：
- API Gateway -> Order Service (REST, 注文管理)
- Order Service -> Payment Service (gRPC, 決済処理)
- Order Service -> Event Bus (OrderCreated,
  OrderUpdated, OrderCancelledをパブリッシュ)
- Notification ServiceがEvent BusからOrderイベントをコンシューム
- Analytics ServiceがEvent BusからOrderイベントをコンシューム

所有チーム：
- Order Service: Platform Team
- Payment Service: Payments Team
- Notification Service: Platform Team
- Analytics Service: Data Team

スキーマ変更はPayment Service（直接依存）と
Orderイベントのすべてのコンシューマーに影響する可能性があります。
Payments TeamとData Teamとの調整をお勧めします。

ArchylのMCPサーバーのセットアップ

ArchylのMCPサーバーのセットアップは数分で完了します。最も一般的なAIアシスタント向けの設定方法を示します。

Claude Code向けセットアップ

Claude Codeの設定にArchyl MCPサーバーを追加します。

{
  "mcpServers": {
    "archyl": {
      "url": "https://mcp.archyl.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

設定後、Claude Codeは56のツールすべてを自動的に発見し、あらゆる会話で使用できます。

Cursor向けセットアップ

CursorはMCPサーバーを設定からサポートしています。MCPセクションにArchylを追加します。

{
  "mcpServers": {
    "archyl": {
      "url": "https://mcp.archyl.com/sse",
      "headers": {
        "Authorization": "Bearer YOUR_ARCHYL_API_KEY"
      }
    }
  }
}

設定追加後、Cursorを再起動します。ArchylのツールがMCPツールリストに表示され、コード生成とリファクタリング中にCursorが使用できるようになります。

その他のMCP互換ツール向けセットアップ

MCPプロトコルをサポートするあらゆるツールがArchylのMCPサーバーに接続できます。サーバーはツール発見を備えた標準MCPエンドポイントを公開するので、互換クライアントは利用可能なツールを自動的に検出してリストアップします。

APIキー生成

Archylダッシュボードからmcp APIキーを生成します。

組織設定に移動
APIセクションに進む
適切な権限を持つ新しいAPIキーを作成
キーをMCPサーバー設定にコピー

異なるユースケース（例：Claude Code用とCI/CD用）ごとに別々のAPIキーを作成し、独立してローテーションできるようにすることをお勧めします。

MCP駆動アーキテクチャドキュメンテーションのベストプラクティス

読み取り専用から始める

MCPサーバーを最初にセットアップする際は、読み取り専用のクエリから始めてください。書き込み操作を有効にする前に、AIアシスタントのアーキテクチャ探索能力に慣れてください。これによりツールの精度と信頼性への信頼が構築されます。

AI生成の変更をレビューする

AIアシスタントがアーキテクチャ要素を作成または変更する場合、最終的なものと見なす前に変更をレビューしてください。Archylの履歴とバージョン機能により、何が変わったかを確認し、必要に応じてロールバックできます。AIは強力なアシスタントですが、アーキテクチャ上の意思決定には常に人間の監視が必要です。

MCPとArchitecture as Codeを組み合わせる

MCPとArchitecture as Codeは補完的です。開発中のインタラクティブなクエリと素早い更新にはMCPを使用します。コードレビューを通過する権威あるバージョン管理された定義には archyl.yaml ファイルを使用します。2つのアプローチは互いを強化します。

コードレビューでMCPを使用する

コードレビュー中に、AIアシスタントにコード変更が文書化されたアーキテクチャと整合しているかチェックするよう依頼します。「この新しいAPIエンドポイントはこのサービスに文書化されたAPIコントラクトと一致していますか？」または「これらのデータベースクエリは文書化されている通りサービスレイヤーを経由していますか？」AIはリアルタイムでアーキテクチャモデルに対してコードを検証できます。

チームに利用可能なツールを教える

MCP採用の最大の障壁は認知度です。ほとんどの開発者はAIがアーキテクチャについてどのような質問に答えられるかを認識していません。例を共有し、有用なクエリのチートシートを作成し、チームミーティングでMCPワークフローを実演してください。

AI駆動アーキテクチャドキュメンテーションの未来

MCPサーバーは、チームがアーキテクチャドキュメンテーションとどう対話するかの根本的な転換を表しています。ドキュメンテーションが開発者が読む（あるいはより多くの場合、読まない）受動的な成果物であるのではなく、開発ワークフローのアクティブな参加者になります。

AIアシスタントがコード生成前にアーキテクチャをクエリし、変更後に適合性をチェックし、システムの進化に合わせてドキュメンテーションを更新できるようになると、「システムでの作業」と「システムの文書化」の間の障壁が消えます。

アーキテクチャドキュメンテーションは別途メンテナンスするものではなくなり、あらゆる開発のやりとりに織り込まれるものになります。AIに聞くすべての質問、行うすべてのコード変更、行うすべての設計議論 -- これらすべてがアーキテクチャモデルによって情報を提供され、そこに反映されるようになります。

これがArchylが構築している未来です。MCPサーバーはAI搭載開発と構造化アーキテクチャドキュメンテーションの橋渡しです。そしてアーキテクチャモデリングの全範囲をカバーする56のツールにより、チームが必要とするあらゆるワークフローをサポートするのに十分な包括性を備えています。

ArchylのMCPサーバーを始めましょう。AIアシスタントに不足していたアーキテクチャのコンテキストを提供してください。

MCPサーバーをアーキテクチャドキュメンテーションに活用する方法 - Archyl Blog