MCP istemcileri için OAuth

Kullanıcıları TwexAPI'ye giriş yaptıran bir MCP istemcisi geliştirmek için referans: keşif, dinamik istemci kaydı, PKCE, scope'lar, token'lar, yenileme ve iptal.

TwexAPI, MCP sunucusu için bir OAuth 2.1 yetkilendirme sunucusu çalıştırır. Claude, ChatGPT ve Cursor gibi MCP istemcileri bunu otomatik olarak kullanır. Kendi istemcinizi geliştirirken veya bir istemcide hata ayıklarken bu sayfayı kullanın.

• PKCE ile yetkilendirme kodu akışı (yalnızca S256).
• Yalnızca public istemciler, client secret yok. Dinamik istemci kaydıyla (RFC 7591) kaydolun.
• Kullanıcılar TwexAPI hesaplarıyla giriş yapar ve erişimi https://twexapi.io/oauth/consent adresinde onaylar.
• Token’lar yalnızca https://api.twexapi.io/mcp üzerinde çalışan opak dizelerdir. TwexAPI API anahtarı değildirler ve REST API’yi çağıramazlar.
• Çağrılar kullanıcının API anahtarı üzerinden kullanıcının kredilerinden düşülür; bu nedenle onay için kredisi olan etkin bir anahtar gerekir.

TwexAPI’yi yalnızca bir script’ten veya backend’den çağırmak istiyorsanız bir API anahtarı kullanın.

Keşif

https://api.twexapi.io/mcp adresine kimlik bilgisi olmadan yapılan istek, şu header ile 401 döndürür:

WWW-Authenticate: Bearer realm="twexapi", resource_metadata="https://api.twexapi.io/.well-known/oauth-protected-resource/mcp", scope="mcp:read mcp:write"

Korunan kaynak meta verisi

GET https://api.twexapi.io/.well-known/oauth-protected-resource/mcp (/.well-known/oauth-protected-resource adresinde de aynısı):

