OAuth untuk klien MCP kustom

Jika Anda membangun klien MCP sendiri (CLI, SDK, plugin IDE), halaman ini menjelaskan implementasi OAuth kami: standar yang kami dukung, endpoint, aturan redirect_uri, dan cara mendebug error umum. Pengguna Claude.ai dan ChatGPT tidak memerlukan halaman ini — gunakan Quickstart saja.

Standar yang kami implementasikan

mcp-telegram.com sepenuhnya patuh terhadap spesifikasi OAuth yang menjadi tumpuan ekosistem MCP — tanpa ekstensi proprietary, tanpa shared secret yang ditanam dalam klien.

RFC 6749 — OAuth 2.0 Authorization Framework — authorization code grant dasar dengan refresh token
RFC 7591 — Dynamic Client Registration — klien mana pun dapat mendaftar sendiri di /oauth/register tanpa koordinasi sebelumnya
RFC 7636 — PKCE (Proof Key for Code Exchange) — challenge S256 wajib untuk klien publik
RFC 8252 — OAuth 2.0 for Native Apps — redirect URI loopback IP dengan fleksibilitas port ephemeral
RFC 8414 — OAuth 2.0 Authorization Server Metadata — dokumen discovery di /.well-known/oauth-authorization-server
RFC 9728 — OAuth 2.0 Protected Resource Metadata — discovery batas resource MCP

Endpoint

Metadata authorization server (RFC 8414)

Dynamic client registration (RFC 7591)

Authorization endpoint

Token endpoint

Resource MCP (Streamable HTTP)

Authorization code flow dengan PKCE

Flow standar RFC 6749 §4.1 + RFC 7636. Tanpa kejutan — jika library OAuth Anda menangani "authorization code + PKCE", maka akan langsung bekerja.

Daftarkan klien Anda

POST /oauth/register dengan { redirect_uris: ["http://127.0.0.1:<port>/callback"], client_name: "nama-klien-anda" }. Server mengembalikan client_id + client_secret (secret bersifat opsional untuk klien publik PKCE, tapi tidak ada salahnya menerimanya).

Buat pasangan PKCE

Buat code_verifier acak sepanjang 43–128 karakter, lalu hitung code_challenge = BASE64URL(SHA256(code_verifier)). Simpan verifier secara lokal untuk langkah 4.

Buka /oauth/authorize di browser

Redirect pengguna ke /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256. Server menampilkan kode QR; pengguna memindainya di aplikasi Telegram untuk autentikasi.

Terima authorization code

Setelah QR dipindai, server me-redirect ke redirect_uri Anda dengan ?code=...&state=.... Verifikasi bahwa parameter state cocok dengan yang Anda kirim.

Tukar code dengan token

POST /oauth/token dengan grant_type=authorization_code, code, redirect_uri, code_verifier, client_id. Anda akan menerima access_token (TTL 10 tahun — lihat Token Lifetime di bawah) dan refresh_token. Gunakan access_token sebagai Authorization: Bearer ... pada request ke /mcp.

Aturan matching redirect_uri

Kami mengikuti RFC 8252 §7.3 dan §8.4 secara ketat. Algoritma matching tergantung pada apakah URI terdaftar adalah literal IP loopback.

