Panduan Integrasi Klien

GoSosmed MCP Hub menyediakan dua transport standar industri: Streamable HTTP (rekomendasi untuk klien AI pribadi yang terhubung lewat internet) dan Server-Sent Events (SSE) (koneksi stream berumur panjang, ideal untuk agent yang berjalan di server yang sama). Halaman ini menyediakan templat konfigurasi siap pakai yang telah diaudit dan diuji secara riil.

Pastikan Anda telah memiliki Kunci API (gsk_live_...) dari menu Settings -> API Keys di dasbor GoSosmed atau panduan Koneksi Lingkungan Produksi.

---

⚡ Prompt Instalasi Otomatis untuk AI Agent (Claude, Codex, Cursor, dll.)

Jika Anda menggunakan AI Coding Agent (seperti Claude Code, Codex / OpenCode, Cursor Agent, Windsurf Cascade, Hermes, atau agent lain yang mendukung MCP), Anda tidak perlu menyunting berkas konfigurasi secara manual. Cukup salin (copy) teks prompt instruksi di bawah ini dan tempelkan (paste) ke jendela chat agent Anda.

Agent akan mendeteksi lingkungannya sendiri, memvalidasi kunci API Anda, menulis konfigurasi MCP secara presisi, dan memvalidasi konektivitas perangkat.

Validasi Wajib API Key

Kunci API berformat gsk_live_... (diperoleh dari menu Settings -> API Keys di dasbor GoSosmed). Agent diwajibkan meminta kunci ini kepada Anda jika belum disertakan, dan dilarang keras menggunakan placeholder palsu.

Berkas Skill Kanonik Agen (.md)

Tersedia berkas skill kanonik siap pakai untuk Claude Code, ZeroClaw, dan Codex:
👉 Skill Agen Mobile MCP (gososmed-mobile-mcp.md)
Berkas ini memuat spesifikasi 24 Tools, 3 Prompts, 2 Resources, dan 5 Pilar Anti-Fragile yang dapat diunduh atau di-import langsung di dasbor /agent tab Skills.

Teks Copy-Prompt Universal:

Tolong pasangkan dan hubungkan GoSosmed MCP Hub ke lingkungan kerja/agent Anda saat ini:

1. Parameter Koneksi MCP:
   - Nama Server: gososmed
   - URL Streamable HTTP (Rekomendasi Utama untuk klien AI pribadi): https://api.bamsbung.id/mcp
   - URL SSE (alternatif, untuk klien yang hanya mendukung SSE): https://api.bamsbung.id/mcp/sse
   - Protokol Transport: pilih salah satu — Streamable HTTP (type: http) ATAU SSE (type: sse),
     sesuai kemampuan klien Anda. Jangan mencampur URL dan tipe transport yang berbeda.
   - Header Otentikasi: Authorization: Bearer <API_KEY_GOSOSMED>

2. Validasi Wajib API Key Pengguna:
   - Periksa apakah saya sudah menyertakan API Key GoSosmed (format: gsk_live_...).
   - JIKA BELUM ADA: Berhenti dan langsung tanyakan API Key GoSosmed saya sekarang sebelum melakukan instalasi. DILARANG menggunakan token placeholder palsu atau menebak kunci otentikasi!

3. Deteksi Lingkungan & Pemasangan Otomatis:
   - Claude Code (CLI): Jalankan perintah:
     claude mcp add gososmed https://api.bamsbung.id/mcp/sse --header "Authorization: Bearer <API_KEY_GOSOSMED>"
   - Cursor IDE: Perbarui/buat berkas `.cursor/mcp.json` di root proyek dengan entri `mcpServers.gososmed` (type: "sse", url: "https://api.bamsbung.id/mcp/sse").
   - Claude Desktop: Perbarui berkas `claude_desktop_config.json` pada bagian `mcpServers.gososmed` dengan url `https://api.bamsbung.id/mcp/sse` (type: "sse").
   - ZeroClaw Agent: Daftarkan ke berkas `~/.zeroclaw/config.toml` pada blok `[[mcp.servers]]` (transport: "sse", url: "https://api.bamsbung.id/mcp/sse").
   - Codex / OpenCode / Hermes: Daftarkan server MCP gososmed ke berkas konfigurasi agent aktif (`.codex/config.json`, `~/.config/opencode/mcp.json`, atau config MCP aktif).
   - Windsurf: Daftarkan ke berkas `mcp_config.json` (serverUrl: `https://api.bamsbung.id/mcp/sse`).

