Mulai menggunakan Apigee dan MCP

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan cara menggunakan proxy Apigee Discovery untuk menyediakan API Anda bagi klien Model Context Protocol (MCP) dalam aplikasi agentic sebagai alat MCP.

Sebelum memulai

Sebelum memulai, selesaikan tugas berikut:

  1. Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

  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. Pastikan Anda telah menyediakan organisasi Apigee. Proxy MCP Discovery tersedia untuk organisasi Langganan, Bayar sesuai penggunaan, dan evaluasi, serta untuk Apigee hybrid versi 1.17.0 dan yang lebih baru. Untuk mengetahui informasi selengkapnya, lihat Pengantar penyediaan.
  7. Khusus Apigee hybrid: Pastikan Anda telah menyelesaikan langkah-langkah pengaktifan cluster satu kali yang dijelaskan dalam Mengaktifkan MCP di Apigee hybrid. Hal ini melibatkan penetapan enableMcpServer: true sebagai kunci tingkat teratas di overrides.yaml dan menjalankan helm upgrade terhadap diagram apigee-operator dan apigee-org.
  8. Pastikan Anda telah menyediakan instance hub API Apigee di project Google Cloud Anda. Untuk mengetahui informasi selengkapnya, lihat Menyediakan API hub di konsol Google Cloud . Anda dapat mengonfirmasi bahwa layanan API hub diaktifkan dengan memeriksa halaman Hub di konsol Google Cloud .

    Buka API hub

  9. Pastikan instance Apigee terpasang ke layanan hub API Anda. Proxy MCP Discovery tidak didukung untuk digunakan dengan instance plugin Apigee Edge for Public Cloud atau Apigee Edge for Private Cloud di hub API. Untuk mengetahui informasi selengkapnya, lihat Melampirkan project runtime. Anda dapat memeriksa status lampiran project runtime di tab Project associations pada halaman Settings di konsol Google Cloud .

    Buka API hub

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk membuat dan men-deploy Proxy Discovery MCP, minta administrator untuk memberi Anda peran IAM Apigee Admin (roles/apigee.admin) di akun layanan yang Anda gunakan untuk men-deploy proxy Apigee. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Mengaktifkan API

Aktifkan Apigee API, jika belum diaktifkan.

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

Mengaktifkan API

Menetapkan variabel lingkungan

Dalam project Google Cloud yang berisi instance Apigee Anda, gunakan perintah berikut untuk menetapkan variabel lingkungan: 

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

Dengan:

  • PROJECT_ID adalah ID project dengan instance Apigee Anda.
  • REGION adalah region Google Cloud instance Apigee Anda. Untuk Apigee hybrid, ini adalah region tempat cluster Anda berada.
  • RUNTIME_HOSTNAME adalah nama host runtime Apigee Anda. Untuk Apigee hybrid, ini adalah nama host yang terdaftar di grup lingkungan Apigee Anda dan disajikan oleh gateway ingress Apigee (misalnya, api.example.com).

Untuk mengonfirmasi bahwa variabel lingkungan telah ditetapkan dengan benar, jalankan perintah berikut dan tinjau outputnya: 

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Menetapkan project

Tetapkan project Google Cloud di lingkungan pengembangan Anda: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Ringkasan

Untuk mengekspos API Anda sebagai alat MCP menggunakan Apigee, buat dan deploy proxy Apigee baru menggunakan template MCP Discovery Proxy. Setelah proxy di-deploy, Anda dapat membuat produk API untuk memaketkan operasi MCP API di proxy Anda ke dalam produk API. Sebagai produk API, operasi/alat API Anda dapat ditemukan oleh klien MCP melalui integrasi ke API Hub.

Bagian berikut menjelaskan langkah-langkah untuk membuat dan men-deploy Proxy MCP Discovery, membuat produk API, dan mencantumkan alat yang tersedia:

  1. Buat spesifikasi OpenAPI 3.0.x yang menjelaskan operasi API Anda.
  2. Buat Proxy Discovery MCP.
  3. (Opsional) Tambahkan kebijakan keamanan ke Proxy Penemuan MCP.
  4. Men-deploy Proxy Discovery MCP.
  5. (Opsional) Lakukan inisialisasi server MCP Anda.
  6. Mencantumkan alat yang tersedia.

Membuat spesifikasi OpenAPI 3.0.x yang menjelaskan operasi API Anda

Sebelum membuat dan men-deploy MCP Discovery Proxy, Anda perlu membuat spesifikasi OpenAPI 3.0.x yang menjelaskan operasi API yang ingin Anda ekspos sebagai alat MCP. MCP di Apigee mendukung versi OpenAPI berikut:

  • 3.0.0
  • 3.0.1
  • 3.0.2
  • 3.0.3

Panduan memulai ini menggunakan contoh spesifikasi OpenAPI 3.0.x dengan tiga operasi API:

  • GET /artists: Menampilkan daftar artis.
  • POST /artists: Memungkinkan pengguna memposting artis baru.
  • GET /artists/{username}: Mendapatkan informasi tentang artis dari nama pengguna uniknya.