{
  "resource": "https://api.twexapi.io/mcp",
  "authorization_servers": ["https://api.twexapi.io"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp:read", "mcp:write"],
  "resource_name": "TwexAPI"
}

Yetkilendirme sunucusu meta verisi

GET https://api.twexapi.io/.well-known/oauth-authorization-server:

{
  "issuer": "https://api.twexapi.io",
  "authorization_endpoint": "https://api.twexapi.io/oauth/authorize",
  "token_endpoint": "https://api.twexapi.io/oauth/token",
  "registration_endpoint": "https://api.twexapi.io/oauth/register",
  "revocation_endpoint": "https://api.twexapi.io/oauth/revoke",
  "response_types_supported": ["code"],
  "response_modes_supported": ["query"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "revocation_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp:read", "mcp:write"],
  "authorization_response_iss_parameter_supported": true
}

Scope’lar

İkisini birden istemek için mcp:read mcp:write isteyin. Bilinmeyen scope’lar yok sayılır; tanınan hiçbir scope yoksa istek ikisini birden istiyormuş gibi değerlendirilir. Token yanıtındaki scope alanı, kullanıcının gerçekte neye izin verdiğini gösterir.

1. İstemci kaydedin

POST https://api.twexapi.io/oauth/register
Content-Type: application/json

{
  "client_name": "My Agent",
  "redirect_uris": ["http://127.0.0.1:53682/callback"]
}

{
  "client_id": "twx_client_...",
  "client_id_issued_at": 1792600000,
  "client_name": "My Agent",
  "redirect_uris": ["http://127.0.0.1:53682/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Kayıt, IP adresi başına saatte 30 istemciyle sınırlıdır. Bir istemci kaydı 180 gün geçerlidir ve bir kullanıcı onunla her yetkilendirme başlattığında uzatılır. Bir kez kaydolun ve client_id değerini yeniden kullanın.

2. PKCE çifti oluşturun

Node.js:

import crypto from "node:crypto";

const verifier = crypto.randomBytes(32).toString("base64url");
const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");

Python:

import base64, hashlib, secrets

verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()

Verifier, A-Z a-z 0-9 - . _ ~ karakterlerinden oluşan 43 ila 128 karakter olmalıdır.

3. Kullanıcıyı yetkilendirmeye gönderin

Bu URL’yi kullanıcının tarayıcısında açın:

https://api.twexapi.io/oauth/authorize
  ?response_type=code
  &client_id=twx_client_...
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcallback
  &code_challenge=CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM_STATE
  &scope=mcp%3Aread%20mcp%3Awrite
  &resource=https%3A%2F%2Fapi.twexapi.io%2Fmcp

TwexAPI kullanıcıyı twexapi.io üzerindeki onay sayfasına gönderir. Kullanıcı giriş yapar, uygulama adını ve geri döneceği host’u görür, yazma erişimi verip vermeyeceğini seçer ve onaylar ya da reddeder. İsteğin süresi 10 dakika sonra dolar.

4. Kodu alın

Onaydan sonra tarayıcı yönlendirme URI’nize geri döner:

http://127.0.0.1:53682/callback?code=CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fapi.twexapi.io

state değerinin eşleştiğini ve iss değerinin https://api.twexapi.io olduğunu kontrol edin. Kullanıcı reddederse code yerine error=access_denied alırsınız. Kod tek kullanımlıktır ve 2 dakika sonra süresi dolar.

client_id bilinmiyorsa veya redirect_uri kayıtlı değilse TwexAPI yönlendirme yapmak yerine bir 400 hatası gösterir; böylece yanlış yapılandırılmış bir istemci kullanıcıyı asla doğrulanmamış bir adrese göndermez.

5. Kodu token’larla değiştirin

POST https://api.twexapi.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=CODE
&redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcallback
&client_id=twx_client_...
&code_verifier=VERIFIER

{
  "access_token": "twx_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "twx_rt_...",
  "scope": "mcp:read mcp:write"
}

redirect_uri ve client_id, yetkilendirme isteğiyle eşleşmelidir. resource=https://api.twexapi.io/mcp da gönderebilirsiniz. JSON gövdeleri kabul edilir.

6. MCP sunucusunu çağırın

POST https://api.twexapi.io/mcp
Authorization: Bearer twx_at_...
Content-Type: application/json
Accept: application/json, text/event-stream

Erişim token’ları yalnızca /mcp üzerinde çalışır. Süresi dolmuş, iptal edilmiş veya bilinmeyen bir token, WWW-Authenticate header’ında error="invalid_token" ile 401 alır. Token’ı yenileyin veya kullanıcıdan yeniden giriş yapmasını isteyin.

Token’ları yenileme

POST https://api.twexapi.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=twx_rt_...
&client_id=twx_client_...

Her yenileme yeni bir erişim token’ı ve yeni bir refresh token döndürür; eski refresh token artık çalışmaz. Her seferinde yeni çifti saklayın. Eski bir refresh token yeniden kullanılırsa TwexAPI bunu sızdırılmış kabul eder ve yetkilendirmenin tamamını iptal eder: tüm token’ları çalışmayı bırakır ve kullanıcının yeniden giriş yapması gerekir.

İptal

POST https://api.twexapi.io/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=twx_rt_...

Bir refresh token’ı iptal etmek tüm yetkilendirmeyi sonlandırır. Bir erişim token’ını iptal etmek yalnızca o token’ı geçersiz kılar. Uç nokta, bilinmeyen token’lar için bile her zaman 200 döndürür. Kullanıcılar bir uygulamayı paneldeki Authorized apps (yetkili uygulamalar) altından da iptal edebilir; bu hemen geçerli olur.

Token süreleri

Hatalar

Hatalar standart OAuth biçimini kullanır:

{
  "error": "invalid_grant",
  "error_description": "The authorization code is invalid, expired or already used"
}

Kullanıcının hesabında etkin bir API anahtarı veya kredi yoksa onay sayfası onaydan önce bunu engeller; böylece istemciniz çağrı yapamayan bir token asla almaz.