MCP 도구 참조

엔드포인트 검색, 인증된 API 호출, 워크플로 전달 및 안전한 에이전트 실행을 위한 Twexapi MCP 도구입니다.

Twexapi API MCP 서버는 explore와 twexapi_request라는 두 가지 도구를 노출합니다. x-api-key 또는 OAuth 2.1 Bearer 인증을 사용하여 https://api.twexapi.io/mcp에 연결합니다.

에이전트는 twexapi_request를 호출하기 전에 explore를 사용하여 API 카탈로그를 검사해야 합니다. 이렇게 하면 엔드포인트 선택이 명시적으로 유지되고, 에이전트가 요청 스키마를 보존하는 데 도움이 되며, MCP를 통해 사용할 수 없는 경로에 대한 우발적인 호출을 방지할 수 있습니다.

도구

explore

API 엔드포인트 카탈로그를 검색하세요. 읽기 전용, X/Twitter 네트워크 호출 없음, 엔드포인트 크레딧 소비 없음. 호출에는 여전히 API 키 또는 OAuth Bearer 토큰을 통한 MCP 인증이 필요합니다.

호출을 실행하기 전에 탐색을 사용하여 사용 가능한 엔드포인트를 찾고, 매개변수를 확인하고, 카테고리를 비교하고, 올바른 API 경로를 찾으세요.

입력

카탈로그 모양

interface EndpointInfo {
  name: string;
  method: string;
  path: string;
  category: string;
  description: string;
  read_only: boolean;
  parameters_schema?: Record<string, unknown>;
  example?: {
    method: string;
    path: string;
    query?: Record<string, unknown>;
    body?: unknown;
  };
}

예

추세 엔드포인트 찾기:

{
  "category": "trending"
}

키워드로 검색:

{
  "query": "advanced search tweets"
}

쓰기 가능 엔드포인트를 포함합니다.

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

twexapi_request

Twexapi 계정에 대해 API 호출을 실행합니다. 인증은 MCP 요청에서 자동으로 주입되므로 에이전트는 엔드포인트 메서드, 상대 경로 및 선택적 쿼리/본문 데이터만 전달합니다.

입력

대응계약

twexapi_request는 MCP 실행 메타데이터와 기본 REST 응답을 반환합니다.

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

ID, 커서, 작업 ID, 크레딧 필드, 쓰기 작업 ID를 포함하여 ’결과’의 지속성 필드를 유지합니다. 페이지에 has_more 및 next_cursor가 포함된 경우 문서화된 후속 엔드포인트 또는 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": "1803006263529541838",
      "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
  }
}

‘국가’, ‘주제’, ‘콘텐츠’, 트윗 ID, 작성자 사용자 이름, 참여 필드, ‘has_more’ 및 ’next_cursor’가 있는 경우 이를 저장합니다.

팔로어를 CRM으로 내보내기

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

user_id, username, name, description, followers_count, 소스 계정 및 페이지 매김/작업 필드를 저장합니다. 엔드포인트가 작업 ID를 반환하는 경우 이를 저장하고 문서화된 상태/다음 엔드포인트를 폴링합니다.

Markdown으로 X 기사 읽기

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

기사 ID, 제목, 작성자, Markdown 본문, 추출된 링크 및 소스 URL을 저장합니다.

트윗을 게시하거나 답장을 보내세요.

{
  "method": "POST",
  "path": "/twitter/tweets/create",
  "body": {
    "tweet_content": "Hello from Twexapi MCP",
    "reply_tweet_id": null,
    "media_url": null
  }
}

tweet_id, write_action_id, status, charged_credits, 응답 대상, 미디어 URL 및 사용자 확인 기록을 저장합니다.

상담원 핸드오프 패턴

MCP는 JSON을 반환합니다. 에이전트 대기열, CRM, 스프레드시트, 웨어하우스 및 코드 없는 워크플로의 경우 원래 작업, 사용된 경로, 저장할 정규화된 행 또는 ID, 폴링할 다음 커서 또는 작업이 포함된 작은 내구성 개체를 반환합니다.

JSON으로 트윗 검색

POST /twitter/advanced_search/page를 호출하세요. 트윗 ID, 텍스트, 작성자 메타데이터, 생성 시간, 링크, has_more, next_cursor 및 원래 쿼리를 저장합니다.

스크랩 답글

제한된 페이지의 경우 GET /twitter/tweets/{tweet_id}/replies/{count}를 호출하고 커서 스타일 페이지 매김의 경우 GET /twitter/tweets/{tweet_id}/replies/page를 호출하세요. 응답 ID, 작성자 사용자 이름, 텍스트, 측정항목, ‘has_more’ 및 ’next_cursor’를 저장합니다.

팔로어 내보내기

GET /twitter/followers/{screen_name}/{count} 또는 explore에서 반환된 페이지/작업 엔드포인트를 호출하세요. 사용자 ID, 사용자 이름, 이름, 약력, 팔로워 수, 소스 계정, 작업 ID 및 다음 커서를 저장합니다.

쓰기 작업 추적

쓰기 엔드포인트의 경우 엔드포인트 경로, 본문 해시 또는 확인 텍스트, 반환된 트윗 ID 또는 쓰기 작업 ID, 상태, 청구된 크레딧 및 미디어 참조를 저장합니다.

DM 보내기

사용자 확인 후에만 DM 엔드포인트를 호출하세요. 메시지 ID, 수신자 사용자 ID, 계정, 미디어 참조 및 배달 상태를 저장합니다. 공유 MCP 출력에서 ​​전체 DM 본문을 유지하세요.

엔드포인트 카테고리

오류 처리

MCP 인증이 실패하면 도구가 실행되지 않습니다. 클라이언트가 JSON-RPC 오류를 수신합니다.

{
  "jsonrpc": "2.0",
  "error": {
    "code": 401,
    "message": "Missing MCP API token"
  }
}

twexapi_request가 실행되고 기본 Twexapi API가 2xx가 아닌 응답을 반환하는 경우 MCP 메타데이터 및 Twexapi 오류를 유지하세요.

{
  "status_code": 403,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "detail": "Credits exhausted or action not allowed."
  }
}

REST 및 MCP 복구 패턴은 오류 처리 및 비율 제한을 참조하세요.