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 le des acceso MCP de Twexapi a un agente de código, un agente de investigación, un agente de flujos o un asistente interno.

En resumen: conecta el servidor MCP de la API iniciando sesión o con una API key, indícale al agente que llame a explore antes que a cualquier otra herramienta, que use twexapi_request para lecturas y twexapi_write solo para escrituras confirmadas, y exige una salida de handoff duradera en lugar de resúmenes solo en el chat.

Checklist de handoff

Checklist de rutas para el 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ías de SDK y ejemplos.

Descubre la ruta de la API

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

Ejecuta la llamada a la API

Usa twexapi_request del MCP de la API para endpoints de solo lectura y twexapi_write para endpoints de escritura, con el método exacto y la ruta relativa devueltos por explore. Cada resultado de explore indica su herramienta. Pasa solo los campos query y body documentados.

Persiste fuera del chat

Usa REST, SDKs, una cola o una herramienta de flujos cuando un backend deba encargarse de reintentos, almacenamiento de cursores, descargas de archivos, tareas programadas u orquestación por lotes.

Entrega los resultados

Guarda la ruta del endpoint, los parámetros de la solicitud, los IDs devueltos, has_more, next_cursor, los IDs de tareas, los IDs de acciones de escritura, los créditos cobrados y cualquier ruta de exportación o polling antes de terminar la ejecución del agente.

Instrucción para copiar y pegar

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

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 the tool named in the catalog entry's `tool` field (`twexapi_request` for reads, `twexapi_write` for writes) with the exact method and a relative path from that entry.

Rules:
- Never call absolute URLs through `twexapi_request` or `twexapi_write`.
- 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 every `twexapi_write` call as a production action. Ask for explicit user confirmation before posting or replying.
- Never repeat an X cookie or auth_token back in your answer.
- 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.
- If a tool returns "No credits left on this TwexAPI account", stop and tell the user to top up; do not retry.
- For downstream workflows, return compact JSON with route_used, request, rows or ids, has_more, next_cursor, and next_step.

Flujos comunes

Investiga 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 interacción, has_more, next_cursor.

Busca 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 orden, tweet_id, texto, metadatos del autor, fecha de creación, URL directa, has_more, next_cursor.

Exporta 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 de página/tarea devuelto por explore

Campos de handoff: cuenta de origen, user_id, username, nombre, bio, número de seguidores, estado de verificación, ID de tarea, has_more, next_cursor.

Extrae 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: ID del tweet de origen, ID de la respuesta, username del autor, texto, métricas, índice de página, has_more, next_cursor.

Obtén 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 en Markdown, enlaces extraídos, URL de origen, resumen generado.

Ejecuta 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. Muestra al usuario el texto exacto del tweet y el tweet al que se responde
3. Espera la confirmación explícita
4. twexapi_write para POST /twitter/tweets/create, con la cookie de X del usuario en cookie

Publicar es la única escritura disponible por MCP. Las demás acciones de escritura usan la API REST.

Campos de handoff: texto de confirmación, método, ruta, texto del tweet, tweet_id, estado, créditos cobrados, tweet al que se responde, URLs de medios. Nunca incluyas la cookie.

Contrato de salida del handoff

Para flujos 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 deban ir a un CRM, una hoja de cálculo, una base de datos o una cola. Usa ids cuando el siguiente worker solo necesite identificadores duraderos.

Modelo de seguridad

Twexapi MCP tiene tres barreras de protección:

Manejo de errores

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

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": 401,
    "message": "Access token is invalid or expired"
  }
}

Cuando la cuenta se queda sin créditos, la conexión sigue funcionando y explore es gratis, pero las demás llamadas a herramientas devuelven:

{
  "error": "No credits left on this TwexAPI account. Top up at https://twexapi.io/dashboard and try again."
}

Cuando una herramienta se ejecuta y la API de Twexapi devuelve una respuesta que no es 2xx, pide al agente que conserve el resultado de la herramienta:

{
  "status_code": 429,
  "endpoint": "get_global_trending_tweets",
  "method": "GET",
  "path": "/twitter/global-trending/tweets",
  "result": {
    "code": 429,
    "msg": "Rate limit exceeded. QPS limit: 2 requests per second",
    "data": []
  }
}

Interpretaciones útiles:

Consulta la referencia de herramientas MCP para ver todos los mensajes de error.

Guía para producción

• Conéctate en modo de solo lectura (desmarca la casilla de escritura al iniciar sesión) cuando el agente no necesite publicar.
• Prefiere flujos de solo lectura para agentes autónomos.
• Registra prompts, cuerpos de solicitud, nombres de rutas y respuestas MCP en los flujos de escritura.
• Exige aprobación humana antes de cada llamada a twexapi_write.
• Mantén cookies, tokens de autenticación, API keys y textos privados de DMs fuera de los mensajes finales visibles para el usuario.
• Guarda cursores e IDs de tareas fuera del chat cuando otro worker necesite continuar el trabajo.
• Usa REST directo o SDKs generados para tareas de producción programadas que necesiten reintentos, colas y almacenamiento duradero.