Apigee と MCP を使ってみる

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する

このページでは、Apigee Discovery プロキシを使用して、エージェント アプリケーションの Model Context Protocol（MCP）クライアントで API を MCP ツールとして使用できるようにする方法について説明します。

始める前に

始める前に、次のタスクを完了します。

  1. Google Cloud アカウントにログインします。 Google Cloudを初めて使用する場合は、 アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Apigee 組織がプロビジョニングされていることを確認します。MCP Discovery プロキシは、サブスクリプション、従量課金制、評価組織、Apigee ハイブリッド バージョン 1.17.0 以降で使用できます。詳細については、プロビジョニングの概要をご覧ください。
  7. Apigee ハイブリッドのみ: Apigee ハイブリッドで MCP を有効にするで説明されている 1 回限りのクラスタ有効化手順を完了していることを確認します。これには、overrides.yaml で enableMcpServer: true を最上位キーとして設定し、apigee-operator チャートと apigee-org チャートに対して helm upgrade を実行することが含まれます。
  8. Google Cloud プロジェクトで Apigee API ハブ インスタンスがプロビジョニングされていることを確認します。詳細については、 Google Cloud コンソールで API Hub をプロビジョニングするをご覧ください。API Hub サービスが有効になっていることを確認するには、 Google Cloud コンソールの [ハブ] ページを確認します。

    [API ハブ] に移動

  9. Apigee インスタンスが API Hub サービスに接続されていることを確認します。MCP Discovery プロキシは、API Hub の Apigee Edge for Public Cloud または Apigee Edge for Private Cloud プラグイン インスタンスでは使用できません。詳細については、ランタイム プロジェクトを接続するをご覧ください。ランタイム プロジェクトの関連付けのステータスは、 Google Cloud コンソールの [設定] ページの [プロジェクトの関連付け] タブで確認できます。

    [API ハブ] に移動

必要なロール

MCP Discovery Proxy の作成とデプロイに必要な権限を取得するには、Apigee プロキシのデプロイに使用するサービス アカウントに対する Apigee 管理者 （roles/apigee.admin）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

API を有効にする

Apigee API が有効になっていない場合は有効にします。

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法を確認する。

API の有効化

環境変数を設定する

Apigee インスタンスを含む Google Cloud プロジェクトで、次のコマンドを使用して環境変数を設定します。

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

ここで

  • PROJECT_ID: Apigee インスタンスを含むプロジェクトの ID。
  • REGION は Apigee インスタンスの Google Cloud リージョンです。Apigee ハイブリッドの場合、これはクラスタが配置されているリージョンです。
  • RUNTIME_HOSTNAME は Apigee ランタイムのホスト名です。Apigee ハイブリッドの場合、これは Apigee 環境グループに登録され、Apigee Ingress ゲートウェイによって提供されるホスト名です（例: api.example.com）。

環境変数が正しく設定されていることを確認するには、次のコマンドを実行して出力を確認します。

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

プロジェクトを設定する

開発環境で Google Cloud プロジェクトを設定します。

    gcloud auth login
    gcloud config set project $PROJECT_ID

概要

Apigee を使用して API を MCP ツールとして公開するには、MCP Discovery Proxy テンプレートを使用して新しい Apigee プロキシを作成してデプロイします。プロキシがデプロイされたら、API プロダクトを作成して、プロキシ内の MCP API オペレーションを API プロダクトにバンドルできます。API プロダクトとして、API オペレーション/ツールは、API Hub への統合を通じて MCP クライアントによって検出可能になります。

以降のセクションでは、MCP Discovery Proxy を作成してデプロイし、API プロダクトを作成して、使用可能なツールを一覧表示する手順について説明します。

  1. API オペレーションを記述する OpenAPI 3.0.x 仕様を作成します。
  2. MCP Discovery プロキシを作成する。
  3. （省略可）MCP Discovery プロキシにセキュリティ ポリシーを追加します。
  4. MCP Discovery プロキシをデプロイする。
  5. （省略可）MCP サーバーを初期化します。
  6. 利用可能なツールをリストします。

API オペレーションを記述する OpenAPI 3.0.x 仕様を作成する

