Client Integration

Halaman ini menjelaskan cara menghubungkan aplikasi atau klien AI ke Etalasse MCP server melalui HTTP transport.

Prasyarat

URL endpoint MCP Etalasse untuk lingkungan Anda, misalnya https://mcp.etalasse.com
autentikasi yang valid — sesi OAuth (lihat OAuth Setup), atau bearer token yang disediakan untuk integrasi server-to-server
klien yang dapat mengirim permintaan JSON-RPC 2.0 melalui HTTP POST, atau klien MCP siap pakai

Endpoint

Endpoint	Fungsi
`GET /health`	Pemeriksaan kesehatan server, tanpa autentikasi.
`POST /mcp`	Endpoint MCP utama untuk `initialize`, `tools/list`, dan `tools/call`.

Catatan perilaku server:

setiap respons menyertakan header x-request-id untuk penelusuran
CORS dibatasi ke daftar origin yang diizinkan
rate limiting per IP diberlakukan pada permintaan HTTP

Konfigurasi klien MCP

Untuk klien AI yang mendukung remote MCP server (seperti Claude Code atau Codex), cukup daftarkan endpoint HTTP-nya. Contoh minimal:

{
  "mcpServers": {
    "etalasse": {
      "type": "http",
      "url": "https://mcp.etalasse.com/mcp"
    }
  }
}

Klien akan menemukan metadata OAuth secara otomatis dan membuka alur sign-in saat pertama kali digunakan.

Alur integrasi dari aplikasi

Jika Anda memanggil MCP langsung dari aplikasi Anda sendiri, alur yang direkomendasikan:

Panggil GET /health saat aplikasi dimulai.
Kirim initialize.
Kirim tools/list dan simpan katalog tool bila diperlukan.
Gunakan tools/call untuk setiap aksi.
Tampilkan kegagalan tool apa adanya — error dari API Etalasse sudah dinormalisasi oleh server MCP.

Lima langkah di kiri; langkah 4 adalah permintaan tools/call: (1) header Authorization dan MCP-Protocol-Version, (2) body JSON-RPC, (3) respons dengan x-request-id.

1. Health check

curl https://mcp.etalasse.com/health

Bentuk respons yang diharapkan:

{
  "ok": true,
  "service": "etalasse-mcp",
  "transport": "http",
  "mcp_path": "/mcp"
}

2. Initialize

curl -X POST https://mcp.etalasse.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2026-07-28",
      "capabilities": {},
      "clientInfo": { "name": "my-app", "version": "1.0.0" }
    }
  }'

3. Daftar tool

curl -X POST https://mcp.etalasse.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

4. Memanggil tool

Contoh pencarian toko publik:

curl -X POST https://mcp.etalasse.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "shop.get_by_username",
      "arguments": { "username": "demo-shop" }
    }
  }'

Gunakan system.ping sebagai tool pertama untuk memverifikasi koneksi end-to-end sebelum memanggil tool bisnis.

Penanganan error

Tangani kode berikut secara terpusat di klien Anda:

401 — autentikasi hilang atau kedaluwarsa; ulangi alur OAuth atau perbarui token
403 — sesi tidak berhak menjalankan tool tersebut
429 — terkena rate limit; ulangi dengan backoff
error tingkat tool — muncul di dalam hasil tools/call; pesannya sudah dinormalisasi dari respons API Etalasse

Sertakan nilai x-request-id saat melaporkan masalah agar penelusuran lebih cepat.

Catatan versi protokol

Jika klien Anda memakai revisi protokol MCP yang berbeda, perbarui keduanya secara konsisten:

header MCP-Protocol-Version
params.protocolVersion pada initialize

Prasyarat​

Endpoint​

Konfigurasi klien MCP​

Alur integrasi dari aplikasi​

1. Health check​

2. Initialize​

3. Daftar tool​

4. Memanggil tool​

Penanganan error​

Catatan versi protokol​

Halaman terkait​