OAuth voor eigen MCP-clients

Als je je eigen MCP-client bouwt (CLI, SDK, IDE-plug-in), beschrijft deze pagina onze OAuth-implementatie: welke standaarden we ondersteunen, endpoints, redirect_uri-regels en hoe je veelvoorkomende fouten oplost. Gebruikers van Claude.ai en ChatGPT hebben deze pagina niet nodig — bekijk in plaats daarvan de Quickstart.

Standaarden die we implementeren

mcp-telegram.com is volledig compatibel met de OAuth-specificaties waarop het MCP-ecosysteem leunt — geen propriëtaire uitbreidingen, geen gedeelde secrets die in clients zijn ingebakken.

RFC 6749 — OAuth 2.0 Authorization Framework — basis authorization code grant met refresh tokens
RFC 7591 — Dynamic Client Registration — elke client kan zichzelf registreren via /oauth/register zonder voorafgaande afstemming
RFC 7636 — PKCE (Proof Key for Code Exchange) — S256-challenge vereist voor publieke clients
RFC 8252 — OAuth 2.0 for Native Apps — loopback IP redirect URI's met flexibiliteit voor ephemerale poorten
RFC 8414 — OAuth 2.0 Authorization Server Metadata — discovery-document op /.well-known/oauth-authorization-server
RFC 9728 — OAuth 2.0 Protected Resource Metadata — discovery van de MCP-resourcegrens

Endpoints

Authorization server metadata (RFC 8414)

Dynamic client registration (RFC 7591)

Authorization-endpoint

Token-endpoint

MCP-resource (Streamable HTTP)

Authorization code flow met PKCE

Standaard RFC 6749 §4.1 + RFC 7636 flow. Geen verrassingen — als je OAuth-bibliotheek "authorization code + PKCE" aankan, werkt het gewoon.

Registreer je client

POST /oauth/register met { redirect_uris: ["http://127.0.0.1:<port>/callback"], client_name: "jouw-client-naam" }. De server retourneert client_id + client_secret (het secret is optioneel voor publieke PKCE-clients, maar onschadelijk om te ontvangen).

Genereer een PKCE-paar

Genereer een willekeurige code_verifier van 43–128 tekens en bereken vervolgens code_challenge = BASE64URL(SHA256(code_verifier)). Sla de verifier lokaal op voor stap 4.

Open /oauth/authorize in een browser

Stuur de gebruiker door naar /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256. De server toont een QR-code; de gebruiker scant die in de Telegram-app om te authenticeren.

Ontvang de authorization code

Na het scannen van de QR redirect de server naar jouw redirect_uri met ?code=...&state=.... Controleer of de state-parameter overeenkomt met wat je hebt verzonden.

Wissel code in voor een token

POST /oauth/token met grant_type=authorization_code, code, redirect_uri, code_verifier, client_id. Je ontvangt een access_token (TTL van 10 jaar — zie Token-levensduur hieronder) en een refresh_token. Gebruik het access_token als Authorization: Bearer ... op /mcp-verzoeken.

Matchingregels voor redirect_uri

We volgen RFC 8252 §7.3 en §8.4 strikt. Het matching-algoritme hangt af van of de geregistreerde URI een loopback IP-literal is.

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

Als je een loopback-URI hebt geregistreerd, moet de redirect_uri op het moment van authorize precies overeenkomen qua scheme, host, path en query — maar de poort mag verschillen. Dit wordt vereist door RFC 8252 §7.3 omdat native clients zich binden aan een door het OS toegewezen ephemerale poort die tussen runs kan veranderen.

Geregistreerd http://127.0.0.1:36201/callback matcht authorize-tijd http://127.0.0.1:50000/callback ✅
Geregistreerd http://127.0.0.1:36201/callback matcht NIET http://127.0.0.1:50000/different-path — het path moet exact zijn
Geregistreerd http://[::1]:36201/cb matcht NIET http://127.0.0.1:36201/cb — IPv4- en IPv6-loopback zijn aparte identifiers

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

Byte-voor-byte exacte match vereist, inclusief path, query en poort (RFC 6749 §3.1.2). Geen flexibiliteit.

localhost (NIET aanbevolen)

We behandelen http://localhost als een gewone hostnaam — exacte match vereist, geen flexibiliteit op de poort. RFC 8252 §8.3 raadt aan om IP-literals (127.0.0.1 / [::1]) te gebruiken in plaats van localhost, omdat DNS-resolutie afhangt van de implementatie.