Untuk membuat spesifikasi OpenAPI 3.0.x, lakukan hal berikut:

  1. Buat file mcp-quickstart-openapi.yaml baru di direktori oas paket proxy API Anda.
  2. Tambahkan teks berikut ke file: 
    # 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

Persyaratan pencocokan nama host

Sangat penting bahwa nilai nama host di kolom servers.url spesifikasi OpenAPI sama persis dengan nama host grup lingkungan dari lingkungan Apigee tempat Proxy Discovery MCP di-deploy. Pencocokan ini diperlukan agar panggilan tools/list dan tools/call berfungsi dengan benar.

Tabel berikut menunjukkan konfigurasi nama host dalam spesifikasi OpenAPI dan konfigurasi nama host yang sesuai dalam grup lingkungan Apigee:

Komponen Konfigurasi yang Diperlukan Nilai Contoh Informasi Pendukung
Grup Lingkungan Apigee Nama host harus dikonfigurasi di grup lingkungan. cymbal.products.com, internal.products.com Grup lingkungan memungkinkan perutean ke grup lingkungan menggunakan nama host.
Spesifikasi OpenAPI Nilai kolom servers.url dari spesifikasi OpenAPI harus sama persis dengan nama host grup lingkungan dari lingkungan Apigee tempat Proxy Discovery MCP di-deploy. https://cymbal.products.com Jika nama host servers.url tidak cocok dengan nama host grup lingkungan yang sesuai dengan lingkungan Apigee tempat Proxy Discovery MCP di-deploy, Anda akan mendapatkan error saat men-deploy proxy.

Membuat Proxy Discovery MCP

Setelah memiliki spesifikasi OpenAPI 3.0.x yang menentukan operasi API, Anda dapat membuat proxy API baru menggunakan template MCP Discovery Proxy.

Untuk membuat Proxy Discovery MCP:

  1. Buka halaman API proxies di konsol Google Cloud .

    Buka proxy API

  2. Klik + Create untuk membuka panel Create Proxy API.
  3. Di kotak Proxy template, pilih MCP Discovery Proxy.
  4. Di bagian Proxy details, masukkan detail berikut:
    • Nama proxy: nama untuk proxy Anda.
    • Description (Optional ): deskripsi untuk proxy Anda. Contoh, My first MCP Discovery Proxy.
  5. Klik Berikutnya.
  6. Di bagian OpenAPI specs, gunakan file browser untuk memilih file OpenAPI 3.0.x yang Anda buat di langkah sebelumnya.
  7. Klik Berikutnya.
  8. Di bagian Deploy (optional), Anda dapat melewati deployment proxy untuk saat ini. Klik Next.
  9. Klik Create.

Anda dapat melihat endpoint target dan server proxy dengan mengklik View di kolom Endpoint summary pada tabel Revisions. Ringkasan endpoint revisi untuk revisi proxy yang Anda pilih menampilkan informasi berikut:

  • Proxy endpoints: Dalam contoh ini, endpoint proxy default dengan jalur dasar /mcp akan ditampilkan. Jika nama host atau grup lingkungan tambahan ditambahkan ke proxy, nama host atau grup lingkungan tersebut juga akan ditampilkan di sini.
  • Target endpoint: Dalam contoh ini, koneksi target default ditetapkan ke ORG_NAME.mcp.apigee.internal, dengan ORG_NAME adalah nama organisasi Apigee Anda. Target mcp.apigee.internal juga didukung untuk kompatibilitas mundur.

(Opsional) Menambahkan kebijakan keamanan ke Proxy Penemuan MCP

Sebelum men-deploy Proxy Discovery MCP, Anda dapat menambahkan kebijakan keamanan untuk menerapkan persyaratan keamanan. Sebaiknya amankan akses ke Proxy Discovery MCP Anda menggunakan token OAuth atau kunci API.

Bagian ini menjelaskan cara menambahkan kebijakan OAuthV2 ke Proxy Discovery MCP. Hal ini memastikan bahwa semua permintaan ke MCP Discovery Proxy diautentikasi dan diotorisasi. Jika Anda ingin menggunakan kunci API, lihat Mengamankan API dengan mewajibkan kunci API untuk mengetahui langkah-langkah yang direkomendasikan.

Untuk mengonfigurasi verifikasi token, tempatkan kebijakan OAuthV2 dengan operasi VerifyAccessToken di awal alur proxy API (awal ProxyEndpoint Preflow). Jika ditempatkan di sana, token akses akan diverifikasi sebelum pemrosesan lainnya dilakukan, dan jika token ditolak, Apigee akan menghentikan pemrosesan dan menampilkan error kepada klien.