MCP Discovery Proxy を作成してデプロイする前に、MCP ツールとして公開する API オペレーションを記述する OpenAPI 3.0.x 仕様を作成する必要があります。Apigee の MCP は、次の OpenAPI バージョンをサポートしています。

  • 3.0.0
  • 3.0.1
  • 3.0.2
  • 3.0.3

このクイックスタートでは、3 つの API オペレーションを含む OpenAPI 3.0.x 仕様のサンプルを使用します。

  • GET /artists: アーティストのリストを返します。
  • POST /artists: : ユーザーが新しいアーティストを投稿できるようにします。
  • GET /artists/{username}: : アーティストの一意のユーザー名からアーティストに関する情報を取得します。

OpenAPI 3.0.x 仕様を作成する手順は次のとおりです。

  1. API プロキシ バンドルの oas ディレクトリに新しい mcp-quickstart-openapi.yaml ファイルを作成します。
  2. このファイルに次の内容を追加します。
    # mcp-quickstart-openapi.yaml
---
openapi: 3.0.3
info:
  title: Cymbal Group Products API
  description: This is the official API for managing the artists for Cymbal Group Products.
  version: 1.0.0
servers:
  - url: https://cymbal.products.com
    description: Cymbal Group Production Server
  - url: https://internal.products.com
    description: Cymbal Group internal Server
paths:
  /artists:
    get:
      description: Returns a list of artists
      operationId: listArtists
      parameters:
        - name: limit
          in: query
          description: Limits the number of items on a page
          schema:
            type: integer
        - name: offset
          in: query
          description: Specifies the page number of the artists to be displayed
          schema:
            type: integer
      responses:
        "200":
          description: An array of artists
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Artist"
    post:
      summary: Create a new artist
      operationId: createArtist
      tags:
        - artists
      requestBody:
        description: The artist to create.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Artist"
      responses:
        "201":
          description: The newly created artist profile
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Artist"
        "400":
          description: Invalid username supplied
  /artists/{username}:
    get:
      summary: Info for a specific artist
      operationId: showArtistByUsername
      tags:
        - artists
      parameters:
        - name: username
          in: path
          required: true
          description: The username of the artist to retrieve
          schema:
            type: string
      responses:
        "200":
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Artist"
        "404":
          description: Artist not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            artists.read: Grants read access
            artists.write: Grants write access
  schemas:
    Artist:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the artist

ホスト名のマッチング要件

OpenAPI 仕様の servers.url フィールドのホスト名の値が、MCP Discovery Proxy がデプロイされている Apigee 環境の環境グループのホスト名と完全に一致していることが重要です。この一致は、tools/list 呼び出しと tools/call 呼び出しが正しく機能するために必要です。

次の表に、OpenAPI 仕様のホスト名構成と、Apigee 環境グループの対応するホスト名構成を示します。

コンポーネント 必要な構成 値の例 補足情報
Apigee 環境グループ ホスト名は環境グループで構成する必要があります。 cymbal.products.com、internal.products.com 環境グループを使用すると、ホスト名を使用して環境のグループにルーティングできます。
OpenAPI 仕様 OpenAPI 仕様の servers.url フィールドの値は、MCP Discovery Proxy がデプロイされている Apigee 環境の環境グループのホスト名と完全に一致する必要があります。 https://cymbal.products.com servers.url ホスト名が、MCP Discovery Proxy がデプロイされている Apigee 環境に対応する環境グループのホスト名と一致しない場合、プロキシのデプロイ時にエラーが発生します。

MCP Discovery プロキシを作成する

API オペレーションを定義する OpenAPI 3.0.x 仕様が作成されたので、MCP Discovery Proxy テンプレートを使用して新しい API プロキシを作成できます。

MCP Discovery プロキシを作成するには:

  1. Google Cloud コンソールの [API プロキシ] ページに移動します。

    [API プロキシ] に移動

  2. [+ 作成] をクリックして、[API プロキシを作成] ペインを開きます。
  3. [Proxy template] ボックスで、[MCP Discovery Proxy] を選択します。
  4. [Proxy details] セクションで、次の詳細を入力します。
    • プロキシ名: プロキシの名前。
    • 説明（省略可）: プロキシの説明。例: My first MCP Discovery Proxy
  5. [次へ] をクリックします。
  6. [OpenAPI specs] セクションで、ファイル ブラウザを使用して、前の手順で作成した OpenAPI 3.0.x ファイルを選択します。
  7. [次へ] をクリックします。
  8. [Deploy (optional)] セクションでは、プロキシのデプロイをスキップできます。[次へ] をクリックします。
  9. [作成] をクリックします。

