Handoff MCP para agentes

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

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:

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

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

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

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

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

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

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:

{
  "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:

Manejo de errores

Cuando falla la autenticación MCP, la herramienta no se ejecuta. Preserva el error JSON-RPC:

{
  "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:

{
  "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:

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.