Untuk menambahkan kebijakan VerifyAccessToken:

  1. Di halaman detail proxy, klik tab Develop.
  2. Di bagian Proxy endpoints, klik default, lalu klik PreFlow.

  3. Di editor alur proxy, klik Add policy step.

    Pilih PreFlow untuk endpoint yang tercantum di bagian Proxy Endpoints.
  4. Dalam dialog Add policy step, pilih Create new policy.
  5. Dari daftar kebijakan, di bagian Security, pilih OAuth v2.0.
  6. Jika ingin, ubah nama kebijakan dan nama tampilan. Misalnya, agar lebih mudah dibaca, Anda dapat mengubah Display name dan Name menjadi VerifyAccessToken.
  7. Klik Tambahkan.

Men-deploy Proxy Discovery MCP

Untuk men-deploy MCP Discovery Proxy:

  1. Klik Deploy untuk membuka panel Deploy API proxy.
  2. Kolom Revision harus ditetapkan ke 1. Jika belum, klik 1 untuk memilihnya.
  3. Dalam daftar Environment, pilih lingkungan tempat Anda ingin men-deploy proxy. Lingkungan harus berupa lingkungan Komprehensif.
  4. Masukkan Akun layanan yang Anda buat di langkah sebelumnya.
  5. Klik Deploy.

Saat Anda mengklik Deploy, Apigee akan mulai men-deploy proxy dan menyediakan komponen downstream. Selama waktu ini, yang mungkin memerlukan waktu beberapa menit, UI akan menampilkan status Provisioning untuk deployment.

Setelah proses selesai, status akan berubah menjadi Deployed dan proxy siap menangani traffic.

Setelah proxy di-deploy, pastikan nilai nama host di kolom servers.url spesifikasi OpenAPI sama persis dengan nama host grup lingkungan dari lingkungan Apigee tempat MCP Discovery Proxy di-deploy.

Menemukan alat MCP di API hub

Setelah MCP Discovery Proxy di-deploy, operasi API-nya akan otomatis diserap ke API hub dan dapat ditemukan sebagai alat MCP.

Untuk melihat alat MCP Anda di hub API:

  1. Di konsol Google Cloud , buka halaman API Hub > APIs.

    Buka API hub API

  2. Klik Filter dan pilih Gaya > MCP, lalu klik Terapkan.
  3. Proxy MCP yang di-deploy akan muncul dalam daftar. Pipeline penyerapan API Hub secara otomatis memetakan jalur yang ditentukan dalam spesifikasi OpenAPI Anda ke setiap alat MCP yang tercantum di hub.

Developer di organisasi Anda kini dapat menggunakan filter atau Penelusuran Semantik di API Hub untuk menemukan alat MCP yang relevan menggunakan kueri bahasa alami.

Melakukan inisialisasi server MCP Anda

Pada langkah ini, Anda akan mengirim permintaan ke endpoint MCP untuk melakukan inisialisasi server MCP dan mengonfirmasi bahwa server tersebut berfungsi seperti yang diharapkan.

Untuk melakukan inisialisasi dan menguji server MCP Anda, kirim permintaan berikut ke endpoint MCP Anda: 

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"

Ganti kode berikut:

  • MCP_ENDPOINT_URL: URI dasar endpoint MCP Anda. Contoh, cymbal.products.com.
  • MCP_PROTOCOL_VERSION: versi protokol MCP. Contoh, 2025-11-25. Lihat Negosiasi Versi dalam spesifikasi MCP untuk mengetahui informasi selengkapnya.
  • (Opsional) TOKEN: Token akses OAuth 2.0

Respons yang berhasil akan terlihat mirip dengan berikut ini:

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

Mencantumkan alat MCP yang tersedia

Pada langkah ini, Anda akan mengirim permintaan ke metode tools/list untuk mengonfirmasi daftar alat yang tersedia di endpoint MCP Anda.

Kirim permintaan ke metode tools/list untuk proxy Apigee Anda:

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"

Ganti kode berikut:

  • MCP_ENDPOINT_URL: URI dasar endpoint MCP Anda. Contoh, cymbal.products.com.
  • MCP_PROTOCOL_VERSION: versi protokol MCP. Contoh, 2025-11-25. Lihat Header versi protokol dalam spesifikasi MCP untuk mengetahui informasi selengkapnya.
  • (Opsional) TOKEN: Token akses OAuth 2.0

Metode ini menampilkan semua alat yang didukung endpoint MCP. Respons yang berhasil akan terlihat mirip dengan berikut ini:

{
  "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"
      }
    ]
  }
}

Setelah endpoint diinisialisasi, alat MCP Anda dapat ditemukan oleh developer dan agen yang menggunakan produk API Anda.

Pemantauan dan analisis

Anda dapat memantau traffic MCP dan melihat metrik tingkat alat menggunakan Apigee Analytics. Dengan Apigee Analytics, Anda dapat memfilter metrik untuk membedakan antara traffic API standar dan traffic khusus MCP, serta melihat volume penggunaan untuk permintaan tools/list versus tools/call. Untuk mengetahui informasi selengkapnya, lihat Memantau dan menganalisis traffic MCP di Apigee.

Langkah berikutnya