---
title: "Referencia de herramientas MCP"
description: "Herramientas MCP de Twexapi para descubrimiento de endpoints, llamadas autenticadas a la API, handoff de flujos y ejecución segura de agentes."
---

El servidor MCP de la API de Twexapi expone 2 herramientas: `explore` y `twexapi_request`. Conéctate a `https://api.twexapi.io/mcp` con `x-api-key` o auth Bearer OAuth 2.1.

Los agentes deben usar `explore` para inspeccionar el catálogo de la API antes de llamar a `twexapi_request`. Esto mantiene la selección de endpoints explícita, ayuda al agente a preservar los esquemas de solicitud y evita llamadas accidentales a rutas no disponibles mediante MCP.

## Herramientas

| Herramienta | Propósito |
| --- | --- |
| `explore` | Busca en el catálogo de endpoints de la API y devuelve métodos, rutas, categorías, parámetros, ejemplos y flags de seguridad. |
| `twexapi_request` | Ejecuta llamadas autenticadas a la API de Twexapi contra rutas relativas en la allowlist. |

## `explore`

Busca en el catálogo de endpoints de la API. Solo lectura, sin llamadas de red a X/Twitter y sin consumo de créditos de endpoints. La llamada aún requiere autenticación MCP mediante API key o token Bearer OAuth.

Usa `explore` para descubrir endpoints disponibles, verificar parámetros, comparar categorías y encontrar la ruta de API correcta antes de ejecutar llamadas.

### Entrada

| Nombre | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `query` | string | No | Búsqueda por palabra clave en nombre del endpoint, método, ruta, categoría, descripción y ejemplos. |
| `category` | string | No | Filtro exacto por categoría, como `trending`, `search`, `users`, `articles` o `write`. |
| `include_writes` | boolean | No | Incluye endpoints con efectos secundarios. Los endpoints de escritura están marcados como `read_only: false`. |

### Forma del catálogo

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

### Ejemplos

Encuentra endpoints de tendencias:

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

Busca por palabra clave:

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

Incluye endpoints con capacidad de escritura:

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

## `twexapi_request`

Ejecuta llamadas a la API contra tu cuenta de Twexapi. La autenticación se inyecta automáticamente desde la solicitud MCP, así que los agentes solo pasan el método del endpoint, la ruta relativa y datos opcionales de query/body.

### Entrada

| Nombre | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `method` | string | Sí | Método HTTP devuelto por `explore`, como `GET` o `POST`. |
| `path` | string | Sí | Ruta relativa de la API de Twexapi. Las URLs absolutas se rechazan. |
| `query` | object | No | Parámetros de query para la solicitud. |
| `body` | object, array o escalar | No | Body JSON de la solicitud para solicitudes que no sean GET. |

:::warning
  Llama a `explore` primero y usa la ruta relativa exacta devuelta por el catálogo. No llames a `/openapi.json`, páginas de docs, dashboards ni rutas ocultas de framework mediante `twexapi_request`.
:::

### Contrato de respuesta

`twexapi_request` devuelve metadatos de ejecución MCP más la respuesta REST subyacente:

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

Preserva campos duraderos de `result`, incluyendo IDs, cursors, task IDs, campos de créditos e IDs de acciones de escritura. Cuando una página incluye `has_more` y `next_cursor`, pasa el cursor al endpoint de seguimiento o parámetro de query documentado devuelto por `explore`.

## Ejemplos de flujos de trabajo

Estos ejemplos muestran la forma que un agente debe producir. Ejecuta `explore` primero en uso real para que el agente pueda confirmar el esquema actual.

### Buscar tweets con filas de handoff

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

Pide al agente que devuelva un objeto compacto de handoff:

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

### Obtener tweets en tendencia

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

Almacena `country`, `topic`, `content`, tweet IDs, usernames de autores, campos de engagement, `has_more` y `next_cursor` cuando estén presentes.

### Exportar seguidores a un CRM

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

Almacena `user_id`, `username`, `name`, `description`, `followers_count`, la cuenta fuente y campos de paginación/tarea. Si el endpoint devuelve un task ID, almacénalo y consulta el endpoint de status/next documentado.

### Leer un artículo de X como Markdown

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

Almacena el ID del artículo, título, autor, cuerpo Markdown, enlaces extraídos y URL fuente.

