CHAINHULK Developers
Website Workspace
Dokumentasi/MCP workspace

MCP workspace

Hubungkan klien MCP dengan layanan workspace menggunakan API key berscope.

Endpoint dan autentikasi

POST https://app.chainhulk.com/api/v1/workspaces/WORKSPACE_ID/mcp
Authorization: Bearer YOUR_API_KEY

Endpoint MCP menerima API key milik satu workspace. Cookie sesi pengguna atau staf tidak mengotorisasi MCP. Gunakan klien yang dapat mengirim Bearer API key. OAuth discovery dan token OAuth belum disediakan pada endpoint ini. ID workspace terikat pada URL; argumen tool tidak dapat memilih workspace lain. Pencabutan key menghentikan permintaan berikutnya.

Transport dan versi protokol

Server menggunakan SDK MCP Go resmi dengan Streamable HTTP stateless dan respons JSON. Tidak ada MCP-Session-Id atau SSE persisten. GET dan DELETE yang sudah terautentikasi mengembalikan 405. Gunakan SDK klien MCP agar versi protokol, metadata dan header metode dikirim secara konsisten. Satu POST menerima satu permintaan JSON-RPC, bukan batch, dengan ukuran maksimal 1 MiB.

Tool yang tersedia

  • bots:read — list_accounts.
  • chats:read — list_conversations, get_conversation, list_messages, dan get_file.
  • contacts:read — list_contacts dan get_contact.
  • messages:send — queue_message dan cancel_message.
  • tools/list hanya menampilkan tool yang diizinkan oleh scope API key. get_file membaca metadata lampiran, tanpa URL bucket publik, object key, atau kredensial penyimpanan.

Antrean pesan dan idempotensi

{
  "name": "queue_message",
  "arguments": {
    "conversation_id": "CONVERSATION_ID",
    "content": "Terima kasih, kami bantu periksa.",
    "idempotency_key": "a363aa19-9647-49d6-930f-30befbb36193"
  }
}

queue_message menggunakan layanan antrean yang sama dengan REST. Hasil created=true berarti pesan baru tersimpan dalam antrean. created=false mengembalikan pesan sebelumnya untuk key dan body yang sama. Perubahan body dengan key yang sama menghasilkan tool error conflict. Konfirmasi antrean tidak berarti provider telah mengirim pesan. Hasil pengiriman unknown tidak otomatis dikirim ulang.

Lampiran opsional file_id harus sudah ready, belum digunakan oleh pesan lain, dan dibuat oleh API key yang sama pada percakapan tersebut. cancel_message hanya membatalkan antrean yang belum memulai percobaan pengiriman. Pengiriman eksternal dinyatakan sebagai tool yang mengubah keadaan, sehingga klien dapat menerapkan persetujuan pengguna.

Permintaan protokol manual

Pada protokol 2026-07-28, sertakan metadata versi dan clientCapabilities pada params._meta, header MCP-Protocol-Version dan Mcp-Method. tools/call juga memerlukan Mcp-Name yang sesuai dengan params.name. Klien resmi mengurus rincian ini. Contoh berikut membaca katalog tool tanpa membuat pesan.

curl https://app.chainhulk.com/api/v1/workspaces/WORKSPACE_ID/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

Kesalahan dan batas akses

HTTP 401 berarti key tidak tersedia atau dicabut. HTTP 403 menolak origin. HTTP 404 berarti workspace tidak tersedia bagi key tersebut. Permintaan berlebih menghasilkan 429 sesuai rate limit API key. Kesalahan bisnis suatu tool memakai isError=true dengan pesan terbatas; error SQL, URL berkredensial dan detail penyimpanan tidak dikembalikan.