Cara Mengubah API Anda Menjadi Server MCP

Pernahkah Anda berharap API Anda dapat berkomunikasi dengan agen AI seperti Claude atau Cursor, mengubah *endpoint* Anda menjadi alat yang cerdas dan komunikatif? Baik, bersiaplah, karena kita akan membahas cara mengubah API Anda menjadi server MCP menggunakan Stainless dan spesifikasi OpenAPI. Panduan komunikatif ini akan memandu Anda melalui prosesnya, mulai dari penyiapan hingga *deployment*, lengkap dengan pengujian untuk membuktikan keberhasilannya. Kita akan menggunakan Model Context Protocol (MCP) untuk membuat API Anda ramah AI, semuanya dengan cara yang menyenangkan dan mudah didekati. Mari kita mulai!

💡

Ingin alat Pengujian API hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform All-in-One yang terintegrasi untuk Tim Pengembang Anda agar dapat bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua kebutuhan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!

button

Apa Itu Server MCP, dan Mengapa Anda Harus Peduli?

**Model Context Protocol (MCP)** bagaikan jabat tangan universal untuk sistem AI. Ini adalah standar berbasis JSON-RPC yang memungkinkan klien AI (seperti Claude Desktop, Cursor, atau VS Code Copilot) berinteraksi dengan API Anda menggunakan bahasa alami atau *prompt* yang dapat diprogram. Sebuah **server MCP** bertindak sebagai jembatan, menerjemahkan *endpoint* API Anda menjadi alat yang dapat dipahami dan digunakan oleh agen AI.

Mengapa **mengubah API Anda menjadi server MCP**? Ini adalah pengubah permainan:

Interaksi Bertenaga AI: Biarkan agen AI memanggil API Anda dengan *prompt* sederhana seperti “Ambil data pengguna” atau “Buat pesanan baru.”
Otomatisasi yang Mudah: Stainless mengotomatiskan prosesnya, menghasilkan server MCP dari spesifikasi OpenAPI Anda dengan pengkodean minimal.
Skalabilitas: Ekspos API Anda ke berbagai klien AI, mulai dari alat pengembangan lokal hingga aplikasi kelas produksi.
Ramah Pengembang: Tidak perlu menulis ulang API Anda—cukup tambahkan lapisan MCP dan biarkan AI melakukan pekerjaan berat.

Baik Anda sedang membangun platform pembayaran, API konten, atau layanan kustom, mengubah API Anda menjadi **server MCP** membuatnya lebih cerdas dan lebih mudah diakses.

Bagaimana Stainless Berperan?

Stainless adalah sahabat terbaik pengembang untuk membuat SDK dan kini server MCP dari spesifikasi OpenAPI. Fitur eksperimental pembuatan server MCP-nya mengambil definisi OpenAPI Anda dan menghasilkan subpaket TypeScript yang siap berfungsi sebagai **server MCP**. Ini berarti *endpoint* API Anda menjadi alat yang dapat diakses AI tanpa Anda perlu bersusah payah. Mari kita lihat bagaimana mewujudkannya!

Mengubah API Anda menjadi Server MCP dengan Stainless

Prasyarat

Sebelum kita mulai, pastikan Anda memiliki:

