Mulai menggunakan Apigee dan MCP

Halaman ini berlaku untuk Apigee, tetapi tidak untuk Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Halaman ini menjelaskan cara menggunakan proxy Apigee Discovery untuk membuat API Anda tersedia bagi klien Model Context Protocol (MCP) di aplikasi berbasis agen 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. Konfirmasi bahwa Anda telah menyediakan organisasi Apigee. Proxy Penemuan MCP tersedia untuk organisasi Langganan, Bayar sesuai penggunaan, dan evaluasi. Untuk mengetahui informasi selengkapnya, lihat Pengantar penyediaan.
  7. Pastikan Anda telah menyediakan instance hub API Apigee di project Anda. Google Cloud Untuk mengetahui informasi selengkapnya, lihat Menyediakan hub API di konsol Google Cloud . Anda dapat mengonfirmasi bahwa layanan hub API diaktifkan dengan memeriksa halaman Hub di konsol Google Cloud .

    Buka hub API

  8. Konfirmasi bahwa instance Apigee terlampir ke layanan hub API Anda. Proxy Penemuan MCP tidak didukung untuk digunakan dengan instance plugin Apigee Edge untuk Cloud Publik atau Apigee Edge untuk Cloud Pribadi 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 hub API

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk membuat dan men-deploy MCP Discovery Proxy, minta administrator Anda 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.

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

Mengaktifkan API

Menetapkan variabel lingkungan

Di 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 Google Cloud region instance Apigee Anda.
  • RUNTIME_HOSTNAME adalah nama host runtime Apigee Anda.

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

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

Menetapkan project

Siapkan Google Cloud project di lingkungan pengembangan Anda: 

    gcloud auth login
    gcloud config set project $PROJECT_ID

Ringkasan

Untuk mengekspos API sebagai alat MCP menggunakan Apigee, Anda membuat dan men-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 hub API.

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

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

Buat spesifikasi OpenAPI 3.0.x yang mendeskripsikan operasi API Anda

Sebelum membuat dan men-deploy MCP Discovery Proxy, Anda harus 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 spesifikasi OpenAPI 3.0.x contoh 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 penggunanya yang unik.

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

Nilai nama host di kolom servers.url spesifikasi OpenAPI harus sama persis dengan nama host grup lingkungan dari lingkungan Apigee tempat MCP Discovery Proxy 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 sekelompok lingkungan menggunakan nama host.
Spesifikasi OpenAPI Nilai kolom servers.url spesifikasi OpenAPI harus sama persis dengan nama host grup lingkungan dari lingkungan Apigee tempat MCP Discovery Proxy di-deploy. https://cymbal.products.com Jika nama host servers.url tidak cocok dengan nama host grup lingkungan yang sesuai dengan lingkungan Apigee tempat MCP Discovery Proxy di-deploy, Anda akan mendapatkan error saat men-deploy proxy.

Membuat Proxy Penemuan 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 MCP Discovery Proxy:

  1. Buka halaman API proxies di konsol Google Cloud .

    Buka proxy API

  2. Klik + Create untuk membuka panel Create API proxy.
  3. Di kotak Proxy template, pilih MCP Discovery Proxy.
  4. Di bagian Proxy details, masukkan detail berikut:
    • Nama proxy: nama untuk proxy Anda.
    • Deskripsi (Opsional): deskripsi untuk proxy Anda. Contoh, My first MCP Discovery Proxy.
  5. Klik Berikutnya.
  6. Di bagian Spesifikasi OpenAPI, gunakan browser file 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 target dan endpoint server proxy dengan mengklik Lihat di kolom Ringkasan endpoint pada tabel Revisi. Ringkasan endpoint revisi untuk revisi proxy yang Anda pilih menampilkan informasi berikut:

  • Endpoint proxy: Dalam contoh ini, endpoint proxy default dengan jalur dasar /mcp ditampilkan. Jika nama host atau grup lingkungan tambahan ditambahkan ke proxy, nama host atau grup lingkungan tersebut juga akan ditampilkan di sini.
  • Endpoint target: 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) Tambahkan kebijakan keamanan ke MCP Discovery Proxy

Sebelum men-deploy MCP Discovery Proxy, Anda dapat menambahkan kebijakan keamanan untuk menerapkan persyaratan keamanan. Kami menyarankan agar Anda mengamankan akses ke MCP Discovery Proxy menggunakan token Oauth atau kunci API.

Bagian ini menjelaskan cara menambahkan kebijakan OAuthV2 ke MCP Discovery Proxy. Hal ini memastikan bahwa semua permintaan ke MCP Discovery Proxy diautentikasi dan diotorisasi. Jika Anda ingin menggunakan kunci API sebagai gantinya, 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 Preflow ProxyEndpoint). 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 perlu, ubah nama kebijakan dan nama tampilan. Misalnya, untuk keterbacaan yang lebih baik, Anda dapat mengubah Nama tampilan dan Nama menjadi VerifyAccessToken.
  7. Klik Tambahkan.

Men-deploy Proxy Penemuan MCP

Untuk men-deploy MCP Discovery Proxy:

  1. Klik Deploy untuk membuka panel Deploy API proxy.
  2. Kolom Revisi harus ditetapkan ke 1. Jika belum, klik 1 untuk memilihnya.
  3. Di 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 hilir. Selama waktu ini, yang mungkin memerlukan waktu beberapa menit, UI akan menampilkan status Penyediaan untuk deployment.

Setelah proses selesai, status akan berubah menjadi Di-deploy 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 hub API

Setelah MCP Discovery Proxy Anda di-deploy, operasi API-nya akan otomatis di-ingest ke hub API 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, lalu 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 Hub API untuk menemukan alat MCP yang relevan menggunakan kueri bahasa alami.

Menginisialisasi server MCP Anda

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

Untuk melakukan inisialisasi dan menguji server MCP, 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. Apigee Analytics memungkinkan Anda 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