> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Server MCP

> Izinkan agen AI menggunakan WhatsApp melalui endpoint Model Context Protocol bawaan GOWA di /mcp.

GOWA menyediakan endpoint [Model Context Protocol](https://modelcontextprotocol.io) dari proses yang sama dengan REST API. Semua klien MCP yang mendukung transport **streamable HTTP** dapat mengirim pesan, membaca chat, dan mengelola grup melaluinya.

* URL: `http://<host>:3000<APP_BASE_PATH>/mcp` (default `http://localhost:3000/mcp`)
* Aktif secara default. Nonaktifkan dengan `MCP_ENABLED=false` or `--mcp-enabled=false`.
* Stateless: tidak ada handshake sesi yang perlu dipertahankan di antara pemanggilan.

> [!NOTE]
>
> Jika Anda memperbarui dari rilis lama, perintah mandiri `./whatsapp mcp` dan endpoint SSE-nya pada port 8080 (`/sse`) sudah dihapus. Jalankan `./whatsapp rest` dan arahkan klien ke `/mcp`. Kumpulan tool lama yang menyediakan satu tool untuk setiap operasi telah diganti dengan tool terpadu di bawah ini.

## Hubungkan klien

`/mcp` dilindungi Basic Auth yang sama dengan REST API. Kirim header `Authorization`, serta `X-Device-Id` jika Anda menjalankan lebih dari satu perangkat:

```json theme={null}
{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic YWRtaW46Y2hhbmdlbWU=",
        "X-Device-Id": "my-device"
      }
    }
  }
}
```

`YWRtaW46Y2hhbmdlbWU=` adalah `base64("admin:changeme")`; buat nilai Anda sendiri dengan `echo -n 'user:pass' | base64`. Hilangkan `Authorization` jika Basic Auth tidak aktif, dan `X-Device-Id` jika hanya ada satu perangkat.

Format konfigurasi bergantung pada klien. Jika klien hanya dapat menjalankan server stdio, gunakan perantara seperti `mcp-remote`.

## Tool

GOWA menyediakan tujuh tool. Masing-masing menerima argumen `type` (untuk pengiriman) atau `action` (untuk semua tool lainnya) untuk memilih operasi.

| Tool | Nilai `type` / `action` |
| - | - |
| `whatsapp_send` | `text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `poll`, `link`, `forward` |
| `whatsapp_schedule` | `list`, `get`, `pause`, `resume`, `cancel` |
| `whatsapp_message` | `react`, `edit`, `revoke`, `delete`, `mark_read`, `mark_played`, `star`, `unstar`, `download_media` |
| `whatsapp_chat` | `list_chats`, `list_contacts`, `get_messages`, `archive` |
| `whatsapp_group` | `create`, `join_with_link`, `leave`, `info`, `participants`, `add_participants`, `remove_participants`, `promote`, `demote`, `invite_link`, `set_name`, `set_topic`, `set_settings`, `join_requests`, `manage_join_requests` |
| `whatsapp_app` | `status`, `login_qr`, `login_code`, `logout`, `reconnect` |
| `whatsapp_newsletter` | `follow`, `unfollow`, `info`, `directory`, `messages`, `message_updates`, `live_updates_subscribe`, `live_updates_unsubscribe`, `live_updates_list` |

Catatan tentang argumen:

* `whatsapp_send` selalu memerlukan `type` dan `phone`. Media dikirim **hanya melalui URL** (`image_url`, `video_url`, `audio_url`, `file_url`, `sticker_url`); MCP tidak dapat mengunggah file lokal. `link` memerlukan `link` dan `caption`; `forward` memerlukan `message_id`.
* `whatsapp_send` menerima [field jadwal](https://gowa-docs.mintlify.site/id/examples/scheduled-sends.md) (`scheduled_at`, `timezone`, `recurrence`, `weekdays`, `day_of_month`, `end_at`, `occurrence_limit`). Kelola hasilnya dengan `whatsapp_schedule` (`get`, `pause`, `resume`, dan `cancel` memerlukan `schedule_id`).
* `whatsapp_message` memerlukan `phone` (chat) dan `message_id`; `edit` juga memerlukan `message`.
* Pada GOWA `main` setelah v9.9.0, `whatsapp_message` dengan `action: "edit"` menerima `media_type: "image"` atau `media_type: "document"` untuk mengganti caption. Sesuaikan dengan jenis media asli dan hilangkan `link`. Lihat [Edit caption](https://gowa-docs.mintlify.site/id/examples/sending-messages.md#mengedit-keterangan-gambar-atau-dokumen).
* `whatsapp_chat`: `get_messages` memerlukan `chat_jid`; `archive` memerlukan `chat_jid` dan `archived`.
* `whatsapp_app`: `login_code` memerlukan `phone`.

Pengiriman tombol, permintaan lokasi, dan carousel yang bersifat eksperimental hanya tersedia melalui REST. Lihat [pesan interaktif](https://gowa-docs.mintlify.site/id/examples/interactive-messages.md). Tool newsletter mendukung penemuan saluran, penghitung riwayat, dan langganan pembaruan langsung yang diperpanjang secara otomatis. Lihat [newsletter](https://gowa-docs.mintlify.site/id/examples/newsletters.md).

Pengunduhan URL media menerapkan pemeriksaan alamat publik yang sama dengan pengiriman REST dan terhubung langsung tanpa `HTTP_PROXY` atau `HTTPS_PROXY`. Pengunggahan file lokal memerlukan REST API.

Klien MCP menampilkan skema input lengkap setiap tool. Endpoint HTTP menerima POST dan DELETE. Streaming GET SSE dinonaktifkan.

## Pemilihan perangkat

Setiap pemanggilan menentukan perangkatnya dengan urutan berikut:

1. Argumen `device_id` pada pemanggilan tool.
2. Header `X-Device-Id` pada koneksi MCP.
3. Satu-satunya perangkat terdaftar, jika hanya ada satu perangkat.

Jika tidak, pemanggilan gagal dengan `device identification required: set the X-Device-Id header or pass device_id`. Lihat [Multi-perangkat](https://gowa-docs.mintlify.site/id/concepts/multidevice.md).

## Klien jarak jauh dengan OAuth

Klien yang dihosting, seperti konektor kustom Claude, tidak dapat menyertakan header Basic Auth. Untuk klien tersebut, GOWA dapat menjalankan server otorisasi OAuth 2.1 untuk `/mcp`. Fitur ini tidak aktif secara default.

```env theme={null}
APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com
# optional, defaults to issuer + APP_BASE_PATH + /mcp
MCP_OAUTH_RESOURCE_URL=https://gowa.example.com/mcp
```

Persyaratan dan perilaku:

* `APP_BASIC_AUTH` harus diatur: halaman otorisasi menggunakan akun yang sama untuk login pengguna. Proses startup gagal tanpa pengaturan ini.
* Issuer dan resource harus berupa URL **HTTPS publik** yang diakses klien, bukan alamat internal seperti `http://gowa:3000`.
* Saat OAuth aktif, `/mcp` menerima token Bearer **atau** Basic Auth. Token tidak diterima pada rute REST atau UI.
* Klien mendaftarkan dirinya sendiri (pendaftaran klien dinamis RFC 7591). Body pendaftaran dibatasi hingga 16 KiB dan setiap URI pengalihan hingga 2 KiB. Pendaftaran dibatasi hingga 40 per jam dan 1,000 klien tersimpan; klien yang tidak digunakan dihapus setelah 24 jam.
* PKCE `S256` wajib digunakan. Kode kedaluwarsa setelah 5 menit, token akses setelah 1 jam; refresh token dirotasi, dan penggunaan ulang token lama mencabut seluruh keluarga token. Hanya hash SHA-256 token yang disimpan, di `MCP_OAUTH_DB_URI` (default `file:storages/oauth.db`).

URI pengalihan harus sama persis dengan nilai yang didaftarkan. Klien native dapat menggunakan callback IP loopback HTTP dengan port dinamis. Callback `localhost` memerlukan port eksplisit dan kecocokan persis. Pengalihan lainnya memerlukan HTTPS. OAuth `resource` terikat pada URL MCP kanonis; permintaan token boleh menghilangkannya, tetapi nilai yang disertakan harus cocok. Respons otorisasi yang berhasil menyertakan `iss`.

Kode dan token yang kedaluwarsa dihapus selama penulisan OAuth. Hash refresh token yang telah dirotasi dipertahankan selama diperlukan untuk mendeteksi penggunaan ulang pada keluarga token aktif, paling lama satu masa berlaku refresh token tambahan selama 30 hari. Menghapus atau mengganti database OAuth membatalkan klien dan pemberian akses yang ada.

Endpoint, relatif terhadap issuer: `/oauth/authorize`, `/oauth/token`, `/oauth/register`. Metadata discovery menggunakan URL well-known dengan penyisipan path pada root domain, sehingga dengan `APP_BASE_PATH=/gowa`, proxy Anda harus merutekan:

```text theme={null}
https://gowa.example.com/.well-known/oauth-authorization-server/gowa
https://gowa.example.com/.well-known/oauth-protected-resource/gowa/mcp
```

Periksa discovery dari luar:

```bash theme={null}
curl -i -X POST https://gowa.example.com/mcp          # expect 401 with a Bearer challenge
curl https://gowa.example.com/.well-known/oauth-protected-resource/mcp
curl https://gowa.example.com/.well-known/oauth-authorization-server
```

Lalu tambahkan `https://gowa.example.com/mcp` sebagai konektor kustom dan login dengan akun `APP_BASIC_AUTH`.

> [!WARNING]
>
> Pastikan Cloudflare Access, tantangan bot, atau proxy autentikasi di depan GOWA tidak mencegat path well-known, `/oauth/*`, atau `/mcp`. Batasi laju upaya login yang gagal pada `/oauth/authorize` di proxy Anda.


## Related topics

- [Pengiriman Terjadwal](https://gowa-docs.mintlify.site/id/examples/scheduled-sends.md)
- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/id/index.md)
- [Referensi API](https://gowa-docs.mintlify.site/id/api-reference/introduction.md)
- [Autentikasi API](https://gowa-docs.mintlify.site/id/api-reference/authentication.md)
- [Referensi Konfigurasi](https://gowa-docs.mintlify.site/id/configuration.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.