---
title: "Mastra"
description: "Crea agentes Mastra en TypeScript para búsqueda de tweets, perfiles, tendencias y escrituras en X revisadas a través de TwexAPI MCP."
---

Crea un agente de Twitter API con Mastra a través del servidor MCP de TwexAPI. Busca tweets, inspecciona perfiles, lee tendencias y revisa acciones de escritura. Conserva IDs de tweet, cursores y nombres de ruta como JSON tipado en lugar de resúmenes solo de chat.

## ¿Por qué usar Mastra con TwexAPI?

Mastra es un framework de agentes en TypeScript. TwexAPI proporciona descubrimiento de endpoints y llamadas autenticadas a través de `explore` y `twexapi_request`.

| Tarea del agente | Ruta de TwexAPI | Conservar para el siguiente paso |
| --- | --- | --- |
| Buscar tweets | `POST /twitter/advanced_search/page` | Consulta, IDs de tweet, autores, `created_at`, cursor |
| Inspeccionar un perfil | `GET /twitter/{screen_name}/about` | ID de usuario, nombre de usuario, biografía, cantidad de seguidores |
| Leer tendencias | `GET /twitter/global-trending/tweets` | País, tema, filas de tweets |
| Publicar o responder | `POST /twitter/tweets/create` | ID de tweet, ruta, aprobación humana, confirmación de cookie |

Usa Mastra para apps TypeScript que ya usan modelos de Vercel AI SDK. Usa el [TypeScript SDK](/sdks/typescript) o el [CLI](/sdks/cli) para trabajos programados que no requieren modelo.

## Requisitos previos

