# Hubungkan Asisten AI (MCP) Your AI Connector menyediakan **server MCP** resmi — sebuah endpoint Model Context Protocol yang memungkinkan asisten AI seperti **Claude Code**, **Claude Desktop**, **Cursor**, dan aplikasi Anda sendiri untuk mengoperasikan akun Your AI Connector Anda secara langsung. Tanyakan dengan bahasa sehari-hari ("list my AI agents", "add this lead", "what did AI cost me this week?") dan asisten akan memanggil API Your AI Connector untuk Anda. Ini adalah API v1 yang sama yang Anda akses dengan [kunci API](api-access.md), yang diautentikasi dengan kunci API Anda sendiri. Server MCP membangun satu alat untuk setiap operasi dalam spesifikasi API kami yang dipublikasikan, sehingga mencakup sebagian besar, namun tidak semua, API v1: kontak, pesan, kampanye, agen AI, fungsi kustom, basis pengetahuan, janji temu, analitik, tag, daftar, siaran, kesepakatan, koneksi saluran, dan sub-akun. Otomatisasi dapat dicantumkan dan dibaca, tetapi belum dapat dibuat atau diedit melalui MCP; buatlah otomatisasi tersebut di dalam aplikasi. Di dalam apa yang dieksposnya, tidak ada izin per-alat dan tidak ada default baca-saja, jadi kunci API adalah satu-satunya kontrol akses. - **Endpoint:** `https://mcp.youraiconnector.com/mcp` - **Otentikasi:** kunci API Your AI Connector Anda (dikirim sebagai header `X-API-Key`) - **Memerlukan:** paket dengan akses API. [Buat kunci API →](api-access.md#generating-your-api-key) > Kunci API Anda bertindak atas **akun Anda sendiri**, dengan izin yang sama seperti > sisa API lainnya — dan dapat membaca akun klien yang Anda kelola, jika Anda menggunakan > paket agensi (lihat di bawah). Perlakukan kunci ini seperti kata sandi. Anda dapat mencabutnya kapan saja dari > Pengaturan → Integrasi → Kunci API, yang akan langsung memutus akses asisten. ## Claude Code ```bash claude mcp add --transport http ai-connector https://mcp.youraiconnector.com/mcp \ --header "X-API-Key: YOUR_API_KEY" ``` Kemudian jalankan `/mcp` di dalam Claude Code untuk memastikan bahwa ia menampilkan **ai-connector ✓ connected**. Secara default, server ditambahkan pada cakupan **lokal** (hanya Anda, proyek ini). Gunakan `--scope user` untuk membuatnya tersedia di semua proyek Anda, atau `--scope project` to commit it to a repo's `.mcp.json` untuk tim Anda: ```json { "mcpServers": { "ai-connector": { "type": "http", "url": "https://mcp.youraiconnector.com/mcp", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` ## Claude Desktop Tambahkan server sebagai konektor kustom. Server ini disiapkan di akun Claude Anda, sehingga berfungsi di Claude Desktop maupun di claude.ai (akun Claude gratis dapat menambahkan satu konektor kustom). 1. Buka **Customize → Connectors**, klik **+ Add**, lalu **Add custom connector**. 2. Beri nama dan masukkan `https://mcp.youraiconnector.com/mcp` sebagai URL. 3. Di bawah **Authentication**, pilih **No sign in**. Server MCP tidak memiliki halaman masuk: memilih opsi masuk akan berakhir dengan "Couldn't register with … sign-in service". 4. Di bawah **Request headers**, tambahkan header bernama `X-API-Key` dengan kunci API Anda sebagai nilainya. 5. Klik **Add**. Alat Your AI Connector akan muncul di menu alat pada obrolan baru. **Tidak ada kolom Request headers?** Versi Claude Desktop Anda sudah lama: perbarui, atau gunakan file konfigurasi sebagai gantinya. File konfigurasi (`claude_desktop_config.json`, Settings → Developer → Edit Config) hanya menjalankan program di komputer Anda dan mengabaikan entri `url`, sehingga memerlukan jembatan `mcp-remote` kecil, yang membutuhkan [Node.js](https://nodejs.org) 18 atau yang lebih baru: ```json { "mcpServers": { "ai-connector": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.youraiconnector.com/mcp", "--header", "X-API-Key:${AI_CONNECTOR_KEY}" ], "env": { "AI_CONNECTOR_KEY": "YOUR_API_KEY" } } } } ``` Biarkan `X-API-Key:${AI_CONNECTOR_KEY}` persis seperti yang tertulis, tanpa spasi setelah titik dua (di Windows, spasi akan memisahkan header), dan masukkan kunci Anda hanya di `env`. Kemudian tutup sepenuhnya Claude Desktop (di Windows, klik kanan ikon baki → Quit) dan buka kembali. ## ChatGPT ChatGPT tidak dapat terhubung ke server MCP saat ini. Formulir konektor kustomnya hanya menawarkan **OAuth** atau **Tanpa autentikasi**, sedangkan server MCP Your AI Connector masuk dengan kunci API Anda, yang dikirim sebagai header permintaan. Memilih OAuth akan gagal dengan pesan "could not discover OAuth settings", dan Tanpa autentikasi ditolak karena setiap permintaan memerlukan kunci tersebut. Gunakan asisten yang memungkinkan Anda untuk mengatur header permintaan sebagai gantinya: [Claude Code](#claude-code), [Claude Desktop](#claude-desktop), [Cursor atau klien MCP lainnya](#cursor--other-mcp-clients), atau [API Claude](#the-claude-api-build-it-into-your-own-app). ChatGPT masih dapat membaca dokumen bantuan tanpa koneksi: lihat [Dokumen bantuan sudah disertakan](#the-help-docs-are-built-in) untuk file `llms.txt` publik. ## Cursor & klien MCP lainnya Sebagian besar editor yang mendukung MCP menggunakan bentuk `.mcp.json` yang sama seperti yang ditunjukkan di atas (server HTTP dengan `url` dan header `X-API-Key`). Tambahkan server `ai-connector` yang mengarah ke `https://mcp.youraiconnector.com/mcp` dan tempelkan kunci API Anda di header. ## API Claude (bangun ke dalam aplikasi Anda sendiri) Anda dapat menghubungkan server MCP secara terprogram dengan konektor MCP API Claude, sehingga agen yang Anda bangun dapat menggunakan alat Your AI Connector tanpa klien terpisah: ```json { "model": "claude-opus-4-8", "messages": [{ "role": "user", "content": "List my AI agents" }], "mcp_servers": [ { "type": "url", "name": "ai-connector", "url": "https://mcp.youraiconnector.com/mcp", "authorization_token": "YOUR_API_KEY" } ] } ``` ## Apa yang dapat Anda lakukan Dalam bagian API v1 yang diekspos oleh server MCP, asisten akan memilih alat yang tepat secara otomatis: - **Agen AI:** daftar, buat, perbarui, jeda/lanjutkan, periksa konfigurasi. - **Kontak:** cari, buat, beri tag, tambahkan ke daftar, impor. - **Basis pengetahuan / FAQ:** tambahkan, edit, impor massal, setujui saran AI. - **Pesan:** baca percakapan, kirim pesan ke kontak. - **Janji temu:** daftar, pesan, batalkan. - **Tugas:** buat, selesaikan, daftar. - **Analitik:** statistik pesan, penggunaan kredit, biaya AI. - **Saluran:** periksa status koneksi, mulai alur koneksi. ## Bertanya tentang akun klien Anda (agensi) Satu koneksi mencakup setiap akun yang Anda kelola. Anda tidak perlu menambahkan koneksi kedua per klien: pada paket agensi, asisten dapat membaca akun klien mana pun di bawah Anda, sehingga Anda dapat bertanya tentang semuanya dalam satu percakapan. Cukup sebutkan nama kliennya: - "Berapa banyak kontak yang dimiliki Bella's Bistro?" - "Berapa biaya AI untuk setiap klien saya minggu ini?" - "Bagaimana status saluran Northside Dental, dan berapa banyak obrolan yang masuk minggu ini?" Ini mencakup pembacaan kontak, pesan, obrolan, kampanye, janji temu, tugas, tag, acara, FAQ, sumber basis pengetahuan, nomor telepon, saluran, webhook, dan analitik. Kami memeriksa apakah akun tersebut benar-benar milik Anda sebelum menjalankan apa pun — meminta akun yang bukan milik Anda akan menghasilkan respons "tidak ditemukan". Abaikan klien dan asisten akan membaca akun Anda sendiri, persis seperti sebelumnya. **Mengubah akun klien** bekerja dengan cara yang sama. Setiap tindakan yang menerima akun klien dalam API tersedia untuk klien bernama: menyiapkan agen AI, basis pengetahuan, fungsi kustom, templat WhatsApp, titik masuk, koneksi saluran, kontak, tag, siaran, janji temu, kesepakatan dan tugas, serta mengirim pesan. Pengecualiannya adalah tindakan tingkat agensi, yang selalu berjalan pada akun agensi Anda sendiri: mengelola akun klien itu sendiri (batas, fitur, harga, penangguhan), snapshot, tim Anda, dan kunci API. Menambahkan kontak ke atau menghapus kontak dari daftar klien belum tersedia untuk klien bernama; lakukan hal tersebut dari kunci klien itu sendiri atau di akun mereka. [Panduan API agensi](../agency/api-for-agencies.md#where-sub_account_id-is-supported) mencantumkan apa saja yang didukung. ::: neutral-mcp Alat agensi hanya tersedia di alamat standar tanpa merek, `https://mcp.youraiconnector.com/mcp`. Alamat MCP white-label di domain Anda sendiri (`mcp.youragency.com`) dibuat untuk klien Anda dan tidak menyertakan alat tersebut, jadi gunakan alamat standar tanpa merek saat Anda mengelola akun klien. ::: Ini juga merupakan jawaban bagi klien yang menjalankan **beberapa bisnis di bawah satu login**. Berikan setiap bisnis akunnya sendiri, lalu undang email klien sebagai anggota tim di semua akun tersebut: mereka masuk sekali dan beralih antar merek mereka dengan pemilih akun di bilah sisi. ### Menguji agen klien Minta asisten untuk mencoba agen klien ("kirim 'apakah Anda melayani pengiriman di hari Minggu?' ke agen Bakery milik klien X dan tunjukkan apa yang dilakukannya"). Asisten akan mengirim pesan Uji Coba dengan kunci agensi Anda dan `sub_account_id` klien, menunggu, lalu membaca balasan serta tindakan apa pun yang dilakukan agen tersebut. Tidak diperlukan salinan agen. Jika asisten mengatakan bahwa Anda bukan akun agensi, berarti asisten terhubung dengan kunci klien: hubungkan kembali dengan kunci akun agensi Anda. Lihat [Uji Coba](../chats/playground.md#testing-an-agent-from-the-api-or-an-ai-assistant). ## Klien dengan batas alat ::: neutral-mcp Beberapa klien AI hanya menerima server dengan jumlah alat yang terbatas. Composio, misalnya, menolak server yang mencantumkan lebih dari 500 alat dan tidak mengimpor satu pun. Koneksi agensi penuh mencantumkan lebih dari itu, jadi tambahkan `?tags=` ke alamat dengan hanya grup alat yang Anda butuhkan. Untuk agensi yang ingin mencantumkan akun kliennya, membaca kontak, obrolan, dan pesan mereka, serta mengirim pesan: ``` https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages ``` Itu memuat sekitar 80 alat. Sebutkan nama klien dalam permintaan Anda dan asisten akan bertindak atas akun klien tersebut, seperti yang dijelaskan di atas. - Pisahkan grup dengan koma; huruf besar atau kecil keduanya berfungsi. - Untuk menambahkan alat tunggal, cantumkan nama persisnya dengan `tools=`, misalnya `?tags=Contacts&tools=list_or_get_subaccounts`. Anda mendapatkan setiap alat dari salah satu daftar. - Alat dokumen bantuan selalu disertakan. - Kunci API tetap dimasukkan di header `X-API-Key` (atau `Authorization: Bearer YOUR_API_KEY`), tidak pernah di alamat. ::: ## Dokumen bantuan sudah terpasang Server MCP memberikan **akun** Anda dan **dokumentasi** ini kepada asisten. Tiga alat membaca dokumen bantuan secara langsung, sehingga asisten dapat mencari tahu cara kerja suatu fitur, atau apa yang baru saja berubah, alih-alih menebak-nebak: - `docs_search`: menemukan bagian yang menjawab pertanyaan dan mengembalikannya dengan tautan halaman. - `docs_read`: membaca satu halaman secara penuh, atau salah satu bagiannya. - `docs_list`: mencantumkan setiap halaman berdasarkan area. Tidak ada yang perlu disiapkan, dan alat dokumen tidak pernah menyentuh data akun Anda. Tanyakan "bagaimana cara kerja titik masuk?" atau "apa yang baru di otomatisasi?" dan asisten akan mencari dokumen terlebih dahulu. Karena alat tersebut membaca situs bantuan itu sendiri, suatu fitur akan diketahui oleh asisten Anda segera setelah panduannya diterbitkan. Asisten yang tidak terhubung melalui MCP masih dapat membaca dokumen: arahkan ke `https://docs.youraiconnector.com/llms.txt` (indeks setiap halaman bantuan dengan tautan ke versi Markdown setiap halaman) atau `https://docs.youraiconnector.com/llms-full.txt` (seluruh dokumentasi dalam satu file Markdown). Keduanya bersifat publik, tidak memerlukan kunci, dan dibangun kembali dengan setiap perubahan dokumentasi. ## Menemukan atau Membuat Kunci API Anda Kunci API yang digunakan koneksi ini berada di **Pengaturan → Integrasi → Kunci API** — bagian tersendiri, terpisah dari Webhook. Lihat [Akses API](api-access.md#generating-your-api-key) untuk langkah-langkah pastinya. ## Pemecahan Masalah - **"Connection refused" atau "not found"** — alamat tersebut tidak menyertakan `/mcp` di bagian akhir. Gunakan `https://mcp.youraiconnector.com/mcp`, bukan `https://mcp.youraiconnector.com`. - **`Needs authentication` / 401** — kunci API Anda hilang atau salah. Tambahkan kembali server dengan `X-API-Key` yang valid. - **"Could not discover OAuth settings" (ChatGPT)** — ChatGPT hanya mendukung OAuth atau tanpa autentikasi untuk konektor kustom, dan server MCP menggunakan kunci API, sehingga ChatGPT tidak dapat terhubung untuk saat ini. Lihat [ChatGPT](#chatgpt). - **"Couldn't register with … sign-in service" atau "add an OAuth Client ID" (Claude Desktop)** — konektor kustom ditambahkan dengan opsi masuk. Tidak ada ID klien OAuth untuk dimasukkan: hapus konektor dan tambahkan kembali dengan **Authentication → No sign in** dan kunci API Anda sebagai header permintaan `X-API-Key`, seperti di [Claude Desktop](#claude-desktop). - **Claude Desktop tidak menampilkan alat setelah mengedit file konfigurasi** — file konfigurasi mengabaikan entri `"url"`; gunakan konektor kustom atau formulir `mcp-remote` di [Claude Desktop](#claude-desktop), lalu tutup sepenuhnya dan buka kembali aplikasinya. - **Alat mengembalikan `403`** — paket atau peran tim Anda tidak mengizinkan tindakan tersebut; server MCP tidak menerapkan batasan tambahan, ini adalah pemeriksaan izin yang sama dengan API. - **Tool not found** — daftar alat dibuat secara langsung dari API, sehingga selalu cocok dengan versi saat ini; sambungkan kembali untuk menyegarkan. - **Peringatan keamanan atau sertifikat pada domain Anda sendiri** — mengarahkan catatan DNS ke kami saja tidak cukup: subdomain juga harus diverifikasi di dasbor sebelum dapat menyajikan koneksi yang aman. Agensi white-label dapat menempatkan alamat MCP di domain mereka sendiri (misalnya `mcp.youragency.com`) dari kartu **Custom domain** di bawah **Settings → White Labeling** — tambahkan CNAME di registrar Anda terlebih dahulu, lalu masukkan nama host di blok **MCP domain (AI assistants)** dan klik **Verify**, alur yang sama seperti subdomain bermerek Anda yang lain. Alamat bermerek tidak menyertakan alat agensi; terus gunakan alamat standar tanpa merek untuk alat tersebut. Sampai alamat bermerek Anda diverifikasi, gunakan alamat standar tanpa merek: aman untuk dibagikan kepada klien. --- ## Langkah Selanjutnya - [Akses API](api-access.md) — buat atau rotasi kunci yang digunakan koneksi ini. - [Webhook](webhooks.md) — mitra berbasis push untuk koneksi MCP berbasis pull ini.