API Contract としての MCP ツール：エージェントができることをドキュメント化する
数か月前、私たちは API Contracts をリリースしました。OpenAPI、gRPC、GraphQL、AsyncAPI の仕様を、それらを実装・利用する C4 要素に直接リンクするものです。考え方はシンプルでした。インターフェースの正確で機械可読な記述は、誰も更新しない Notion ページではなく、アーキテクチャの中にあるべきだ、ということです。
まだカバーしていないインターフェースが一つ残っていました。最も新しいもの。あなたのサービスが、他のサービスにではなく、ますます AI エージェントに公開しているもの ── MCP です。
MCP サーバーは一連のツールを公開します。それぞれに名前、説明、そして入力用の JSON Schema があります。これは契約です。エージェントがあなたのシステムに対して何をしてよいかを決める契約です。そして今日まで、それはアーキテクチャドキュメントの中で完全に不可視でした。
もう違います。MCP は Archyl の第一級の API Contract タイプになりました ── HTTP、gRPC、GraphQL、AsyncAPI に続く 5 番目です。
難しいところ：MCP ツールはファイルの中に存在しない
他の 4 つの契約タイプはある前提を共有しています ── リポジトリにスペックファイルがある、というものです。openapi.yaml。schema.graphql。Archyl をそこに向ければ、私たちが描画します。
MCP はこれを破ります。MCP サーバーのツールはコードの中で定義され、完全で正式な一覧は、クライアントが tools/list を呼び出して各ツールのスキーマを受け取る実行時にのみ存在します。指し示せる普遍的な mcp.yaml は存在しません。
そこで、入り口を 2 つ用意しました。
MCP 契約を追加する 2 つの方法
貼り付ける。 すでに tools/list の出力があるなら、貼り付けてください。Archyl がそれを検証し、各ツール ── 説明と入力パラメータを読みやすい表として描画します。
または URL を渡すだけ。 MCP サーバーの場所を Archyl に伝え、必要ならアクセストークンを（ヘッダーまたはクエリパラメータとして）追加し、ツールを検出をクリックします。Archyl が接続し、ハンドシェイクを実行し、すべてのツールとパラメータを自動的に取り込みます。コピー&ペーストも、手作業で保守するファイルも不要です。
ライブ検出の仕組み ── そしてなぜ安全なのか
検出は私たちのサーバーではなく、あなたのブラウザの中で行われます。ツールを検出をクリックすると、あなたのブラウザが MCP サーバーと直接やり取りします。
この選択には意味があります。
- トークンがブラウザから出ることは決してありません。 Archyl は検出したツールと接続情報 ── URL、トランスポート、トークンの送り先 ── を保存しますが、トークンそのものは決して保存しません。
- サーバー側からあなたのネットワークへのアクセスはありません。 呼び出しはあなたのマシンから始まるため、他人の内部サービスに向けることはできません。SSRF 系のリスクのカテゴリ全体が、ここには単に存在しません。
- localhost やプライベートサーバーにも届きます。 ノート PC やネットワーク内で動くサーバーをテストしていますか？ あなたのブラウザがそれを見られるので、機能します。
唯一のトレードオフは CORS です。サードパーティのサーバーは、あなたのブラウザが応答を読めるように Archyl のオリジンを許可する必要があります。あなたが管理するサーバーなら設定 1 行で済みます。それ以外は、貼り付けオプションが常に用意されています。
他のすべての契約と同じく、アーキテクチャにリンクされる
いったん取り込まれれば、MCP 契約は他の契約と同じように振る舞います。サーバーをホストする container やコンポーネントにリンクしてください。各ツールとその入力スキーマを閲覧できます。サーバーが変われば再検出できます。REST や GraphQL の契約の隣に表示されます ── それを呼び出すエージェントにとっては、同じく実在する API だからです。
これにより、あなたの MCP 契約は本当に新しいものになります。システムの特定の部分に対して AI エージェントが何をしてよいかのマップ ── ドキュメント化され、リンクされ、レビュー可能なものです。
私たち自身でも使っています
Archyl 自体が MCP サーバーです ── Claude Code、Cursor、あるいは任意の MCP クライアントからアーキテクチャを操作できる 178 個のツールがあります。私たちが最初に作成した MCP 契約は自分自身のものでした。Archyl を自身のエンドポイントに向け、178 個のツールすべてを検出し、プラットフォームにリンクする。私たちのエージェント面は、いまや自らをドキュメント化しています。
試してみる
任意のプロジェクトを開き、API Contracts に移動し、新規作成して MCP を選びます。tools/list を貼り付けるか、URL を入力してツールを検出を押してください。
あなたのサービスはすでにエージェントと話しています。いまや、あなたのアーキテクチャはその会話の内容を知っています。