Spesifikasi OpenAPI: Berkas OpenAPI (Swagger) yang valid untuk API Anda (misalnya, openapi.yaml atau openapi.json).
Akun Stainless: Daftar di stainless.com untuk membuat proyek.
Akun Apidog: Untuk menguji Spesifikasi OpenAPI Anda (kunjungi https://apidog.com/).
Node.js 20+: Untuk pengujian lokal dan menjalankan server MCP (nodejs.org/en/download).
npm: Hadir bersama Node.js untuk manajemen paket.
Klien yang Kompatibel dengan MCP: Claude Desktop, Cursor, atau VS Code Copilot untuk pengujian.
Kunci API: Jika API Anda memerlukan autentikasi, siapkan kunci API.

Langkah 1: Menguji Spesifikasi OpenAPI Anda dengan Apidog

Sebelum atau bahkan setelah mengubah **spesifikasi OpenAPI** Anda menjadi **server MCP**, akan sangat baik untuk mengujinya. Dan di sinilah **Apidog** sangat berguna! Platform intuitif Apidog memungkinkan Anda mengimpor dan menguji spesifikasi OpenAPI Anda untuk memastikan *endpoint* API Anda siap untuk integrasi MCP. Berikut caranya:

Kunjungi Apidog dan Daftar atau Masuk:

Klik Masuk (kanan atas) jika Anda memiliki akun, atau Daftar untuk membuat akun dengan mengikuti petunjuk.

button

2. Buat Proyek Baru dan Impor Spesifikasi OpenAPI Anda:

Setelah masuk, klik Buat Proyek di dasbor.
Pada halaman pembuatan proyek, klik Impor.
Masukkan URL berkas OpenAPI Anda (misalnya, https://my-api.com/openapi.yaml) atau klik atau unggah berkas untuk memilih openapi.yaml atau openapi.json lokal Anda.

Apidog akan mengurai berkas dan menghasilkan API baru di akun Anda (ini mungkin memakan waktu beberapa menit untuk spesifikasi yang kompleks).

3. Konfigurasi Pengaturan API:

Setelah impor berhasil, Anda akan diarahkan ke halaman pengaturan. Sesuaikan nama, deskripsi, dan persyaratan autentikasi API Anda (misalnya, kunci API atau OAuth).

4. Tambahkan Endpoint dan Uji:

Gunakan antarmuka Apidog untuk menambah atau mengedit *endpoint* dan dokumentasi.
Uji *endpoint* Anda langsung di Apidog untuk memverifikasi bahwa mereka berfungsi seperti yang diharapkan sebelum menghasilkan **server MCP** Anda.

Pengujian dengan Apidog memastikan **spesifikasi OpenAPI** Anda solid, membuat proses pembuatan MCP Stainless lebih lancar dan **server MCP** Anda lebih andal.

Langkah 2: Menyiapkan Proyek Stainless dengan TypeScript

Buat Proyek Stainless:

Masuk ke stainless.com dan buat proyek baru.
Unggah spesifikasi OpenAPI Anda (YAML atau JSON) untuk mendefinisikan *endpoint* API Anda.
Pilih TypeScript sebagai bahasa target (pembuatan server MCP memerlukan TypeScript, meskipun target node lama didukung).

Aktifkan Pembuatan Server MCP:

Di bagian Tambah SDK proyek Anda, pilih Server MCP untuk mengaktifkan pembuatan.
Ini akan membuat subpaket di bawah packages/mcp-server di proyek Anda.

Langkah 3: Mengonfigurasi Pembuatan Server MCP

Di pengaturan proyek Stainless Anda, konfigurasikan opsi server MCP. Buat atau edit berkas konfigurasi (misalnya, stainless.yaml) dengan:

targets:
  typescript:
    package_name: my-org-name
    production_repo: null
    publish:
      npm: false
    options:
      mcp_server:
        package_name: my-org-name-mcp
        enable_all_resources: true

package_name: Nama paket server MCP Anda (defaultnya adalah nama SDK Anda dengan -mcp).
enable_all_resources: true: Mengekspos semua *endpoint* API sebagai alat MCP secara default.

Ini memberitahu Stainless untuk menghasilkan subpaket **server MCP** yang mengimplementasikan *endpoint* API Anda sebagai alat yang dapat diakses AI.

Langkah 4: Menyesuaikan Eksposur Endpoint dan Deskripsi Alat

Secara default, semua *endpoint* dalam spesifikasi OpenAPI Anda menjadi alat MCP. Untuk menyesuaikan:

Pilih Endpoint Spesifik:

Atur enable_all_resources: false dan aktifkan sumber daya atau metode spesifik:

resources:
  users:
    mcp: true
    methods:
      create:
        mcp: true
  orders:
    methods:
      create:
        mcp: true
        endpoint: post /v1/orders

2. Sesuaikan Metadata Alat:

Sesuaikan nama dan deskripsi alat untuk interaksi AI yang lebih baik:

resources:
  users:
    methods:
      create:
        mcp:
          tool_name: create_user
          description: Creates a new user profile with name and email.

Ini memastikan **server MCP** Anda hanya mengekspos *endpoint* yang Anda inginkan, dengan deskripsi yang jelas dan ramah AI.

Langkah 5: Menangani API Besar dengan Pemfilteran Alat dan Alat Dinamis

Untuk API dengan banyak *endpoint* (>50), mengekspos setiap *endpoint* sebagai alat terpisah dapat membanjiri jendela konteks AI. Gunakan strategi ini:

Pemfilteran Alat:

Saring alat saat runtime berdasarkan sumber daya, jenis operasi (misalnya, baca/tulis), atau tag kustom:

npx -y my-org-mcp --resource=users

2. Mode Alat Dinamis:

Aktifkan alat dinamis untuk mengekspos tiga meta-alat: list_api_endpoints, get_api_endpoint_schema, dan invoke_api_endpoint. Ini menyederhanakan interaksi untuk API besar:

npx -y my-org-mcp --tools=dynamic

Alat dinamis memungkinkan AI menemukan dan memanggil *endpoint* secara dinamis, mengurangi beban konteks.

Langkah 6: Membangun dan Menerbitkan Server MCP Anda

Membangun Server MCP:

Stainless menghasilkan server MCP di packages/mcp-server saat Anda membangun SDK Anda.
Jalankan perintah *build* di proyek Stainless Anda (periksa README.md proyek Anda untuk detailnya).

Terbitkan ke npm:

Konfigurasi repositori produksi di pengaturan Stainless Anda.
Terbitkan server MCP sebagai paket npm terpisah (misalnya, my-org-name-mcp):

npm publish

Langkah 7: Menginstal dan Mengonfigurasi untuk Klien MCP

Setelah menerbitkan, instal paket server MCP Anda secara lokal atau jarak jauh untuk digunakan dengan klien AI. Untuk Claude Desktop:

Instal Paket:

Jika menguji secara lokal, navigasikan ke packages/mcp-server dan ikuti instruksi README.md.
Untuk penggunaan jarak jauh, instal melalui npm:

npm install my-org-name-mcp

2. Konfigurasi Claude Desktop:

Buka claude_desktop_config.json (macOS: ~/Library/Application Support/Claude, Windows: %APPDATA%\Claude).

Tambahkan:

{
  "mcpServers": {
    "my_org_api": {
      "command": "npx",
      "args": ["-y", "my-org-mcp"],
      "env": {
        "MY_API_KEY": "123e4567-e89b-12d3-a456-426614174000"
      }
    }
  }
}

Ganti my-org-mcp dengan nama paket Anda dan MY_API_KEY dengan kunci API Anda.
Simpan dan mulai ulang Claude Desktop.

3. Klien Lain:

Untuk Cursor atau VS Code Copilot, tambahkan konfigurasi yang sama ke pengaturan masing-masing (misalnya, settings.json untuk VS Code atau panel Tools and Integrations Cursor).

Langkah 8: Menguji Server MCP Anda

Mari kita uji **server MCP** Anda! Di Claude Desktop (atau klien MCP lainnya), coba *prompt* ini:

alex@example.com

Jika API Anda memiliki *endpoint* POST /users (seperti yang didefinisikan dalam spesifikasi OpenAPI Anda), **server MCP** akan menerjemahkan *prompt* ini menjadi panggilan API, membuat pengguna dan mengembalikan respons seperti:

User created: { "name": "Alex", "email": "alex@example.com", "id": "123" }

Ini mengonfirmasi bahwa **server MCP** Anda berfungsi dan siap untuk interaksi berbasis AI.

Tips Pemecahan Masalah

Kesalahan *Build*? Pastikan spesifikasi OpenAPI Anda valid dan TypeScript diaktifkan di proyek Stainless Anda.
Klien Tidak Terhubung? Verifikasi nama paket dan kunci API di konfigurasi MCP Anda, dan mulai ulang klien.
*Prompt* Tidak Berfungsi? Periksa konfigurasi *endpoint* Anda dan pastikan tindakan yang diminta cocok dengan alat yang diekspos.
Beban Konteks Berlebihan? Aktifkan mode alat dinamis atau saring sumber daya untuk API besar.

Praktik Terbaik untuk Server MCP

Jaga Alat Tetap Terfokus: Ekspos hanya *endpoint* yang dibutuhkan AI Anda untuk menghindari pembengkakan konteks.
Deskripsi Jelas: Tulis deskripsi alat yang ramah LLM untuk meningkatkan akurasi *prompt*.
Gunakan Alat Dinamis untuk API Besar: Sederhanakan API besar dengan meta-alat untuk menghemat ruang konteks.
Autentikasi Aman: Gunakan variabel lingkungan atau OAuth untuk kunci API dalam produksi.
Uji Secara Lokal Terlebih Dahulu: Gunakan instruksi README.md untuk menguji sebelum menerbitkan ke npm.

Kesimpulan

Dan selesai! Anda baru saja mempelajari cara **mengubah API Anda menjadi server MCP** menggunakan **Stainless**, mengubah spesifikasi OpenAPI Anda menjadi kekuatan siap-AI. Mulai dari mengonfigurasi *endpoint* hingga menguji dengan *prompt* pembuatan pengguna, panduan ini memudahkan untuk menjembatani API Anda dengan agen AI seperti Claude atau Cursor. Baik Anda sedang meningkatkan proyek kecil atau menskalakan API produksi, **server MCP** adalah tiket Anda menuju integrasi yang lebih cerdas dan komunikatif.

Siap mencobanya? Ambil spesifikasi OpenAPI Anda, nyalakan Stainless, dan biarkan API Anda bersinar di dunia AI.

💡

button