Apigee と MCP を使ってみる

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

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

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

始める前に

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

  1. アカウントにログインします。 Google Cloud を初めて使用する場合は、 アカウントを作成して、実際のシナリオで Google プロダクトのパフォーマンスを評価してください。 Google Cloud新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $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 プロキシは、サブスクリプション、従量課金制、評価組織で使用できます。詳細については、プロビジョニングの概要をご覧ください。
  7. プロジェクトに Apigee API ハブ インスタンスがプロビジョニングされていることを確認します。 Google Cloud 詳細については、 コンソールでAPI ハブをプロビジョニングする Google Cloud をご覧ください。API ハブサービスが有効になっていることは、 Google Cloud コンソールの [ハブ] ページで確認できます。

    [API ハブ] に移動

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

    [API ハブ] に移動

必要なロール

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

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

API を有効にする

Apigee API を有効にします。

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

API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（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 リージョンです。
  • RUNTIME_HOSTNAME は Apigee ランタイムのホスト名です。

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

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 ハブとの統合を通じて MCP クライアントから検出できます。

以降のセクションでは、MCP Discovery プロキシの作成とデプロイ、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 プロキシを作成してデプロイする前に、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 プロキシがデプロイされている Apigee 環境の環境グループのホスト名 と完全に一致していることが重要です。 この一致は、tools/list 呼び出しと tools/call 呼び出しが正しく機能するために必要です。

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

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

MCP Discovery プロキシを作成する

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

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

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

    [API プロキシ] に移動

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

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

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

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

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

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

トークンの確認を構成するには、API プロキシフローの先頭（ ProxyEndpoint Preflow の先頭）に OAuthV2 policy を 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 プロキシをデプロイするには:

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

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

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

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

API ハブで MCP ツールを検出する

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

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

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

    API Hub の [API] に移動

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

組織内のデベロッパーは、API ハブでフィルタまたはセマンティック検索 を使用して、 自然言語クエリを使用して関連する 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 トラフィックをモニタリングして分析するをご覧ください。

次のステップ