- Node.js 20 o posterior
- Una [API key de TwexAPI](https://twexapi.io/dashboard)
- Una API key de proveedor de modelo compatible con Mastra
- Una cookie de Twitter o `auth_token` para acciones de escritura — consulta

Las lecturas públicas de X no requieren credenciales de X Developer. Autentícate con TwexAPI.

## Instalación

```bash
npm install @mastra/core @mastra/mcp @ai-sdk/openai dotenv
```

```txt .env
TWEXAPI_API_KEY=YOUR_API_KEY
OPENAI_API_KEY=sk-...
```

## Conectar TwexAPI MCP

```ts
import "dotenv/config";
import { MCPClient } from "@mastra/mcp";

export const twexapiMcp = new MCPClient({
  servers: {
    twexapi: {
      url: new URL("https://api.twexapi.io/mcp"),
      requestInit: {
        headers: {
          "x-api-key": process.env.TWEXAPI_API_KEY!,
        },
      },
    },
  },
});
```

El servidor expone `explore` para descubrimiento y `twexapi_request` para llamadas autenticadas. Las solicitudes MCP no autenticadas devuelven `401`.

## Ejemplo completo

```ts
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { writeFile } from "node:fs/promises";
import { twexapiMcp } from "./mcp";

type TweetRow = {
  tweet_id: string;
  text: string;
  author_username?: string;
  created_at?: string;
};

type TweetSearchHandoff = {
  query: string;
  route_used: string;
  tweets: TweetRow[];
  has_more: boolean;
  next_cursor: string | null;
  stop_reason: "complete" | "requested_limit" | "cursor_stalled" | "page_cap";
};

const tools = await twexapiMcp.listTools();

export const twexapiAgent = new Agent({
  name: "twexapi-agent",
  instructions: `
    Use TwexAPI MCP for Twitter API requests.
    Call explore before twexapi_request.
    Preserve exact IDs and cursors. Never invent missing tweet fields.
    Ask for confirmation before read_only: false actions.
    Return only valid JSON matching the handoff contract.
  `,
  model: openai("gpt-4o-mini"),
  tools,
});

const result = await twexapiAgent.generate(
  `Search 25 recent tweets about Mastra MCP.
Return JSON with query, route_used, tweets[{tweet_id,text,author_username,created_at}],
has_more, next_cursor, and stop_reason.`
);

const handoff = JSON.parse(result.text) as TweetSearchHandoff;
await writeFile(
  "twexapi-mastra-handoff.json",
  JSON.stringify(handoff, null, 2),
  "utf8"
);
```

Valida el JSON antes de que otro flujo de trabajo lo consuma. El historial de conversación no es una base de datos de trabajos.

## Conservar el contrato de respuesta MCP

Pasa solo los campos documentados de `query` y `body` de `explore` a `twexapi_request`.

Detén la paginación cuando se cumpla una de estas condiciones:

- El agente recopila el total solicitado.
- `has_more` o `has_next_page` pasa a ser false.
- `next_cursor` falta o se repite.
- Se alcanza el límite de páginas configurado.

Elimina duplicados de tweets y usuarios por `tweet_id` o `user_id`.

## Mantener una entrega de agente reanudable

<CardGroup cols={2}>
  <Card title="Páginas de tweets" icon="message-square">
    Almacena `tweet_id`, `text`, `author_username`, `created_at`, `has_more`, `next_cursor` y la consulta original.
  </Card>
  <Card title="Filas de perfil" icon="user-round">
    Almacena `user_id`, `username`, `name`, `description`, cantidades de seguidores y la entrada de búsqueda.
  </Card>
  <Card title="Filas de tendencias" icon="radio">
    Almacena país, tema, IDs de tweet y métricas de engagement.
  </Card>
  <Card title="Acciones de escritura" icon="send">
    Almacena ruta, texto de vista previa y aprobación humana. Mantén las cookies fuera del archivo de entrega. Consulta.
  </Card>
</CardGroup>

Consulta [Agent MCP Handoff](/mcp/agent-handoff) para la lista de verificación completa.

## Construir manejo de errores

| Estado | Significado | Decisión del agente |
| --- | --- | --- |
| `400` | Ruta o parámetros inválidos | Corrige la solicitud antes de reintentar |
| `401` | API key faltante o inválida | Detente y reemplaza la credencial |
| `403` | Acceso denegado o créditos | Pausa escrituras; verifica [Get Balance](/api-reference/balance-endpoints/get-balance-api-balance-get) |
| `429` | Límite de tasa alcanzado | Espera y luego reanuda el mismo cursor |
| `5xx` | Fallo temporal del servidor | Aplica backoff acotado a lecturas seguras |

Nunca reintentes una escritura después de un timeout sin una verificación de lectura. Consulta [Error Handling](/guides/error-handling) y [Rate Limits](/guides/rate-limits).

## Requerir aprobación antes de acciones en X

```txt
Call explore with include_writes true only when the user asked to post, like, follow, or DM.
Stop before any read_only: false call.
Show method, path, tweet text or target username, and media URLs.
Do not send cookie values in the model output.
```

Previsualiza con el [CLI](/sdks/cli) `--dry-run`, luego ejecuta a través de REST o el TypeScript SDK después de la aprobación.

## Conectar múltiples servidores MCP

```ts
export const mcp = new MCPClient({
  servers: {
    twexapi: {
      url: new URL("https://api.twexapi.io/mcp"),
      requestInit: {
        headers: { "x-api-key": process.env.TWEXAPI_API_KEY! },
      },
    },
    twexapiDocs: {
      url: new URL("https://docs.twexapi.io/mcp"),
    },
  },
});
```

Mantén estable el nombre del servidor TwexAPI. Dale al agente solo las herramientas necesarias para el trabajo actual.

## Versiones de paquetes

| Paquete | Rango compatible |
| --- | --- |
| Node.js | `>=20` |
| `@mastra/core` | `>=0.10` |
| `@mastra/mcp` | `>=0.10` |

## Próximos pasos

- [MCP Tools](/mcp/tools)
- [Agent MCP Handoff](/mcp/agent-handoff)
-
- [TypeScript SDK](/sdks/typescript)
- [Advanced Twitter Search](/api-reference/search-endpoints/get-data-page-twitter-advanced-search-page-post)