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

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

요약: API MCP 서버를 연결하고, 에이전트에 API 키를 제공하며, `twexapi_request` 전에 `explore`를 호출하도록 지시하고, 채팅 요약만이 아닌 durable handoff 출력을 요구하세요.

## Handoff 체크리스트

1. **API MCP 서버 연결**

    MCP 클라이언트에 `https://api.twexapi.io/mcp`를 추가하고 `x-api-key` 또는 `Authorization: Bearer <token>` 중 하나를 사용하세요.

2. **Docs MCP 서버 연결**

    에이전트가 API 경로를 선택하기 전에 Twexapi 문서를 검색해야 할 때 `https://docs.twexapi.io/mcp`를 추가하세요.

3. **호출 전 탐색**

    에이전트에게 작업과 일치하는 query 또는 category로 먼저 `explore`를 호출하도록 지시하세요.

4. **상대 경로만 사용**

    에이전트에게 `explore`가 반환한 상대 경로로만 `twexapi_request`를 호출하도록 지시하세요.

5. **Handoff 필드 보존**

    최종 출력에 ID, cursor, task ID, 경로 이름, status, credit 필드를 포함하도록 요구하세요.

6. **쓰기 작업 신중히 처리**

    `read_only`가 `false`인 모든 엔드포인트에서 명시적 사용자 확인을 요구하세요.

## 에이전트 경로 체크리스트

### 먼저 문서 읽기

공개 문서, 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에 다음을 붙여 넣으세요:

```txt
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.
```

## 일반적인 워크플로

### 트렌딩 주제 리서치

```txt
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`.

### 트윗 검색

```txt
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`.

### 팔로워 내보내기

```txt
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`.

### 답글 스크래핑

```txt
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 기사 가져오기

```txt
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.

### 쓰기 작업 실행

```txt
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을 반환하도록 요청하세요:

```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에는 세 가지 중요한 가드레일이 있습니다:

| Guardrail | 동작 |
| --- | --- |
| API key auth | MCP는 REST API와 동일한 API key 검증, credit 확인, 계정 제어를 사용합니다. |
| Allowlisted paths | `twexapi_request`는 MCP 카탈로그 외부 엔드포인트를 거부합니다. |
| Write flags | 부수 효과가 있는 작업은 `read_only: false`로 표시되어 에이전트가 확인을 요청할 수 있습니다. |

## 오류 처리

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

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

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

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

유용한 해석:

| Status | 의미 |
| --- | --- |
| `401` | 도구 실행 전 MCP 인증 실패; `x-api-key` 또는 Bearer auth를 확인하세요. |
| `403` | API 키를 사용할 수 없거나 credits가 소진되었거나 작업이 허용되지 않습니다. |
| `429` | Rate limit 초과. limit window 이후 재시도하세요. |
| `5xx` | 서비스 측 실패 또는 upstream X/Twitter fetch 문제. |

## 프로덕션 가이드

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