4. Pembuktian & Verifikasi Koneksi:
   - Setelah konfigurasi terpasang, jalankan tool MCP GoSosmed (seperti `check_device_status` atau `list_devices`) untuk memverifikasi bahwa koneksi aktif dan API Key valid.
   - Laporkan hasil status perangkat fisik (model HP & status online) kepada saya sebagai bukti instalasi selesai.

---

⚖️ Mengapa SSE Lebih Unggul dalam Automasi Agen AI?

Berdasarkan audit arsitektur dan hasil pengujian riil pada live device, berikut karakteristik kedua transport. Pilihan terbaik bergantung pada tempat klien Anda berjalan — klien yang berjalan di server yang sama dengan GoSosmed (loopback) mendapat manfaat terbesar dari SSE, sedangkan klien AI pribadi yang terhubung lewat internet lebih nyaman memakai Streamable HTTP.

Aspek Keunggulan	Server-Sent Events (/mcp/sse)	Streamable HTTP (/mcp)	Dampak Nyata pada Automasi AI
Asynchronous Progress Push	⭐ Didukung Penuh	⚠️ Terbatas	Server GoSosmed dapat mengirimkan progres upload video (40–75 detik), tangkapan layar Set-of-Marks, dan status live secara langsung tanpa menunggu giliran request baru.
Kompatibilitas Standar Klien	🏆 Luas	⚠️ Sebagian	SSE didukung langsung oleh Claude Code, Claude Desktop, ZeroClaw, Cursor, dan Continue.dev.
Pola Koneksi Jaringan	Long-lived Event Stream	Request-response mandiri	SSE memberi latensi sangat rendah selama stream tetap hidup.
Ketahanan terhadap Putus Jaringan	⚠️ Perlu sambung ulang	⭐ Tahan gangguan	Pada SSE, satu stream yang terputus (laptop sleep, pindah Wi-Fi, timeout Cloudflare) mengakhiri sesi sessionId — panggilan berikutnya gagal dan perlu reconnect. Pada Streamable HTTP, tiap panggilan tool berdiri sendiri sehingga cukup diulang.
Interupsi & Sinyal Darurat	⭐ Instan	⚠️ Terhenti (Tunggu Turn)	Agen AI dapat menerima sinyal darurat (seperti deteksi CAPTCHA / human intervention) di tengah proses automasi.

Ringkasnya: gunakan SSE bila klien Anda berjalan di mesin yang sama dengan server GoSosmed, dan Streamable HTTP bila klien berjalan di komputer Anda sendiri lewat internet.

---

1. Claude Desktop

Buka berkas konfigurasi Claude Desktop di komputer Anda:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Tambahkan konfigurasi gososmed pada bagian mcpServers:

{
  "mcpServers": {
    "gososmed": {
      "type": "sse",
      "url": "https://api.bamsbung.id/mcp/sse",
      "headers": {
        "Authorization": "Bearer gsk_live_GANTI_DENGAN_KUNCI_ANDA"
      }
    }
  }
}

Simpan berkas lalu buka ulang (restart) aplikasi Claude Desktop. Ikon palu (tools) akan menampilkan 24 tools GoSosmed yang siap digunakan.

---

2. Cursor IDE & Windsurf

Pada editor yang mendukung MCP (seperti Cursor IDE, Windsurf, atau ekstensi Roo Code di VS Code):

Opsi A: Melalui Antarmuka Pengaturan

1. Buka Settings -> Features -> MCP.
2. Klik tombol + Add New MCP Server.
3. Isi kolom:
   • Name: gososmed
   • Type: sse (atau http jika menggunakan Streamable)
   • Server URL: https://api.bamsbung.id/mcp/sse (atau https://api.bamsbung.id/mcp)
   • Headers: Tambahkan header Authorization dengan nilai Bearer gsk_live_....
4. Klik Save. Titik status akan berubah menjadi hijau (Connected).

Opsi B: Melalui Berkas Konfigurasi (.cursor/mcp.json)