プロキシのターゲット エンドポイントとサーバー エンドポイントを表示するには、[リビジョン] テーブルの [エンドポイントの概要] 列で [表示] をクリックします。選択したプロキシ リビジョンの [Revision endpoint summary] には、次の情報が表示されます。

  • Proxy endpoints: この例では、ベースパスが /mcp の default プロキシ エンドポイントが表示されます。追加のホスト名または環境グループがプロキシに追加されている場合は、それらもここに表示されます。
  • ターゲット エンドポイント: この例では、default ターゲット接続が ORG_NAME.mcp.apigee.internal に設定されています。ここで、ORG_NAME は Apigee 組織の名前です。ターゲット mcp.apigee.internal は、下位互換性のためにサポートされています。

（省略可）MCP Discovery プロキシにセキュリティ ポリシーを追加する

MCP Discovery Proxy をデプロイする前に、セキュリティ ポリシーを追加してセキュリティ要件を適用できます。OAuth トークンまたは API キーを使用して、MCP Discovery Proxy へのアクセスを保護することをおすすめします。

このセクションでは、MCP Discovery Proxy に OAuthV2 ポリシーを追加する方法について説明します。これにより、MCP Discovery Proxy へのすべてのリクエストが認証および認可されます。代わりに API キーを使用する場合は、API キーを要求して API を保護するで推奨される手順をご覧ください。

トークンの確認を構成するには、API プロキシフローの先頭（ProxyEndpoint PreFlow の先頭）に OAuthV2 ポリシーを VerifyAccessToken オペレーションとともに配置します。この場合、他の処理が行われる前にアクセス トークンが検証され、トークンが拒否された場合は、Apigee で処理が停止され、クライアントにエラーが返されます。

VerifyAccessToken ポリシーを追加するには:

  1. プロキシの詳細ページで、[Develop] タブをクリックします。
  2. [Proxy endpoints] で [default] をクリックし、[PreFlow] をクリックします。

  3. プロキシのフローエディタで、[Add policy step] をクリックします。

    [Proxy Endpoints] に一覧表示されているエンドポイントの PreFlow を選択します。
  4. [Add policy step] ダイアログで、[Create new policy] を選択します。
  5. ポリシーリストの [Security] で、[OAuth v2.0] を選択します。
  6. 必要に応じて、ポリシー名と表示名を変更します。たとえば、読みやすくするために、表示名と名前の両方を VerifyAccessToken に変更することもできます。
  7. [追加] をクリックします。

MCP Discovery プロキシをデプロイする

MCP Discovery Proxy をデプロイするには:

  1. [Deploy] をクリックして、[Deploy API プロキシ] ペインを開きます。
  2. [Revision] フィールドは [1] に設定します。選択されていない場合は、[1] をクリックして選択します。
  3. [Environment] リストで、プロキシをデプロイする環境を選択します。環境は包括的環境である必要があります。
  4. 前の手順で作成したサービス アカウントを入力します。
  5. [デプロイ] をクリックします。

[Deploy] をクリックすると、Apigee はプロキシのデプロイとダウンストリーム コンポーネントのプロビジョニングを開始します。この間（数分かかる場合があります）、UI にはデプロイのプロビジョニング ステータスが表示されます。

プロセスが完了すると、ステータスが [デプロイ済み] に変わり、プロキシはトラフィックを処理できるようになります。

プロキシがデプロイされたら、OpenAPI 仕様の servers.url フィールドのホスト名の値が、MCP Discovery Proxy がデプロイされている Apigee 環境の環境グループのホスト名と完全に一致していることを確認します。

API Hub で MCP ツールを検出する

MCP Discovery Proxy がデプロイされると、その API オペレーションは自動的に API ハブに取り込まれ、MCP ツールとして検出可能になります。

