---
title: "MCP 도구 참조"
description: "엔드포인트 검색, 인증된 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 엔드포인트 카탈로그를 검색하고 메서드, 경로, 카테고리, 매개변수, 예제 및 안전 플래그를 반환합니다. |
| `twexapi_request` | 허용 목록에 있는 상대 경로에 대해 인증된 Twexapi API 호출을 실행합니다. |

## `explore`

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

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

### 입력

| 이름 | 유형 | 필수의 | 설명 |
| --- | --- | --- | --- |
| `query` | 끈 | No | 엔드포인트 이름, 방법, 경로, 카테고리, 설명 및 예제에 대한 키워드 검색입니다. |
| `category` | 끈 | No | `trending`, `search`, `users`, `articles` 또는 `write`와 같은 정확한 카테고리 필터입니다. |
| `include_writes` | 부울 | No | 부작용이 있는 엔드포인트를 포함합니다. 쓰기 끝점은 `read_only: false`로 표시됩니다. |

### 카탈로그 모양

```ts
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;
  };
}
```

### 예

추세 엔드포인트 찾기:

```json
{
  "category": "trending"
}
```

키워드로 검색:

```json
{
  "query": "advanced search tweets"
}
```

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

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

## `twexapi_request`

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

### 입력

| 이름 | 유형 | 필수의 | 설명 |
| --- | --- | --- | --- |
| `method` | 끈 | Yes | `GET` 또는 `POST`와 같은 `explore`에서 반환된 HTTP 메서드입니다. |
| `path` | 끈 | Yes | 상대 Twexapi API 경로. 절대 URL은 거부됩니다. |
| `query` | 물체 | No | 요청에 대한 쿼리 매개변수입니다. |
| `body` | 객체, 배열 또는 스칼라 | No | GET이 아닌 요청에 대한 JSON 요청 본문입니다. |

:::warning
  먼저 `explore`를 호출하고 카탈로그에서 반환된 정확한 상대 경로를 사용하세요. `twexapi_request`를 통해 `/openapi.json`, 문서 페이지, 대시보드 또는 숨겨진 프레임워크 경로를 호출하지 마세요.
:::

### 대응계약

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

```json
{
  "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`에서 반환된 쿼리 매개변수에 커서를 전달하세요.

## 워크플로우 예시

이 예는 에이전트가 생성해야 하는 모양을 보여줍니다. 에이전트가 현재 스키마를 확인할 수 있도록 실제 사용 시 먼저 '탐색'을 실행하세요.

### 핸드오프 행이 있는 트윗 검색

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

에이전트에게 컴팩트 핸드오프 객체를 반환하도록 요청하세요.

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

### 인기 트윗 가져오기

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

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

### 팔로어를 CRM으로 내보내기

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

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

### Markdown으로 X 기사 읽기

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

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

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

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

:::warning
  `read_only: false`가 있는 엔드포인트를 프로덕션 작업으로 처리합니다. 게시, 답장, 팔로우, 차단, 삭제, 북마크 지정 또는 DM 보내기 전에 명시적인 사용자 확인이 필요합니다.
:::

`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 본문을 유지하세요.

## 엔드포인트 카테고리

| 범주 | 일반적인 용도 |
| --- | --- |
| `trending` | 국가, 주제, 콘텐츠 태그, 인기 트윗. |
| `search` | 고급검색, 해시태그 검색, 캐시태그 검색, 페이지 매김 검색이 가능합니다. |
| `users` | 사용자 조회, 계정 확인, 사용자 검색, 계정 상태. |
| `tweets` | 답글, 스레드, 트윗 조회, 유사한 트윗, 감정, 인용문, 리트윗자 및 즐겨찾기. |
| `followers` | 팔로어, 팔로잉, 최신 팔로어 및 페이지가 매겨진 관계 데이터입니다. |
| `communities` | 커뮤니티 메타데이터, 회원, 트윗, 검색 및 커뮤니티 트윗 검색. |
| `lists` | 리스트 생성, 리스트 트윗, 회원, 구독자, 리스트 검색 등을 할 수 있습니다. |
| `dm` | DM 상태, DM 보내기, DM 내역입니다. |
| `articles` | X 기사 조회, Markdown 가져오기, 초안, 표지, 콘텐츠 업데이트 및 게시. |
| `timeline` | 사용자 타임라인 및 트윗/답글 페이지. |
| `accounts` | 쿠키 유효성 검사, 계정 정보, 계정 확인 및 계정 상태. |
| `write` | 게시, 답글, 좋아요, 리트윗, 팔로우, 차단, 북마크, 삭제, DM 보내기 등의 부작용 행위. |

## 오류 처리

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

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

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

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

| 상태 | 의미 |
| --- | --- |
| `401` | 도구가 실행되기 전에 MCP 인증이 실패했습니다. `x-api-key` 또는 Bearer 인증을 확인하세요. |
| `403` | API 키를 사용할 수 없거나 크레딧이 소진되었거나 작업이 허용되지 않습니다. |
| `429` | 비율 제한을 초과했습니다. 제한 기간이 지난 후 다시 시도하세요. |
| `5xx` | 서비스 측 오류 또는 업스트림 X/Twitter 가져오기 문제. |

REST 및 MCP 복구 패턴은 [오류 처리](/guides/error-handling) 및 [비율 제한](/guides/rate-limits)을 참조하세요.