MCP TelegramÖzel MCP istemcileri için OAuth
Kendi MCP istemcini (CLI, SDK, IDE eklentisi) geliştiriyorsan, bu sayfa OAuth uygulamamızı anlatır: desteklediğimiz standartlar, uç noktalar, redirect_uri kuralları ve yaygın hataların nasıl giderileceği. Claude.ai ve ChatGPT kullanıcılarının bu sayfaya ihtiyacı yok — onun yerine Hızlı Başlangıç'a bak.
Uyguladığımız standartlar
mcp-telegram.com, MCP ekosisteminin dayandığı OAuth spesifikasyonlarına tamamen uyumludur — özel uzantılar yok, istemcilere gömülü paylaşılan sırlar yok.
- RFC 6749 — OAuth 2.0 Authorization Framework — refresh token'lı temel authorization code grant
- RFC 7591 — Dynamic Client Registration — her istemci /oauth/register üzerinden, önceden anlaşma olmadan kendini kaydedebilir
- RFC 7636 — PKCE (Proof Key for Code Exchange) — açık (public) istemciler için S256 challenge zorunlu
- RFC 8252 — OAuth 2.0 for Native Apps — loopback IP redirect URI ve geçici (ephemeral) port esnekliği
- RFC 8414 — OAuth 2.0 Authorization Server Metadata — /.well-known/oauth-authorization-server adresinde keşif belgesi
- RFC 9728 — OAuth 2.0 Protected Resource Metadata — MCP kaynak sınırının keşfi
Uç noktalar
PKCE ile authorization code akışı
Standart RFC 6749 §4.1 + RFC 7636 akışı. Sürpriz yok — OAuth kütüphanen "authorization code + PKCE" destekliyorsa çalışacak.
İstemcini kaydet
POST /oauth/register isteğini { redirect_uris: ["http://127.0.0.1:<port>/callback"], client_name: "istemci-adın" } ile gönder. Sunucu client_id + client_secret döner (secret, public PKCE istemcileri için isteğe bağlıdır ama almakta da bir zarar yoktur).
PKCE çiftini üret
43–128 karakterlik rastgele bir code_verifier üret, ardından code_challenge = BASE64URL(SHA256(code_verifier)) hesapla. Verifier'ı 4. adım için yerelde sakla.
Tarayıcıda /oauth/authorize'ı aç
Kullanıcıyı /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256 adresine yönlendir. Sunucu bir QR kodu gösterir; kullanıcı kimlik doğrulaması için bunu Telegram uygulamasında tarar.
Authorization code'unu al
QR taramasının ardından sunucu, redirect_uri'ne ?code=...&state=... ile geri yönlendirir. state parametresinin gönderdiğinle eşleştiğini doğrula.
Code'u token ile değiştir
POST /oauth/token isteğini grant_type=authorization_code, code, redirect_uri, code_verifier, client_id ile gönder. access_token (10 yıllık TTL — aşağıdaki Token Lifetime bölümüne bak) ve refresh_token alırsın. /mcp isteklerinde access_token'ı Authorization: Bearer ... olarak kullan.
redirect_uri eşleştirme kuralları
RFC 8252 §7.3 ve §8.4'ü sıkıca takip ediyoruz. Eşleştirme algoritması, kayıtlı URI'nın loopback IP literali olup olmadığına bağlıdır.
Loopback (http://127.0.0.1 veya http://[::1])
Loopback bir URI kaydettiysen, authorize sırasındaki redirect_uri scheme, host, path ve query bakımından tam olarak eşleşmek zorundadır — ancak port farklı olabilir. Bu, RFC 8252 §7.3 tarafından zorunlu kılınmıştır çünkü yerel (native) istemciler işletim sisteminin atadığı ve çalıştırmalar arasında değişebilen geçici (ephemeral) bir porta bağlanır.
- Kayıtlı http://127.0.0.1:36201/callback, authorize sırasındaki http://127.0.0.1:50000/callback ile eşleşir ✅
- Kayıtlı http://127.0.0.1:36201/callback, http://127.0.0.1:50000/different-path ile eşleşMEZ — path birebir aynı olmalıdır
- Kayıtlı http://[::1]:36201/cb, http://127.0.0.1:36201/cb ile eşleşMEZ — IPv4 ve IPv6 loopback ayrı tanımlayıcılardır
HTTPS (https://your-domain.example/...)
Path, query ve port dahil bayt bayt tam eşleşme zorunludur (RFC 6749 §3.1.2). Esneklik yoktur.
localhost (önerilmez)
http://localhost'u sıradan bir hostname olarak değerlendiriyoruz — tam eşleşme gerekir, portta esneklik yoktur. RFC 8252 §8.3, DNS çözümlemesi uygulamaya bağlı olduğundan, localhost yerine IP literalleri (127.0.0.1 / [::1]) kullanılmasını önerir.
PKCE zorunludur
code_challenge_method=S256 her authorize isteğinde gereklidir. Plain yöntemi reddedilir. code_challenge'ı tamamen atlarsan, /token değişimi code_verifier doğrulamasında başarısız olur.
Token ömrü
access_token TTL'i kasıtlı olarak uzundur (10 yıl), çünkü bazı MCP istemcileri refresh_token'ı güvenilir biçimde saklamaz. Yine de bir refresh_token verilir ve her yenilemede rotasyona girer (RFC 6819 §5.2.2.3). Kullanıcı, tüm token'ları istediği zaman /my/sessions üzerinden veya Telegram'dan çıkış yaparak iptal edebilir. Kullanıcı ayrıca bir oturumu sonlandırmak için açıkça /oauth/revoke (RFC 7009) adresine POST isteği gönderebilir.
Yaygın hatalar
/oauth/authorize'da HTTP 400 "Invalid redirect_uri"
redirect_uri query parametresi, bu client_id için kayıtlı hiçbir URI ile eşleşmiyor. Loopback istemciler için: scheme + host + path + query'nin birebir eşleştiğini kontrol et (yalnızca port esnektir). HTTPS istemciler için: tam bayt eşitliği gerekir — sondaki eğik çizgilere ve URL kodlama farklarına dikkat et.
HTTP 400 "Unknown client"
client_id veritabanımızda yok. Ya /oauth/register adımını atladın, ya client_id'yi kaydetmeden önce kayıt yanıtı kayboldu, ya da istemci kullanıcı tarafından /my/clients üzerinden iptal edildi.
İstemci sürekli "Needs Auth" gösteriyor
İstemcin access_token'ı saklıyor ama refresh_token'ı saklamıyorsa, access_token'ın süresi dolduğunda bunu görürsün. access token'larımız özellikle bunu hafifletmek için 10 yıllık TTL'e sahiptir; ancak istemcin token'ları daha kısa bir pencerede istemci tarafında süresi dolmuş kabul ediyorsa, ya refresh_token'ı saklamalı ya da gerektiğinde /oauth/revoke + yeniden auth çağırmalısın.
Test edilmiş istemciler
Sunucumuzla birlikte çalıştığı doğrulandı. Yeni bir şey geliştirip çalıştığında, bu listeye eklemek için bize PR gönder.
- Claude.ai web — yerleşik MCP connector aracılığıyla
- ChatGPT Apps — yerleşik MCP connector aracılığıyla
- Hermes Agent — açık kaynak CLI MCP istemcisi (RFC 8252 loopback akışı)
- Cursor MCP — IDE eklentisi (RFC 8252 loopback akışı)
- RFC 6749 + RFC 7591 + RFC 7636 + RFC 8252 ile uyumlu herhangi bir istemci, bizim tarafımızda kod değişikliği olmadan çalışmalıdır.
Tek bir OAuth bağlantısında birden fazla Telegram hesabı
v2.32.0 sürümünden itibaren tek bir OAuth bağlantısı birden çok Telegram kimliğini barındırabilir ve tek bir tool çağrısıyla aralarında geçiş yapabilirsiniz — Disconnect/Connect döngüsü yok, yeni client kaydı gerekmez.
Bağlı olanları listeleyin
telegram-accounts-list çağırın. Aktifse ⭐ ile işaretlenmiş primary (OAuth'a bağlı) hesabınızı ve eklediğiniz tüm ikincil hesapları görürsünüz.
Başka bir hesap ekleyin
telegram-accounts-add çağırın, isteğe bağlı bir label verin (ör. "testing"). Tool tek kullanımlık bir URL döndürür (TTL 10 minutes) — herhangi bir cihazda açın ve eklemek istediğiniz Telegram hesabıyla QR'ı tarayın.
Aktif hesabı değiştirin
telegram-accounts-switch çağırın; identifier=label, @username, account_id veya 'primary' verin. Sonraki telegram-* çağrısı anında bu hesabı kullanır. Yeniden bağlanma gerekmez.
İkincil hesabı kaldırın
İkincil bir hesap için telegram-accounts-remove identifier=… çağırın. Telegram hesabının kendisi oturumdan ÇIKMAZ — yalnızca buradaki bağ kaldırılır. Primary bu yolla kaldırılamaz; tamamen oturum kapatmak için istemcinizin Disconnect akışını kullanın.
Her OAuth bağlantısı yalıtılmıştır: Hermes üzerinden eklediğiniz hesaplar, aynı Telegram kimliği olsa bile Claude.ai veya ChatGPT için görünmezdir. Farklı hesapları farklı MCP istemcilerine bağlamak için her istemciyi ayrı ayrı kaydedin ve kendi oturumu içinde telegram-accounts-add kullanın.