API Hub で MCP ツールを表示するには:

  1. Google Cloud コンソールで、[API Hub] > [API] ページに移動します。

    API Hub の [API] に移動

  2. [フィルタ] をクリックし、[スタイル > MCP] を選択して、[適用] をクリックします。
  3. デプロイした MCP プロキシがリストに表示されます。API Hub の取り込みパイプラインは、OpenAPI 仕様で定義されたパスを、ハブにリストされている個々の MCP ツールに自動的にマッピングします。

組織内のデベロッパーは、API Hub でフィルタまたはセマンティック検索を使用して、自然言語クエリで関連する MCP ツールを検索できるようになりました。

MCP サーバーを初期化する

このステップでは、MCP エンドポイントにリクエストを送信して MCP サーバーを初期化し、期待どおりに動作していることを確認します。

MCP サーバーを初期化してテストするには、次のリクエストを MCP エンドポイントに送信します。

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {
          "protocolVersion": "MCP_PROTOCOL_VERSION"
        }
      }' \
  -H "Authorization: Bearer TOKEN"

次のように置き換えます。

  • MCP_ENDPOINT_URL: MCP エンドポイントのベース URI。例: cymbal.products.com
  • MCP_PROTOCOL_VERSION: MCP プロトコルのバージョン。例: 2025-11-25詳細については、MCP 仕様のバージョン ネゴシエーションをご覧ください。
  • （省略可）TOKEN: OAuth 2.0 アクセス トークン

成功したときのレスポンスは次のようになります。

{
"id":1,
"jsonrpc":"2.0",
"result":
  {
    "capabilities":
    {
      "tools":
      {
        "listChanged":false
      }
    },
    "protocolVersion":"2025-11-25",
    "serverInfo":
      {
        "name":"cymbal.products.com",
        "version":"1.0.0"
      }
    }
  }

利用可能な MCP ツールを一覧表示する

このステップでは、tools/list メソッドにリクエストを送信して、MCP エンドポイントで使用可能なツールのリストを確認します。

Apigee プロキシの tools/list メソッドにリクエストを送信します。

curl -X POST "https://MCP_ENDPOINT_URL/mcp" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: MCP_PROTOCOL_VERSION" \
  -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list",
        "params": {}
      }' \
  -H "Authorization: Bearer TOKEN"

次のように置き換えます。

  • MCP_ENDPOINT_URL: MCP エンドポイントのベース URI。例: cymbal.products.com
  • MCP_PROTOCOL_VERSION: MCP プロトコルのバージョン。例: 2025-11-25詳細については、MCP 仕様のプロトコル バージョン ヘッダーをご覧ください。
  • （省略可）TOKEN: OAuth 2.0 アクセス トークン

このメソッドは、MCP エンドポイントがサポートするすべてのツールを返します。成功したときのレスポンスは次のようになります。

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "description": "Returns a list of artists",
        "inputSchema": {
          "properties": {
            "id": {
              "description": "Unique identifier for the artist",
              "format": "uuid",
              "type": "string"
            }
          },
          "type": "object"
        },
        "name": "listArtists"
      },
      {
        "description": "Create a new artist",
        "inputSchema": {
          "properties": {
            "id": {
              "description": "Unique identifier for the artist",
              "format": "uuid",
              "type": "string"
            }
          },
          "type": "object"
        },
        "name": "createArtist"
      },
      {
        "description": "Info for a specific artist",
        "inputSchema": {
          "properties": {
            "id": {
              "description": "Unique identifier for the artist",
              "format": "uuid",
              "type": "string"
            }
          },
          "type": "object"
        },
        "name": "showArtistByUsername"
      }
    ]
  }
}

エンドポイントが初期化されると、API プロダクトを使用するデベロッパーとエージェントが MCP ツールを検出できるようになります。

モニタリングと分析

Apigee Analytics を使用して、MCP トラフィックをモニタリングし、ツールレベルの指標を表示できます。Apigee Analytics では、指標をフィルタして、標準の API トラフィックと MCP 固有のトラフィックを区別し、tools/list リクエストと tools/call リクエストの使用量を確認できます。詳細については、Apigee で MCP トラフィックをモニタリングして分析するをご覧ください。

次のステップ