Mastra AI Twitter MCP agent guide for TypeScript

npm install "@mastra/core@^1.55" "@mastra/mcp@^1.15" zod

import { writeFile } from "node:fs/promises";
import { Agent } from "@mastra/core/agent";
import { createStep, createWorkflow } from "@mastra/core/workflows";
import { MCPClient } from "@mastra/mcp";
import { z } from "zod";

const tweetRowSchema = z.object({
  tweet_id: z.string(),
  text: z.string(),
  author_username: z.string().nullable(),
  created: z.number().int().nullable(),
  url: z.string().url().nullable(),
});

const handoffSchema = z.object({
  query: z.string(),
  route_used: z.literal("GET /api/v1/x/tweets/search"),
  tweets: z.array(tweetRowSchema),
  has_more: z.boolean(),
  next_cursor: z.string().nullable(),
  pages_fetched: z.number().int().positive(),
  stop_reason: z.enum([
    "complete",
    "requested_limit",
    "cursor_stalled",
  ]),
});

const mcp = new MCPClient({
  servers: {
    xquik: {
      url: new URL("https://xquik.com/mcp"),
      requestInit: {
        headers: {
          "x-api-key": process.env.XQUIK_API_KEY!,
        },
      },
      onToolError: "throw",
    },
  },
  timeout: 60_000,
});

try {
  const agent = new Agent({
    id: "xquik-tweet-search-agent",
    name: "Xquik Tweet Search Agent",
    instructions: [
      "Use Xquik for Twitter API requests.",
      "Use GET /api/v1/x/tweets/search.",
      "Preserve exact tweet IDs, created timestamps, and cursors.",
      "Never invent missing tweet fields.",
      "Stop when the requested limit is reached.",
      "Stop if the server repeats a cursor.",
    ].join(" "),
    model: "openai/gpt-5",
    tools: await mcp.listTools(),
  });

  const searchStep = createStep({
    id: "search-twitter",
    inputSchema: z.object({ query: z.string().min(1) }),
    outputSchema: handoffSchema,
    execute: async ({ inputData }) => {
      const result = await agent.generate(
        `Search 50 latest tweets for: ${inputData.query}`,
        { structuredOutput: { schema: handoffSchema } },
      );

      return handoffSchema.parse(result.object);
    },
  });

  const tweetResearchWorkflow = createWorkflow({
    id: "xquik-tweet-research",
    inputSchema: z.object({ query: z.string().min(1) }),
    outputSchema: handoffSchema,
  })
    .then(searchStep)
    .commit();

  const run = await tweetResearchWorkflow.createRun();
  const workflowResult = await run.start({
    inputData: { query: "Mastra AI MCP" },
  });

  if (workflowResult.status !== "success") {
    throw new Error(`Tweet workflow ended with ${workflowResult.status}.`);
  }

  await writeFile(
    "xquik-mastra-handoff.json",
    JSON.stringify(workflowResult.result, null, 2),
    "utf8",
  );
} finally {
  await mcp.disconnect();
}

const approvedMcp = new MCPClient({
  servers: {
    xquik: {
      url: new URL("https://xquik.com/mcp"),
      requestInit: {
        headers: { "x-api-key": process.env.XQUIK_API_KEY! },
      },
      requireToolApproval: ({ toolName }) => toolName === "xquik",
      onToolError: "throw",
    },
  },
});

const tools = await mcp.listTools();
const discoveryTools = Object.fromEntries(
  Object.entries(tools).filter(([name]) => name.endsWith("_explore")),
);

const discoveryAgent = new Agent({
  id: "xquik-route-discovery-agent",
  name: "Xquik Route Discovery Agent",
  instructions: "Inspect Twitter API routes. Never execute an operation.",
  model: "openai/gpt-5",
  tools: discoveryTools,
});

import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";

async function runTenantRequest(prompt: string, userApiKey: string) {
  const tenantMcp = new MCPClient({
    id: crypto.randomUUID(),
    servers: {
      xquik: {
        url: new URL("https://xquik.com/mcp"),
        requestInit: {
          headers: { "x-api-key": userApiKey },
        },
        requireToolApproval: true,
        onToolError: "throw",
      },
    },
  });

  const agent = new Agent({
    id: "tenant-twitter-agent",
    name: "Tenant Twitter Agent",
    instructions: "Preserve tweet IDs, profile IDs, cursors, and job IDs.",
    model: "openai/gpt-5",
  });

  try {
    return await agent.generate(prompt, {
      toolsets: await tenantMcp.listToolsets(),
    });
  } finally {
    await tenantMcp.disconnect();
  }
}

const mcp = new MCPClient({
  servers: {
    xquik: {
      url: new URL("https://xquik.com/mcp"),
      fetch: async (url, init) => {
        const headers = new Headers(init?.headers);
        headers.set("x-api-key", await secretStore.getXquikKey());
        return fetch(url, { ...init, headers });
      },
      onToolError: "throw",
    },
  },
});