Ö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

Authorization server metadata (RFC 8414)

Dynamic client registration (RFC 7591)

Authorization uç noktası

Token uç noktası

MCP kaynağı (Streamable HTTP)

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 zorunludurcode_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

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.