PKCE is verplicht

code_challenge_method=S256 is vereist bij elk authorize-verzoek. De methode Plain wordt geweigerd. Als je code_challenge volledig overslaat, faalt de /token-uitwisseling bij de validatie van code_verifier.

Token-levensduur

De TTL van access_token is bewust lang (10 jaar) omdat sommige MCP-clients refresh_token niet betrouwbaar persistent opslaan. Er wordt nog steeds een refresh_token uitgegeven dat bij elke refresh rouleert (RFC 6819 §5.2.2.3). De gebruiker kan op elk moment alle tokens intrekken via /my/sessions of door uit te loggen bij Telegram. De gebruiker kan ook expliciet POSTen naar /oauth/revoke (RFC 7009) om een sessie te beëindigen.

Veelvoorkomende fouten

HTTP 400 "Invalid redirect_uri" op /oauth/authorize

De query-parameter redirect_uri komt niet overeen met een URI die voor deze client_id is geregistreerd. Voor loopback-clients: controleer of scheme + host + path + query exact overeenkomen (alleen de poort is flexibel). Voor HTTPS-clients: volledige byte-gelijkheid is vereist — let op trailing slashes en verschillen in URL-encoding.

HTTP 400 "Unknown client"

De client_id bestaat niet in onze database. Ofwel heb je de /oauth/register-stap overgeslagen, ofwel is de registratierespons verloren gegaan voordat je het client_id opsloeg, ofwel is de client door de gebruiker ingetrokken via /my/clients.

Client toont herhaaldelijk "Needs Auth"

Als je client wel access_token persistent opslaat maar geen refresh_token, zie je dit wanneer het access_token verloopt. Onze access tokens hebben juist een TTL van 10 jaar om dit te verzachten, maar als je client tokens aan clientzijde na een kortere periode laat verlopen, moet je ofwel refresh_token persistent opslaan ofwel op aanvraag /oauth/revoke + opnieuw authenticeren aanroepen.

Geteste clients

Bevestigd interoperabel met onze server. Bouw je iets nieuws en werkt het, stuur ons dan een PR om het hier toe te voegen.

Claude.ai web — via ingebouwde MCP connector
ChatGPT Apps — via ingebouwde MCP connector
Hermes Agent — open-source CLI MCP-client (RFC 8252 loopback flow)
Cursor MCP — IDE-plug-in (RFC 8252 loopback flow)
Elke client die voldoet aan RFC 6749 + RFC 7591 + RFC 7636 + RFC 8252 zou aan onze kant zonder codewijzigingen moeten werken.

Meerdere Telegram-accounts op één OAuth-verbinding

Sinds v2.32.0 kan één OAuth-verbinding meerdere Telegram-identiteiten bevatten en met één tool-aanroep tussen accounts wisselen — geen Disconnect/Connect-cyclus, geen nieuwe client-registratie.

Bekijk wat er gekoppeld is

Roep telegram-accounts-list aan. U ziet uw primary (OAuth-gebonden) account gemarkeerd met ⭐ als deze actief is, plus eventuele secundaire accounts die u heeft toegevoegd.

Koppel nog een account

Roep telegram-accounts-add aan met een optionele label (bijv. "testing"). De tool retourneert een eenmalige URL (TTL 10 minutes) — open deze op een willekeurig apparaat en scan de QR met het Telegram-account dat u wilt toevoegen.

Wissel het actieve account

Roep telegram-accounts-switch aan met identifier=label, @username, account_id of 'primary'. De volgende telegram-* aanroep gebruikt dit account direct. Geen reconnect nodig.

Ontkoppel een secundair account

Roep telegram-accounts-remove identifier=… aan voor een secundair account. Het Telegram-account zelf wordt NIET uitgelogd — alleen de koppeling hier wordt verwijderd. De primary kan niet op deze manier worden verwijderd; gebruik de Disconnect-flow van uw client om volledig uit te loggen.

Elke OAuth-verbinding is geïsoleerd: accounts die u via Hermes koppelt zijn onzichtbaar voor Claude.ai of ChatGPT, zelfs als het om dezelfde Telegram-identiteit gaat. Om verschillende accounts aan verschillende MCP-clients te koppelen, registreer elke client afzonderlijk en gebruik telegram-accounts-add binnen zijn eigen sessie.