에이전트 MCP Handoff

AI 에이전트 및 하위 워크플로에 Twexapi MCP 접근을 안전하게 넘기는 방법.

AI 코딩 에이전트, 리서치 에이전트, 워크플로 에이전트 또는 내부 어시스턴트에 Twexapi MCP 접근을 부여할 때 이 페이지를 사용하세요.

요약: 로그인 또는 API 키로 API MCP 서버를 연결하고, 다른 도구보다 먼저 explore를 호출하도록 에이전트에 지시하며, 읽기에는 twexapi_request를, 확인된 쓰기에만 twexapi_write를 사용하게 하고, 채팅 요약만이 아닌 durable handoff 출력을 요구하세요.

Handoff 체크리스트

에이전트 경로 체크리스트

먼저 문서 읽기

공개 문서, API 매개변수, 설정 지침, 오류 코드, SDK 가이드, 예제는 Docs MCP https://docs.twexapi.io/mcp를 사용하세요.

API 경로 탐색

정확한 엔드포인트, method, request schema, category, safety flag를 찾으려면 API MCP explore를 사용하세요.

API 호출 실행

explore가 반환한 정확한 method와 상대 경로로, 읽기 전용 엔드포인트에는 API MCP twexapi_request를, 쓰기 엔드포인트에는 twexapi_write를 사용하세요. 각 explore 결과에는 사용할 도구가 표시됩니다. 문서화된 query 및 body 필드만 전달하세요.

채팅 외부에 영속화

백엔드가 재시도, cursor 저장, 파일 다운로드, 예약 작업 또는 배치 오케스트레이션을 소유해야 할 때 REST, SDK, 큐 또는 워크플로 도구를 사용하세요.

결과 Handoff

에이전트 실행을 종료하기 전에 엔드포인트 경로, 요청 매개변수, 반환된 ID, has_more, next_cursor, task ID, write action ID, 차감 credits, export 또는 poll 경로를 저장하세요.

복사-붙여넣기 에이전트 지침

에이전트의 system instructions, project instructions 또는 task prompt에 다음을 붙여 넣으세요:

You have access to Twexapi MCP servers.

Use Twexapi Docs MCP first when you need product documentation, setup instructions, endpoint docs, authentication details, examples, or error-code explanations.

Use the API MCP tool `explore` before making API calls. Search by query or category to find the correct Twexapi endpoint. Then call the tool named in the catalog entry's `tool` field (`twexapi_request` for reads, `twexapi_write` for writes) with the exact method and a relative path from that entry.

Rules:
- Never call absolute URLs through `twexapi_request` or `twexapi_write`.
- Never call paths that were not returned by `explore`.
- Do not call `/openapi.json`, docs pages, dashboards, or hidden framework routes through API MCP.
- Treat every `twexapi_write` call as a production action. Ask for explicit user confirmation before posting or replying.
- Never repeat an X cookie or auth_token back in your answer.
- Preserve tweet IDs, user IDs, task IDs, cursors, write action IDs, status, credit fields, and response metadata in your final answer when they are useful for auditability.
- If a request fails, report the HTTP status, endpoint name, method, path, and Twexapi error message.
- If a tool returns "No credits left on this TwexAPI account", stop and tell the user to top up; do not retry.
- For downstream workflows, return compact JSON with route_used, request, rows or ids, has_more, next_cursor, and next_step.

일반적인 워크플로

트렌딩 주제 리서치

Use Twexapi MCP to find trending countries, choose the United States, fetch AI-related trending tweets, and summarize the top themes with tweet IDs.

권장 경로:

1. explore(category="trending")
2. twexapi_request for /twitter/global-trending/countries
3. twexapi_request for /twitter/global-trending/topics
4. twexapi_request for /twitter/global-trending/tweets

Handoff 필드: country, topic, content, tweet_id, author_username, created_at, engagement metrics, has_more, next_cursor.

트윗 검색

Search recent posts from @openai that mention AI agents and return the most relevant tweets with IDs, author metadata, and a short summary.

권장 경로:

1. explore(query="advanced search tweets")
2. twexapi_request for /twitter/advanced_search/page
3. 카탈로그가 pagination flow를 반환하면 /twitter/advanced_search/page 사용

