← กลับไปที่ Quickstart

OAuth สำหรับ MCP client ของคุณเอง

หากคุณกำลังสร้าง MCP client ของตัวเอง (CLI, SDK, ปลั๊กอิน IDE) หน้านี้จะอธิบายการ implement OAuth ของเรา: มาตรฐานที่เรารองรับ, endpoint, กฎของ redirect_uri และวิธี debug ข้อผิดพลาดที่พบบ่อย ผู้ใช้ Claude.ai และ ChatGPT ไม่จำเป็นต้องอ่านหน้านี้ — ใช้ Quickstart แทน

มาตรฐานที่เรา implement

mcp-telegram.com ปฏิบัติตามข้อกำหนด OAuth ที่ระบบนิเวศ MCP พึ่งพาอย่างครบถ้วน — ไม่มีส่วนขยายแบบ proprietary และไม่มี shared secret ที่ฝังอยู่ใน client

RFC 6749 — OAuth 2.0 Authorization Framework — authorization code grant พื้นฐานพร้อม refresh token
RFC 7591 — Dynamic Client Registration — client ใดก็ตามสามารถลงทะเบียนตัวเองที่ /oauth/register ได้โดยไม่ต้องประสานล่วงหน้า
RFC 7636 — PKCE (Proof Key for Code Exchange) — challenge แบบ S256 จำเป็นสำหรับ public client
RFC 8252 — OAuth 2.0 for Native Apps — redirect URI แบบ loopback IP พร้อมความยืดหยุ่นของ ephemeral port
RFC 8414 — OAuth 2.0 Authorization Server Metadata — เอกสาร discovery ที่ /.well-known/oauth-authorization-server
RFC 9728 — OAuth 2.0 Protected Resource Metadata — discovery ขอบเขตของ MCP resource

Endpoint

Metadata ของ authorization server (RFC 8414)
Dynamic client registration (RFC 7591)
Authorization endpoint
Token endpoint
MCP resource (Streamable HTTP)

Authorization code flow ด้วย PKCE

Flow มาตรฐาน RFC 6749 §4.1 + RFC 7636 ไม่มีอะไรซับซ้อน — หากไลบรารี OAuth ของคุณรองรับ "authorization code + PKCE" ก็จะใช้งานได้ทันที

1

ลงทะเบียน client ของคุณ

POST /oauth/register ด้วย { redirect_uris: ["http://127.0.0.1:«port»/callback"], client_name: "ชื่อ-client-ของคุณ" } เซิร์ฟเวอร์จะคืน client_id + client_secret (secret เป็นทางเลือกสำหรับ public PKCE client แต่การได้รับมาก็ไม่เสียหาย)

2

สร้างคู่ PKCE

สร้าง code_verifier แบบสุ่มขนาด 43–128 ตัวอักษร จากนั้นคำนวณ code_challenge = BASE64URL(SHA256(code_verifier)) เก็บ verifier ไว้ใน local เพื่อใช้ในขั้นตอนที่ 4

3

เปิด /oauth/authorize ในเบราว์เซอร์

Redirect ผู้ใช้ไปที่ /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256 เซิร์ฟเวอร์จะแสดง QR code; ผู้ใช้สแกนใน Telegram เพื่อยืนยันตัวตน

4

รับ authorization code

หลังจากสแกน QR แล้ว เซิร์ฟเวอร์จะ redirect ไปยัง redirect_uri ของคุณพร้อม ?code=...&state=.... ตรวจสอบว่าพารามิเตอร์ state ตรงกับที่คุณส่งไป

5

แลก code เป็น token

POST /oauth/token ด้วย grant_type=authorization_code, code, redirect_uri, code_verifier, client_id คุณจะได้รับ access_token (TTL 10 ปี — ดู Token Lifetime ด้านล่าง) และ refresh_token ใช้ access_token เป็น Authorization: Bearer ... ในการเรียกใช้ /mcp

กฎการ matching ของ redirect_uri

เราปฏิบัติตาม RFC 8252 §7.3 และ §8.4 อย่างเคร่งครัด อัลกอริทึม matching ขึ้นอยู่กับว่า URI ที่ลงทะเบียนเป็น literal IP แบบ loopback หรือไม่