### Publicar un tweet o respuesta

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

:::warning
  Trata cualquier endpoint con `read_only: false` como una acción de producción. Requiere confirmación explícita del usuario antes de publicar, responder, seguir, bloquear, eliminar, marcar favoritos o enviar DMs.
:::

Almacena `tweet_id`, `write_action_id`, `status`, `charged_credits`, el objetivo de la respuesta, URLs de medios y el registro de confirmación del usuario.

## Patrones de handoff de agentes

MCP devuelve JSON. Para colas de agentes, CRMs, hojas de cálculo, data warehouses y flujos no-code, devuelve un objeto duradero pequeño con el job original, la ruta usada, filas o IDs normalizados para almacenar y el siguiente cursor o tarea a consultar.

### Buscar tweets a JSON

Llama a `POST /twitter/advanced_search/page`. Almacena tweet IDs, texto, metadatos del autor, hora de creación, enlaces, `has_more`, `next_cursor` y la query original.

### Extraer respuestas

Llama a `GET /twitter/tweets/{tweet_id}/replies/{count}` para una página acotada o `GET /twitter/tweets/{tweet_id}/replies/page` para paginación por cursor. Almacena reply IDs, usernames de autores, texto, métricas, `has_more` y `next_cursor`.

### Exportar seguidores

Llama a `GET /twitter/followers/{screen_name}/{count}` o los endpoints page/task devueltos por `explore`. Almacena user IDs, usernames, nombres, bios, cantidades de seguidores, cuenta fuente, task ID y siguiente cursor.

### Rastrear acciones de escritura

Para endpoints de escritura, almacena la ruta del endpoint, hash del body o texto de confirmación, tweet ID o write action ID devuelto, status, créditos cobrados y referencias de medios.

### Enviar DMs

Llama al endpoint de DM solo después de la confirmación del usuario. Almacena message ID, user ID del destinatario, cuenta, referencias de medios y status de entrega. Mantén los cuerpos completos de DM fuera de las salidas MCP compartidas.

## Categorías de endpoints

| Categoría | Usos comunes |
| --- | --- |
| `trending` | Países, temas, etiquetas de contenido y tweets en tendencia. |
| `search` | Búsqueda avanzada, búsqueda por hashtag, búsqueda por cashtag y búsqueda paginada. |
| `users` | Consulta de usuarios, verificación de cuentas, búsqueda de usuarios y status de cuenta. |
| `tweets` | Respuestas, hilos, consulta de tweets, tweets similares, sentimiento, quotes, retweeters y favoriters. |
| `followers` | Seguidores, following, seguidores recientes y datos de relaciones paginados. |
| `communities` | Metadatos de comunidad, miembros, tweets, búsqueda y búsqueda de tweets en comunidades. |
| `lists` | Creación de listas, tweets de listas, miembros, suscriptores y búsqueda de listas. |
| `dm` | Status de DM, envío de DM e historial de DMs. |
| `articles` | Consulta de artículos de X, obtención en Markdown, borradores, portadas, actualizaciones de contenido y publicación. |
| `timeline` | Timelines de usuario y páginas de tweets/respuestas. |
| `accounts` | Validación de cookies, info de cuenta, verificación de cuenta y status de cuenta. |
| `write` | Acciones con efectos secundarios como publicar, responder, dar like, retweetear, seguir, bloquear, marcar favoritos, eliminar y enviar DMs. |

## Manejo de errores

Cuando falla la autenticación MCP, la herramienta no se ejecuta. El cliente recibe un error JSON-RPC:

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

Cuando `twexapi_request` se ejecuta y la API subyacente de Twexapi devuelve una respuesta no 2xx, preserva los metadatos MCP y el error de 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."
  }
}
```

| Status | Significado |
| --- | --- |
| `401` | Falló la autenticación MCP antes de ejecutar la herramienta; verifica `x-api-key` o auth Bearer. |
| `403` | La API key no está disponible, los créditos se agotaron o la acción no está permitida. |
| `429` | Se excedió el límite de tasa. Reintenta después de la ventana del límite. |
| `5xx` | Fallo del servicio o problema al obtener datos de X/Twitter upstream. |

Consulta [Error Handling](/guides/error-handling) y [Rate Limits](/guides/rate-limits) para patrones de recuperación REST y MCP.