MCP 도구 레퍼런스

TwexAPI MCP 도구: 엔드포인트 탐색, 읽기 전용 X 데이터 호출, 게시, 워크플로 인계, 안전한 에이전트 실행.

https://api.twexapi.io/mcp의 TwexAPI API MCP 서버는 explore, twexapi_request, twexapi_write 세 가지 도구를 제공합니다. 로그인 또는 API 키로 연결하세요.

에이전트는 먼저 explore로 엔드포인트를 찾은 다음, explore가 해당 엔드포인트에 지정한 도구를 호출해야 합니다. 읽기와 쓰기가 별도의 도구로 나뉘어 있어 Claude 같은 클라이언트는 읽기는 자유롭게 실행하고 쓰기마다 확인을 요청할 수 있습니다.

도구

사용자가 읽기 전용(스코프 mcp:read)으로 로그인했거나 서버에서 쓰기 작업이 꺼져 있으면 twexapi_write는 표시되지 않습니다.

explore

엔드포인트 카탈로그를 검색합니다. X/Twitter를 호출하지 않고 크레딧도 사용하지 않으므로, 계정에 크레딧이 남아 있지 않아도 동작합니다. 다만 로그인 또는 API 키는 필요합니다.

입력

결과는 최대 50개입니다.

카탈로그 항목

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
}

예시

{ "category": "trending" }

{ "query": "advanced search" }

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

twexapi_request

읽기 전용 엔드포인트를 호출합니다. 인증은 MCP 연결에서 자동으로 주입되므로 에이전트는 메서드, 상대 경로, 선택적인 query와 body만 전달합니다.

입력

응답

도구는 MCP 메타데이터와 REST 응답을 함께 반환합니다.

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

status_code가 2xx가 아니면 도구 결과가 오류로 표시됩니다. result의 ID, 커서, 작업 ID, 크레딧 필드를 보존하세요. 페이지에 has_more와 next_cursor가 있으면 explore가 반환한 후속 엔드포인트에 커서를 전달합니다.

twexapi_write

쓰기 엔드포인트를 호출합니다. 입력과 응답 형식은 twexapi_request와 같습니다. 현재 MCP 카탈로그의 쓰기 엔드포인트는 트윗이나 답글을 게시하는 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
  }
}

모든 twexapi_write 호출에는 메서드, 경로, 본문으로 만든 Idempotency-Key가 붙습니다. 클라이언트가 타임아웃 후 재시도처럼 10분 안에 완전히 같은 호출을 반복하면, 두 번째 게시 대신 첫 번째 결과를 받습니다. 자세한 내용은 게시를 안전하게 재시도하기를 참고하세요.

좋아요, 리트윗, 팔로우, 북마크, 삭제, DM, 아티클 게시 등 다른 쓰기 작업은 REST API에서만 사용할 수 있습니다.

쓰기 엔드포인트를 twexapi_request로, 읽기 엔드포인트를 twexapi_write로 호출하면 실패하며, 올바른 도구를 알려 주는 메시지가 반환됩니다.

워크플로 예시

다음은 에이전트가 만들어야 할 요청의 예시입니다. 실제로 사용할 때는 먼저 explore를 실행해 최신 스키마를 확인하게 하세요.

트윗 검색

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

에이전트에게 간결한 인계 객체를 반환하도록 요청합니다.

{
  "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
}

트렌드 트윗 가져오기

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

팔로워 내보내기

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

대량으로 내보낼 때는 커서를 사용하는 POST /twitter/followers/page나 explore가 반환하는 작업 엔드포인트(/twitter/followers/task/{task_id}/status와 /next)를 사용하세요.

X 아티클을 Markdown으로 읽기

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

엔드포인트 카테고리

카탈로그에는 읽기 전용 엔드포인트 54개와 쓰기 엔드포인트 1개가 있습니다.

오류 처리

연결이 인가되지 않으면 어떤 도구도 실행되지 않고, 클라이언트는 HTTP 401 또는 403의 JSON-RPC 오류를 받습니다.

{
  "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."
  }
}

계정의 크레딧이 소진되어도 연결은 유지됩니다. explore는 결과를 반환하고, 다른 도구 호출은 API를 호출하지 않고 오류 결과를 반환합니다.

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

도구가 실행되었는데 REST API가 2xx가 아닌 응답을 반환하면 MCP 메타데이터와 API 오류를 보존하세요.

{
  "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": []
  }
}

복구 방법은 오류 처리와 요청 한도를 참고하세요.