MCPサーバーにもOpenAPIのような静的コントラクトが必要だ: CiscoがAPIエンジニアリングの知見を持ち込んだ理由

8月4日、Ciscoが「Beyond the Protocol: Applying API Engineering Practices to MCP Servers」と題した記事を公開した。この記事では、MCPサーバーにAPIエンジニアリングの知見（バージョン管理・リンティング・ドキュメント生成）を適用するための実践的アプローチについて詳しく紹介されている。

MCPはランタイムの問題を解いたが、ライフサイクルの問題は残った

MCP（Model Context Protocol）は、Anthropicが2024年末にオープン標準として公開した、AIアプリケーションと外部ツール・データソースを接続するためのプロトコルだ。AIクライアントが接続先サーバーに「何ができるか」を動的に問い合わせ、ツールを発見して使う——このランタイムの動的ディスカバリーモデルはエージェント用途に適している。

しかし、Cisco DevNetが指摘するのは「ランタイムの前後にある問題」だ。

このサーバーを信頼して接続してよいか、という判断は人間がランタイムの前に行う
ドキュメントパイプラインは、ランタイムを待たずに構造化された入力を必要とする
ガバナンスプロセスはバージョン管理されたアーティファクトを必要とする
レビュープロセスには、リントでき、比較でき、承認でき、公開できる何かが必要だ

MCPの仕様はこのギャップを埋めていない。これはRESTとOpenAPIの関係で何年もかけて解決してきた問題と、構造的に同じだとCiscoは言う。

核心：「MCP Description」フォーマット

Cisco DevNetが社内で育てたのがMCP Descriptionと呼ぶ静的フォーマットだ。コンセプトはOpenAPIと同じ——「実装」ではなく「契約（コントラクト）」を記述する機械可読なドキュメントである。

現時点のフォーマットバージョンは**mcpdesc: 0.7.0**であり、まだドラフト段階にある。エンタープライズ環境への本格採用を検討する場合、仕様が今後変更される可能性を織り込んだ上で評価することが望ましい。

以下は実際のサンプルだ。YAMLで記述され、OpenAPIに慣れた開発者には直感的に読める：

mcpdesc: 0.7.0
info:
  title: Search MCP Server
  version: 1.2.0
  description: MCP server exposing search tools for AI assistants.
server:
  name: Search
  type: remote
transports:
  - type: streamable-http
    url: https://api.example.com/mcp
tools:
  - name: search
    title: Search content
    description: Execute a search query and return matching results.
    inputSchema:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: Search query string.
    outputSchema:
      type: object
      properties:
        results:
          type: array
          description: List of matching results.
          items:
            type: object
            properties:
              title:
                type: string
              snippet:
                type: string
              url:
                type: string

このドキュメントには、サポートするトランスポート、ツール一覧、プロンプト、リソース、入出力スキーマ、認証要件、バージョン情報、サポート情報が含まれる。ソースコントロールに保存し、プルリクエストでレビューし、リリース間で差分を取れる——OpenAPIが担ってきた役割をMCPサーバーに適用するための「欠けていたアーティファクト」だ。

ツールチェーンが実現すること

フォーマットが定まると、その周辺ツールが意味を持つ。Ciscoが社内で構築したのが mcpcontract CLI（後にmcptoolkit-contractとして公開）で、稼働中のMCPサーバーに接続してMCP Descriptionを生成する。生成されたDescriptionはリンティング・差分検出・チェンジログ生成・ドキュメント生成・インベントリ管理といった後続ワークフローへの入力として機能する。

Live MCP server
      │
      ▼
`mcpcontract` dump
      │
      ▼
MCP Description
      │
      ├── linting and review
      ├── diff and breaking-change detection
      ├── changelog generation
      ├── documentation generation
      └── inventory and publication workflows

v1.0.0とv1.1.0のDescriptionを比較すれば、追加・削除されたツール、変更されたスキーマ、破壊的変更の有無、バージョン番号の妥当性、変更履歴に記載すべき内容が自動で把握できる。

リンティングの観点でも実用的な用途がある。ツールの説明文はLLMが読んで判断に使うため、曖昧・不一致な記述はエージェントの動作に直接影響する。ツール名の一貫性、必須パラメータのドキュメント有無、スキーマの精度、認証要件の明示——こうした品質チェックを自動化できる。Ciscoはdeveloper.cisco.comでの実際のドキュメント公開フローにもこのパイプラインを組み込んでいる。

OSSとして公開済み

これらのツールはすでにgithub.com/cisco-openで公開されている：

**mcptoolkit-contract**：MCPサーバーのケイパビリティをダンプし、ドキュメント生成・チェンジログ生成を行うCLI
**mcptoolkit-editor**：Swagger Editorに相当するもので、MCP Descriptionのプレビュー・編集・エクスポートができるツール

いずれもCisco Open Sourceの傘下にあり、Apache 2.0ライセンスで公開されている。ただし、執筆時点ではリポジトリのスター数・コントリビューター数ともに初期段階であり、コミュニティの成熟度はこれからという状況だ。フォーマット自体がドラフト（0.7.0）であることと合わせ、エンタープライズ環境での採用にはベンダーロックインや仕様変更への追従コストを考慮に入れておきたい。

既存のMCPサーバーを運用しているチームであれば、mcptoolkit-contractでサーバーに接続してDescriptionを生成し、何が公開されているかをバージョン付きアーティファクトとして確認するところから始めるのが実用的な入口だ。

「エコシステムに共通フォーマットが必要か」という問い

記事の末尾でCiscoが投げかけるのは「MCPエコシステムには、MCPサーバーを記述する共通の静的フォーマットが必要か」という問いだ。DevNetの経験に基づく答えは「Yes」だが、これはまだエコシステム全体のコンセンサスには至っていない。MCPの仕様自体が急速に進化していることも踏まえると、このフォーマットがどこまで普及するかは今後の動向次第だ。

ただし、RESTとOpenAPIの関係が辿った道筋を知っていれば、こうした静的コントラクト記述への需要がエンタープライズ採用とともに高まることは想像に難くない。

詳細はBeyond the Protocol: Applying API Engineering Practices to MCP Serversを参照していただきたい。