Handoff 필드: original query, sort mode, tweet_id, text, author metadata, created time, direct URL, has_more, next_cursor.

팔로워 내보내기

Export a page of followers for @openai in CRM-ready JSON.

권장 경로:

1. explore(category="followers")
2. twexapi_request for /twitter/followers/{screen_name}/{count} 또는 explore가 반환한 page/task 엔드포인트

Handoff 필드: source account, user_id, username, name, bio, follower count, verified status, task ID, has_more, next_cursor.

답글 스크래핑

Fetch replies for a tweet and return reply IDs, author usernames, text, and engagement fields.

권장 경로:

1. explore(query="tweet replies")
2. twexapi_request for /twitter/tweets/{tweet_id}/replies/{count} 또는 /twitter/tweets/{tweet_id}/replies/page

Handoff 필드: source tweet ID, reply ID, author username, text, metrics, page index, has_more, next_cursor.

X 기사 가져오기

Fetch this X article as Markdown and turn it into a concise brief.

권장 경로:

1. explore(category="articles")
2. twexapi_request for /x/article/{tweet_id}/markdown

Handoff 필드: article ID, title, author, Markdown body, extracted links, source URL, generated summary.

쓰기 작업 실행

Draft a reply to this tweet, ask me for confirmation, then post only after I approve.

권장 경로:

1. explore(query="create tweet", include_writes=true)
2. 사용자에게 정확한 트윗 본문과 답글 대상 제시
3. 명시적 확인 대기
4. POST /twitter/tweets/create에 twexapi_write 호출, cookie에 사용자의 X 쿠키 전달

MCP로 사용할 수 있는 쓰기 작업은 게시뿐입니다. 다른 쓰기 작업은 REST API를 사용하세요.

Handoff 필드: confirmation text, method, path, tweet text, tweet_id, status, charged credits, reply target, media URLs. 쿠키는 절대 포함하지 마세요.

Handoff 출력 계약

durable 워크플로의 경우 에이전트에게 compact JSON을 반환하도록 요청하세요:

{
  "source": "twexapi_mcp",
  "job": "tweet_search",
  "route_used": "/twitter/advanced_search/page",
  "request": {
    "method": "POST",
    "path": "/twitter/advanced_search/page",
    "query": null,
    "body": {
      "searchTerms": ["from:openai AI agents"],
      "maxItems": 20,
      "sortBy": "Latest"
    }
  },
  "rows": [],
  "ids": [],
  "has_more": false,
  "next_cursor": null,
  "next_step": null
}

CRM, 스프레드시트, 데이터베이스 또는 큐로 보낼 레코드에는 rows를 사용하세요. 다음 worker가 durable identifier만 필요할 때는 ids를 사용하세요.

안전 모델

Twexapi MCP에는 세 가지 가드레일이 있습니다:

오류 처리

MCP 인증이 실패하면 도구가 실행되지 않습니다. JSON-RPC 오류를 보존하세요:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Access token is invalid or expired"
  }
}

계정의 크레딧이 소진되어도 연결은 유지되고 explore는 무료이지만, 다른 도구 호출은 다음을 반환합니다:

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

도구가 실행되고 기본 Twexapi API가 non-2xx 응답을 반환하면 에이전트에게 도구 결과를 보존하도록 요청하세요:

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

유용한 해석:

모든 오류 메시지는 MCP 도구 레퍼런스를 참고하세요.

프로덕션 가이드

• 에이전트가 게시할 필요가 없다면 읽기 전용으로 연결하세요(로그인할 때 쓰기 체크 해제).
• 자율 에이전트에는 읽기 전용 워크플로를 선호하세요.
• 쓰기 워크플로에는 prompt, request body, 경로 이름, MCP 응답을 로깅하세요.
• 모든 twexapi_write 호출 전에 사람 승인을 요구하세요.
• cookie, auth token, API key, 비공개 DM 텍스트를 최종 사용자에게 보이는 메시지에서 제외하세요.
• 다른 worker가 작업을 이어야 할 때 cursor와 task ID를 채팅 외부에 저장하세요.
• 재시도, 큐잉, durable storage가 필요한 예약 프로덕션 작업에는 직접 REST 또는 생성된 SDK를 사용하세요.