{
  "mcpServers": {
    "gososmed": {
      "url": "https://api.bamsbung.id/mcp/sse",
      "headers": {
        "Authorization": "Bearer gsk_live_GANTI_DENGAN_KUNCI_ANDA"
      }
    }
  }
}

---

3. Claude Code (CLI)

Untuk menghubungkan antarmuka terminal Claude Code, tambahkan server melalui perintah CLI:

claude mcp add gososmed https://api.bamsbung.id/mcp/sse --header "Authorization: Bearer gsk_live_GANTI_DENGAN_KUNCI_ANDA"

Verifikasi dengan menjalankan claude mcp list di terminal Anda.

---

4. ZeroClaw AI Agent Framework

Bagi Anda yang menggunakan orkestrator ZeroClaw, daftarkan GoSosmed MCP Hub sebagai server MCP pada berkas konfigurasi ZeroClaw Anda (~/.zeroclaw/config.toml):

[[mcp.servers]]
name = "gososmed"
transport = "sse"
url = "https://api.bamsbung.id/mcp/sse"
headers = { Authorization = "Bearer gsk_live_GANTI_DENGAN_KUNCI_ANDA" }
tool_timeout_secs = 60

Pastikan agent ZeroClaw Anda diberi izin memakai server di atas sesuai mekanisme scoping pada dokumentasi resmi ZeroClaw. Bila konfigurasi Anda benar, 24 tools GoSosmed akan tersedia dan siap dipanggil oleh agen.

---

5. Integrasi Python Script

Anda dapat mengontrol HP Android dari skrip Python menggunakan pustaka resmi mcp via transport SSE:

import asyncio
from mcp.client.sse import sse_client
from mcp.client.session import ClientSession

API_KEY = "gsk_live_GANTI_DENGAN_KUNCI_ANDA"
MCP_SSE_URL = "https://api.bamsbung.id/mcp/sse"

async def main():
    headers = {"Authorization": f"Bearer {API_KEY}"}
    async with sse_client(MCP_SSE_URL, headers=headers) as (read_stream, write_stream):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            # 1. Periksa daftar perangkat online
            devices = await session.call_tool("list_devices", arguments={"status": "online"})
            print("Perangkat aktif:", devices.content)

            # 2. Ambil observasi visual Set-of-Marks
            obs = await session.call_tool("annotated_screenshot", arguments={})
            print("Observasi visual berhasil diterima.")

            # 3. Klik tombol Posting secara semantik (Pilar 0 Anti-Fragile)
            await session.call_tool("click_element", arguments={"text": "Posting"})

if __name__ == "__main__":
    asyncio.run(main())

---

6. Integrasi Node.js / TypeScript

Contoh pemanggilan menggunakan SDK resmi @modelcontextprotocol/sdk via SSE:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

async function run() {
  const apiKey = "gsk_live_GANTI_DENGAN_KUNCI_ANDA";
  const transport = new SSEClientTransport(
    new URL("https://api.bamsbung.id/mcp/sse"),
    {
      requestInit: {
        headers: { Authorization: `Bearer ${apiKey}` },
      },
    }
  );

  const client = new Client({ name: "my-automation-app", version: "1.0.0" }, { capabilities: {} });
  await client.connect(transport);

  // Panggil tool list_accounts
  const result = await client.callTool({
    name: "list_accounts",
    arguments: { platform: "instagram" },
  });

  console.log("Akun Instagram terhubung:", result);
}

run().catch(console.error);

---

Pemecahan Masalah Koneksi Klien

Gejala Galat	Akar Penyebab	Solusi
HTTP 401 Unauthorized	Kunci API salah, kedaluwarsa, atau format header Bearer tidak lengkap.	Pastikan header menyertakan Bearer sebelum kunci gsk_live_.... Periksa status kunci di menu Settings -> API Keys.
HTTP 403 Forbidden	Kunci API telah dicabut atau ruang kerja (tenant) disuspend.	Terbitkan kunci API baru di dasbor GoSosmed.
Tool Call Timeout (>30s)	HP target dalam kondisi mati, sleep, atau koneksi WebSocket terputus.	Buka aplikasi Mobile Agent di HP, pastikan status perangkat menampilkan indikator hijau terhubung.
device_offline Error	Tidak ada perangkat fisik yang online pada akun Anda.	Pastikan agent Android aktif dan tidak dibatasi optimasi baterai (lihat Pemecahan Masalah Baterai).