Integrasi Model Context Protocol (MCP)

Model Context Protocol (MCP) adalah standar protokol terbuka dari Anthropic yang memungkinkan agen AI (seperti Claude Desktop, Cursor, Copilot, dsb.) secara aman menggunakan perkakas (tools) yang disediakan oleh platform Kirem.

Kirem mendukung interaksi dengan AI Agent Anda melalui endpoint JSON-RPC 2.0 yang kompatibel penuh dengan spesifikasi MCP. Dengan integrasi ini, Agen AI Anda dapat membaca riwayat percakapan WhatsApp, melihat daftar percakapan aktif, dan mengirimkan pesan balasan secara mandiri.

🔌 Detail Endpoint & Autentikasi

Semua request MCP dikirimkan melalui satu endpoint API POST menggunakan format protokol JSON-RPC 2.0.

• Method: POST
• URL: https://api.kirem.co/v1/mcp
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer <YOUR_API_KEY> (Gunakan API Key yang digenerate dari dasbor Kirem)

🛠️ Daftar Tools yang Tersedia (MCP Tools)

Kirem menyediakan tools berikut untuk dieksekusi oleh Agen AI Anda:

1. tools/list

Digunakan untuk mendapatkan skema dan daftar lengkap tools yang didukung oleh Kirem.

• Payload Request:

  {
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }
  

• Contoh Response Sukses:

  {
    "jsonrpc": "2.0",
    "result": {
      "tools": [
        {
          "name": "send_message",
          "description": "Kirim pesan WhatsApp ke session chat/percakapan tertentu.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "session_id": {
                "type": "string",
                "description": "ID dari chat session/percakapan."
              },
              "text": {
                "type": "string",
                "description": "Isi pesan teks yang ingin dikirim."
              }
            },
            "required": ["session_id", "text"]
          }
        },
        {
          "name": "list_conversations",
          "description": "Dapatkan daftar percakapan (chat sessions) aktif dalam proyek.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "description": "Saring berdasarkan status percakapan (open, pending, resolved, on_hold). Opsional."
              }
            }
          }
        },
        {
          "name": "get_conversation",
          "description": "Dapatkan detail percakapan (chat session) beserta riwayat timeline pesannya.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "session_id": {
                "type": "string",
                "description": "ID dari chat session/percakapan."
              }
            },
            "required": ["session_id"]
          }
        }
      ]
    },
    "id": 1
  }
  

2. list_conversations (via tools/call)

Digunakan oleh Agen AI untuk menarik daftar seluruh sesi obrolan (percakapan WhatsApp) yang sedang aktif di proyek Anda.

• Payload Request:

  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_conversations",
      "arguments": {
        "status": "open" // Opsional: "open", "pending", "resolved", "on_hold"
      }
    },
    "id": 2
  }
  

• Contoh Response Sukses:

  {
    "jsonrpc": "2.0",
    "result": {
      "content": [
        {
          "type": "text",
          "text": "[{\"id\":\"8a3d12d4-1a9b-4bfa-a7b3-c123456789ab\",\"status\":\"open\",\"customer_phone\":\"62812345678\",\"updated_at\":\"2026-06-28T16:00:00Z\"}]"
        }
      ]
    },
    "id": 2
  }
  

3. get_conversation (via tools/call)

Digunakan oleh Agen AI untuk mendapatkan riwayat pesan lengkap dari suatu sesi percakapan agar agen memiliki konteks obrolan sebelum merespons.

• Payload Request:

  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_conversation",
      "arguments": {
        "session_id": "8a3d12d4-1a9b-4bfa-a7b3-c123456789ab" // Wajib berupa UUID session yang valid
      }
    },
    "id": 3
  }
  

• Contoh Response Sukses:

  {
    "jsonrpc": "2.0",
    "result": {
      "content": [
        {
          "type": "text",
          "text": "{\"session\":{\"id\":\"8a3d12d4-1a9b-4bfa-a7b3-c123456789ab\",\"status\":\"open\"},\"messages\":[{\"id\":\"msg_1\",\"sender\":\"customer\",\"text\":\"Halo, apakah produk X ready?\",\"created_at\":\"...\"}]}"
        }
      ]
    },
    "id": 3
  }
  

4. send_message (via tools/call)

Digunakan oleh Agen AI untuk membalas pesan WhatsApp pelanggan secara langsung.

• Payload Request:

  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "send_message",
      "arguments": {
        "session_id": "8a3d12d4-1a9b-4bfa-a7b3-c123456789ab", // Wajib UUID valid
        "text": "Halo! Produk X saat ini ready stock. Ingin langsung kami buatkan pesanannya?"
      }
    },
    "id": 4
  }
  

• Contoh Response Sukses:

  {
    "jsonrpc": "2.0",
    "result": {
      "content": [
        {
          "type": "text",
          "text": "Pesan berhasil dikirim. Message ID: msg_abc123"
        }
      ]
    },
    "id": 4
  }
  

💡 Contoh Alur Penggunaan (Use Case: Customer Support AI Agent)

Berikut adalah siklus interaksi Agen AI Anda dengan API MCP Kirem saat membalas pesan pelanggan secara otomatis:

sequenceDiagram
    participant Agent as AI Agent (Claude/Custom)
    participant Kirem as Kirem MCP API
    participant DB as Kirem Database

    Note over Agent, Kirem: Tahap 1: Cek Pesan Masuk
    Agent->>Kirem: POST /v1/mcp (Method: tools/call, Tool: list_conversations, status: open)
    Kirem->>Agent: Kembalikan daftar session aktif dengan UUID-nya
    
    Note over Agent, Kirem: Tahap 2: Tarik Konteks Obrolan
    Agent->>Kirem: POST /v1/mcp (Method: tools/call, Tool: get_conversation, session_id: <UUID>)
    Kirem->>Agent: Kembalikan riwayat pesan chat dari pelanggan tersebut
    
    Note over Agent: Berpikir & Memformulasikan Balasan
    
    Note over Agent, Kirem: Tahap 3: Kirim Balasan ke WhatsApp
    Agent->>Kirem: POST /v1/mcp (Method: tools/call, Tool: send_message, session_id: <UUID>, text: "...")
    Kirem->>DB: Validasi & Simpan Pesan (UUID check)
    DB-->>Kirem: Berhasil
    Kirem->>Agent: Kembalikan status sukses (Pesan berhasil dikirim)

1. AI Agent secara terjadwal/polling memanggil tool list_conversations untuk mendeteksi apakah ada sesi percakapan berstatus open atau pending.
2. Setelah mendapatkan list session, AI Agent mengambil salah satu session_id (berupa UUID) dan memanggil tool get_conversation untuk membaca riwayat obrolan pelanggan.
3. AI Agent memproses riwayat tersebut menggunakan Large Language Model (LLM) miliknya untuk menyusun teks jawaban yang tepat.
4. AI Agent mengirimkan teks jawaban tersebut kembali ke pelanggan menggunakan tool send_message dengan menyertakan session_id yang sesuai.