MCP araç referansı

Uç nokta keşfi, salt okunur X veri çağrıları, paylaşım, iş akışı devri ve güvenli agent yürütmesi için TwexAPI MCP araçları.

https://api.twexapi.io/mcp adresindeki TwexAPI API MCP sunucusu üç araç sunar: explore, twexapi_request ve twexapi_write. Giriş yaparak veya bir API anahtarıyla bağlanın.

Agent’lar önce bir uç nokta bulmak için explore’u, ardından explore’un o uç nokta için belirttiği aracı çağırmalıdır. Okuma ve yazma ayrı araçlar kullanır; böylece Claude gibi istemciler okumaları serbestçe çalıştırabilir ve her yazma için onay isteyebilir.

Araçlar

Kullanıcı salt okunur giriş yaptıysa (mcp:read scope’u) veya sunucuda yazma işlemleri kapalıysa twexapi_write gizlenir.

explore

Uç nokta kataloğunda arama yapar. X/Twitter’ı çağırmaz ve kredi kullanmaz; bu nedenle hesapta kredi kalmasa bile çalışır. Yine de giriş veya bir API anahtarı gerektirir.

Girdi

En fazla 50 sonuç döndürür.

Katalog kaydı

interface EndpointInfo {
  name: string;
  method: string;
  path: string; // may contain {placeholders}; replace them before calling
  category: string;
  description: string;
  read_only: boolean;
  tool: "twexapi_request" | "twexapi_write"; // the tool that calls this endpoint
  cursor_paginated: boolean;
  parameters_schema: Record<string, unknown>; // JSON Schema of method, path, query, body
  example: { method: string; path: string; query?: Record<string, unknown>; body?: unknown };
  mpp_eligible: boolean; // accepts pay-per-call on /mcp/pay
}

Örnekler

{ "category": "trending" }

{ "query": "advanced search" }

{ "query": "create tweet", "include_writes": true }

twexapi_request

Salt okunur bir uç noktayı çağırır. Kimlik doğrulama MCP bağlantısından eklenir; agent yalnızca yöntemi, göreli yolu ve isteğe bağlı query ile body’yi iletir.

Girdi

Yanıt

Araç, REST yanıtıyla birlikte MCP meta verisini döndürür:

{
  "status_code": 200,
  "endpoint": "list_global_trending_countries",
  "method": "GET",
  "path": "/twitter/global-trending/countries",
  "result": {
    "code": 200,
    "msg": "success",
    "data": []
  }
}

2xx olmayan bir status_code, araç sonucunu hata olarak işaretler. result içindeki ID’leri, cursor’ları, görev ID’lerini ve kredi alanlarını koruyun. Bir sayfa has_more ve next_cursor içerdiğinde cursor’ı explore’un döndürdüğü devam uç noktasına iletin.

twexapi_write

Bir yazma uç noktasını çağırır. Girdi ve yanıt biçimi twexapi_request ile aynıdır. Bugün MCP kataloğunda tek bir yazma uç noktası vardır: tweet veya yanıt paylaşan POST /twitter/tweets/create:

{
  "method": "POST",
  "path": "/twitter/tweets/create",
  "body": {
    "tweet_content": "Hello from TwexAPI MCP",
    "cookie": "auth_token=...; ct0=...",
    "reply_tweet_id": null,
    "media_url": null
  }
}

Her twexapi_write çağrısı; yöntem, yol ve gövdeden türetilen bir Idempotency-Key taşır. Bir istemci aynı çağrıyı 10 dakika içinde birebir tekrarlarsa (örneğin zaman aşımından sonra), ikinci bir gönderi yerine ilk sonucu alır. Ayrıntılar için Gönderileri güvenle yeniden deneyin.

Beğeni, retweet, takip, yer işareti, silme, DM ve makale yayınlama gibi diğer yazma işlemleri yalnızca REST API üzerinden kullanılabilir.

Bir yazma uç noktasını twexapi_request ile veya bir okuma uç noktasını twexapi_write ile çağırmak, doğru aracı belirten bir mesajla başarısız olur.

Örnek iş akışları

Bunlar bir agent’ın oluşturması gereken isteklerin örnekleridir. Gerçek kullanımda, güncel şemayı almak için agent’a önce explore çalıştırtın.

Tweet arama

{
  "method": "POST",
  "path": "/twitter/advanced_search/page",
  "body": {
    "searchTerms": ["from:openai AI agents"],
    "maxItems": 20,
    "sortBy": "Latest"
  }
}

Agent’tan kompakt bir devir nesnesi döndürmesini isteyin:

{
  "source": "twexapi_mcp",
  "job": "tweet_search",
  "route_used": "/twitter/advanced_search/page",
  "query": "from:openai AI agents",
  "rows": [
    {
      "tweet_id": "2104354931595423762",
      "text": "...",
      "author_username": "openai",
      "created_at": "..."
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Trend tweet’leri getirme

{
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "query": {
    "country": "united-states",
    "topic": "technology",
    "content": "AI",
    "count": 20
  }
}

Takipçileri dışa aktarma

{
  "method": "GET",
  "path": "/twitter/followers/openai/50"
}

Büyük dışa aktarımlar için cursor’larla POST /twitter/followers/page veya explore’un döndürdüğü görev uç noktalarını (/twitter/followers/task/{task_id}/status ve /next) kullanın.

Bir X makalesini Markdown olarak okuma

{
  "method": "GET",
  "path": "/x/article/2104354931595423762/markdown"
}

Uç nokta kategorileri

Katalogda 54 salt okunur uç nokta ve 1 yazma uç noktası vardır.

Hata yönetimi

Bağlantı yetkili değilse hiçbir araç çalışmaz ve istemci HTTP 401 veya 403 ile bir JSON-RPC hatası alır:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Sign in through your MCP client, or send your TwexAPI API key in the Authorization header. For pay-per-call without an API key, use /mcp/pay."
  }
}

Hesabın kredisi bittiğinde bağlantı açık kalır. explore sonuç döndürür; diğer araç çağrıları API’yi çağırmadan bir hata sonucu döndürür:

{
  "error": "No credits left on this TwexAPI account. Top up at https://twexapi.io/dashboard and try again."
}

Bir araç çalıştığında ve REST API 2xx olmayan bir yanıt döndürdüğünde MCP meta verisini ve API hatasını koruyun:

{
  "status_code": 429,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "code": 429,
    "msg": "Rate limit exceeded. QPS limit: 2 requests per second",
    "data": []
  }
}

Kurtarma için Hata yönetimi ve Hız sınırları sayfalarına bakın.