에이전트 MCP Handoff

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

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

요약: API MCP 서버를 연결하고, 에이전트에 API 키를 제공하며, twexapi_request 전에 explore를 호출하도록 지시하고, 채팅 요약만이 아닌 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를 사용하세요. 문서화된 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 `twexapi_request` with the exact method and a relative path from the returned catalog entry.

Rules:
- Never call absolute URLs through `twexapi_request`.
- 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 any catalog entry with `read_only: false` as a production action.
- Ask for explicit user confirmation before posting, replying, liking, retweeting, following, blocking, bookmarking, deleting, sending DMs, or making any other write call.
- 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.
- 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. 사용자에게 정확한 write body 제시
3. 명시적 확인 대기
4. 반환된 write 엔드포인트에 twexapi_request

Handoff 필드: confirmation text, method, path, request body, tweet_id, write_action_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",
  "error": {
    "code": 401,
    "message": "Missing MCP API token"
  }
}

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

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

유용한 해석:

프로덕션 가이드

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