Loopback (http://127.0.0.1 atau http://[::1])

Jika Anda mendaftarkan URI loopback, redirect_uri pada saat authorize harus cocok persis di scheme, host, path, dan query — tetapi port boleh berbeda. Ini diwajibkan oleh RFC 8252 §7.3 karena klien native mengikat port ephemeral yang ditetapkan OS yang bisa berubah antar run.

Terdaftar http://127.0.0.1:36201/callback cocok dengan authorize-time http://127.0.0.1:50000/callback ✅
Terdaftar http://127.0.0.1:36201/callback TIDAK cocok dengan http://127.0.0.1:50000/different-path — path harus persis
Terdaftar http://[::1]:36201/cb TIDAK cocok dengan http://127.0.0.1:36201/cb — loopback IPv4 dan IPv6 adalah identifier yang terpisah

HTTPS (https://your-domain.example/...)

Kecocokan persis byte-per-byte diperlukan, termasuk path, query, dan port (RFC 6749 §3.1.2). Tanpa fleksibilitas.

localhost (TIDAK direkomendasikan)

Kami memperlakukan http://localhost sebagai hostname biasa — diperlukan kecocokan persis, tanpa fleksibilitas port. RFC 8252 §8.3 merekomendasikan menggunakan literal IP (127.0.0.1 / [::1]) sebagai pengganti localhost karena resolusi DNS bergantung pada implementasi.

PKCE wajib

code_challenge_method=S256 wajib pada setiap authorize request. Method plain ditolak. Jika Anda melewatkan code_challenge sama sekali, pertukaran /token akan gagal saat validasi code_verifier.

Masa berlaku token

TTL access_token sengaja dibuat panjang (10 tahun) karena beberapa klien MCP tidak menyimpan refresh_token dengan andal. refresh_token tetap diterbitkan dan dirotasi pada setiap refresh (RFC 6819 §5.2.2.3). Pengguna dapat mencabut semua token kapan saja di /my/sessions atau dengan logout dari Telegram. Pengguna juga dapat secara eksplisit POST ke /oauth/revoke (RFC 7009) untuk mengakhiri sesi.

Error umum

HTTP 400 "Invalid redirect_uri" di /oauth/authorize

Parameter query redirect_uri tidak cocok dengan URI mana pun yang terdaftar untuk client_id ini. Untuk klien loopback: pastikan scheme + host + path + query cocok persis (hanya port yang fleksibel). Untuk klien HTTPS: kesetaraan byte penuh diperlukan — perhatikan trailing slash dan perbedaan URL-encoding.

HTTP 400 "Unknown client"

client_id tidak ada di database kami. Bisa jadi Anda melewatkan langkah /oauth/register, respons registrasi hilang sebelum Anda menyimpan client_id, atau klien dicabut oleh pengguna melalui /my/clients.

Klien terus-menerus menampilkan "Needs Auth"

Jika klien Anda menyimpan access_token tetapi tidak refresh_token, Anda akan melihat ini ketika access_token kedaluwarsa. Access token kami memiliki TTL 10 tahun khusus untuk meredam hal ini, tetapi jika klien Anda meng-expire token di sisi klien setelah jendela yang lebih pendek, Anda perlu menyimpan refresh_token atau memanggil /oauth/revoke + re-auth on demand.

Klien yang diuji

Dikonfirmasi dapat beroperasi dengan server kami. Jika Anda membangun sesuatu yang baru dan berhasil, kirimkan PR untuk menambahkannya di sini.

Claude.ai web — melalui konektor MCP bawaan
ChatGPT Apps — melalui konektor MCP bawaan
Hermes Agent — klien CLI MCP open-source (RFC 8252 loopback flow)
Cursor MCP — plugin IDE (RFC 8252 loopback flow)
Klien apa pun yang patuh terhadap RFC 6749 + RFC 7591 + RFC 7636 + RFC 8252 seharusnya bekerja tanpa perubahan kode di sisi kami.

Beberapa akun Telegram pada satu koneksi OAuth

Sejak v2.32.0, satu koneksi OAuth dapat menampung beberapa identitas Telegram dan beralih di antaranya hanya dengan satu pemanggilan tool — tanpa siklus Disconnect/Connect, tanpa pendaftaran client baru.

Lihat akun yang terpasang

Panggil telegram-accounts-list. Anda akan melihat akun primary (yang terikat OAuth) Anda ditandai dengan ⭐ jika sedang aktif, beserta akun-akun sekunder yang telah Anda tambahkan.

Pasang akun lain

Panggil telegram-accounts-add dengan label opsional (misalnya "testing"). Tool ini mengembalikan URL sekali pakai (TTL 10 menit) — buka URL tersebut di perangkat apa pun dan pindai QR dengan akun Telegram yang ingin Anda tambahkan.

Beralih akun aktif

Panggil telegram-accounts-switch dengan identifier=label, @username, account_id, atau 'primary'. Pemanggilan tool telegram-* berikutnya akan langsung menggunakan akun tersebut. Tanpa reconnect.

Lepaskan akun sekunder

Panggil telegram-accounts-remove identifier=… pada akun sekunder. Akun Telegram itu sendiri TIDAK di-log out — hanya pengikatannya di sini yang dihapus. Akun primary tidak dapat dihapus dengan cara ini; gunakan alur Disconnect pada klien Anda untuk keluar sepenuhnya.

Setiap koneksi OAuth terisolasi: akun-akun yang Anda pasang melalui Hermes tidak terlihat oleh Claude.ai atau ChatGPT, bahkan jika identitas Telegram-nya sama. Untuk menghubungkan akun yang berbeda ke klien MCP yang berbeda, daftarkan setiap klien secara terpisah dan gunakan telegram-accounts-add di dalam sesinya masing-masing.