Loopback (http://127.0.0.1 หรือ http://[::1])

หากคุณลงทะเบียน URI แบบ loopback ไว้ redirect_uri ขณะ authorize ต้องตรงกันทุกประการในส่วนของ scheme, host, path และ query — แต่ port สามารถต่างกันได้ RFC 8252 §7.3 กำหนดเช่นนี้เพราะ native client จะ bind กับ ephemeral port ที่ OS กำหนดให้ ซึ่งอาจเปลี่ยนแปลงไปในแต่ละครั้งที่รัน

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

ต้องตรงกันทุก byte รวมถึง path, query และ port (RFC 6749 §3.1.2) ไม่มีความยืดหยุ่น

localhost (ไม่แนะนำ)

เราถือว่า http://localhost เป็น hostname ปกติ — ต้องตรงกันทุกประการ ไม่มีความยืดหยุ่นของ port RFC 8252 §8.3 แนะนำให้ใช้ literal IP (127.0.0.1 / [::1]) แทน localhost เพราะการ resolve DNS ขึ้นอยู่กับการ implement

PKCE เป็นข้อบังคับcode_challenge_method=S256 ต้องระบุในทุก authorize request หากใช้ method แบบ plain จะถูกปฏิเสธ หากคุณไม่ใส่ code_challenge เลย การแลกเปลี่ยน /token จะล้มเหลวที่ขั้นตอนการตรวจสอบ code_verifier
อายุของ tokenTTL ของ access_token ถูกตั้งให้ยาวโดยตั้งใจ (10 ปี) เพราะ MCP client บางตัวไม่สามารถเก็บ refresh_token ได้อย่างน่าเชื่อถือ แต่ refresh_token ก็ยังถูกออกให้และหมุนใหม่ทุกครั้งที่ refresh (RFC 6819 §5.2.2.3) ผู้ใช้สามารถเพิกถอน token ทั้งหมดได้ตลอดเวลาที่ /my/sessions หรือโดยการ logout ออกจาก Telegram และผู้ใช้ยังสามารถ POST ไปที่ /oauth/revoke (RFC 7009) อย่างชัดเจนเพื่อสิ้นสุด session ได้

ข้อผิดพลาดที่พบบ่อย

Client ที่ได้รับการทดสอบแล้ว

ยืนยันว่าใช้งานร่วมกับเซิร์ฟเวอร์ของเราได้ หากคุณสร้างอะไรใหม่ขึ้นมาแล้วใช้งานได้ ส่ง PR มาเพื่อเพิ่มในรายการนี้ได้เลย

Claude.ai web — ผ่าน MCP connector ในตัว
ChatGPT Apps — ผ่าน MCP connector ในตัว
Hermes Agent — CLI MCP client แบบโอเพนซอร์ส (RFC 8252 loopback flow)
Cursor MCP — ปลั๊กอิน IDE (RFC 8252 loopback flow)
Client ใดก็ตามที่ปฏิบัติตาม RFC 6749 + RFC 7591 + RFC 7636 + RFC 8252 จะทำงานได้โดยไม่ต้องเปลี่ยนแปลงโค้ดในฝั่งของเรา

หลายบัญชี Telegram บนการเชื่อมต่อ OAuth เดียว

ตั้งแต่ v2.32.0 เป็นต้นมา การเชื่อมต่อ OAuth เดียวสามารถเก็บหลายตัวตน Telegram และสลับระหว่างกันได้ด้วยการเรียก tool เพียงครั้งเดียว — ไม่ต้องวนรอบ Disconnect/Connect ไม่ต้องลงทะเบียน client ใหม่

1

ดูบัญชีที่ผูกอยู่

เรียก telegram-accounts-list คุณจะเห็นบัญชี primary (ที่ผูกกับ OAuth) ของคุณถูกทำเครื่องหมายด้วย ⭐ หากกำลังใช้งานอยู่ พร้อมด้วยบัญชีรองทุกบัญชีที่คุณเพิ่มเข้ามา

2

ผูกบัญชีอื่นเพิ่ม

เรียก telegram-accounts-add พร้อม label ที่เลือกได้ (เช่น "testing") Tool จะคืน URL แบบใช้ครั้งเดียว (TTL 10 นาที) — เปิด URL นั้นบนอุปกรณ์ใดก็ได้และสแกน QR ด้วยบัญชี Telegram ที่คุณต้องการเพิ่ม

3

สลับบัญชีที่กำลังใช้งาน

เรียก telegram-accounts-switch ด้วย identifier=label, @username, account_id, หรือ 'primary' การเรียก tool telegram-* ครั้งถัดไปจะใช้บัญชีนั้นทันที ไม่ต้อง reconnect

4

ถอดบัญชีรองออก

เรียก telegram-accounts-remove identifier=… บนบัญชีรอง ตัวบัญชี Telegram เองจะ ไม่ ถูก log out — มีเพียงการผูกที่นี่เท่านั้นที่ถูกลบ ไม่สามารถลบบัญชี primary ด้วยวิธีนี้ได้ ให้ใช้ขั้นตอน Disconnect ของ client เพื่อออกจากระบบโดยสมบูรณ์

การเชื่อมต่อ OAuth แต่ละครั้งถูกแยกออกจากกัน: บัญชีที่คุณผูกผ่าน Hermes จะมองไม่เห็นจาก Claude.ai หรือ ChatGPT แม้ว่าจะเป็นตัวตน Telegram เดียวกันก็ตาม หากต้องการเชื่อมต่อบัญชีที่ต่างกันกับ MCP client ที่ต่างกัน ให้ลงทะเบียน client แต่ละตัวแยกกัน และใช้ telegram-accounts-add ภายใน session ของตัวเอง