---
title: "Handoff MCP para agentes"
description: "Instrucciones para entregar acceso MCP de Twexapi de forma segura a agentes de IA y flujos downstream."
---

Usa esta página cuando estés dando acceso MCP de Twexapi a un agente de código con IA, agente de investigación, agente de flujo de trabajo o asistente interno.

En resumen: conecta el servidor MCP de la API, dale al agente una API key, indícale que llame a `explore` antes de `twexapi_request` y exige una salida de handoff duradera en lugar de resúmenes solo en el chat.

## Checklist de handoff

1. **Conecta el servidor MCP de la API**

    Agrega `https://api.twexapi.io/mcp` a tu cliente MCP con `x-api-key` o `Authorization: Bearer <token>`.

2. **Conecta el servidor Docs MCP**

    Agrega `https://docs.twexapi.io/mcp` cuando el agente deba buscar documentación de Twexapi antes de elegir rutas de la API.

3. **Descubre antes de llamar**

    Indica al agente que llame a `explore` primero, usando una query o categoría que coincida con la tarea.

4. **Exige rutas relativas**

    Indica al agente que llame a `twexapi_request` solo con rutas relativas devueltas por `explore`.

5. **Preserva campos de handoff**

    Exige IDs, cursors, task IDs, nombres de ruta, status y campos de créditos en la salida final.

6. **Maneja las escrituras con cuidado**

    Exige confirmación explícita del usuario antes de cualquier endpoint donde `read_only` sea `false`.

## Checklist de rutas del agente

### Lee la documentación primero

Usa Docs MCP en `https://docs.twexapi.io/mcp` para documentación pública, parámetros de la API, instrucciones de configuración, códigos de error, guía de SDKs y ejemplos.

### Descubre la ruta de la API

Usa `explore` del MCP de la API para encontrar el endpoint exacto, método, esquema de solicitud, categoría y flag de seguridad.

### Ejecuta la llamada a la API

Usa `twexapi_request` del MCP de la API con el método y la ruta relativa exactos devueltos por `explore`. Pasa solo los campos `query` y `body` documentados.

### Persiste fuera del chat

Usa REST, SDKs, una cola o una herramienta de flujo de trabajo cuando un backend deba manejar reintentos, almacenamiento de cursors, descargas de archivos, jobs programados u orquestación por lotes.

### Entrega los resultados

Almacena la ruta del endpoint, parámetros de solicitud, IDs devueltos, `has_more`, `next_cursor`, task IDs, write action IDs, créditos cobrados y cualquier ruta de exportación o consulta antes de terminar la ejecución del agente.

## Instrucción de agente para copiar y pegar

Pega esto en las instrucciones del sistema de tu agente, instrucciones del proyecto o prompt de tarea:

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

## Flujos de trabajo comunes

### Investigar temas en tendencia

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

Ruta recomendada:

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

Campos de handoff: `country`, `topic`, `content`, `tweet_id`, `author_username`, `created_at`, métricas de engagement, `has_more`, `next_cursor`.

### Buscar tweets

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

Ruta recomendada:

1. `explore(query="advanced search tweets")`
2. `twexapi_request` para `/twitter/advanced_search/page`
3. Usa `/twitter/advanced_search/page` si el catálogo devuelve un flujo de paginación

Campos de handoff: query original, modo de ordenamiento, `tweet_id`, texto, metadatos del autor, hora de creación, URL directa, `has_more`, `next_cursor`.

### Exportar seguidores

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

Ruta recomendada:

1. `explore(category="followers")`
2. `twexapi_request` para `/twitter/followers/{screen_name}/{count}` o un endpoint page/task devuelto por `explore`

Campos de handoff: cuenta fuente, `user_id`, `username`, nombre, bio, cantidad de seguidores, status de verificación, task ID, `has_more`, `next_cursor`.

### Extraer respuestas

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

Ruta recomendada:

1. `explore(query="tweet replies")`
2. `twexapi_request` para `/twitter/tweets/{tweet_id}/replies/{count}` o `/twitter/tweets/{tweet_id}/replies/page`

Campos de handoff: tweet ID fuente, reply ID, username del autor, texto, métricas, índice de página, `has_more`, `next_cursor`.

### Obtener artículos de X

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

Ruta recomendada:

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

Campos de handoff: ID del artículo, título, autor, cuerpo Markdown, enlaces extraídos, URL fuente, resumen generado.

### Ejecutar una acción de escritura

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

Ruta recomendada:

1. `explore(query="create tweet", include_writes=true)`
2. Presenta el body exacto de escritura al usuario
3. Espera confirmación explícita
4. `twexapi_request` para el endpoint de escritura devuelto

Campos de handoff: texto de confirmación, método, ruta, body de solicitud, `tweet_id`, `write_action_id`, status, créditos cobrados, objetivo de la respuesta, URLs de medios.

## Contrato de salida de handoff

Para flujos de trabajo duraderos, pide al agente que devuelva JSON compacto:

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

Usa `rows` para registros que deben ir a un CRM, hoja de cálculo, base de datos o cola. Usa `ids` cuando el siguiente worker solo necesite identificadores duraderos.

## Modelo de seguridad

Twexapi MCP tiene tres guardrails importantes:

| Guardrail | Comportamiento |
| --- | --- |
| Auth por API key | MCP usa la misma validación de API key, verificación de créditos y controles de cuenta que la API REST. |
| Rutas en allowlist | `twexapi_request` rechaza endpoints fuera del catálogo MCP. |
| Flags de escritura | Las acciones con efectos secundarios están marcadas como `read_only: false` para que los agentes puedan solicitar confirmación. |

## Manejo de errores

Cuando falla la autenticación MCP, la herramienta no se ejecuta. Preserva el 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, pide al agente que preserve el resultado de la herramienta:

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

Interpretaciones útiles:

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

## Guía para producción

- Usa una API key con alcance limitado cuando el agente solo necesite un flujo de trabajo específico.
- Prefiere flujos de solo lectura para agentes autónomos.
- Registra prompts, bodies de solicitud, nombres de ruta y respuestas MCP para flujos de escritura.
- Exige aprobación humana antes de llamadas con `read_only: false`.
- Mantén cookies, tokens de auth, API keys y texto de DMs privados fuera de los mensajes finales visibles para el usuario.
- Almacena cursors y task IDs fuera del chat cuando otro worker deba continuar el job.
- Usa REST directo o SDKs generados para jobs de producción programados que necesiten reintentos, colas y almacenamiento duradero.