Mastra - Xquik

Build a Mastra agent in TypeScript that can search tweets, hand off IDs and cursors, post tweets, replay stored monitor events, and run extraction jobs - connected to Xquik’s MCP server.

Prerequisites

Node.js 18+
Xquik API key (xq_...)
An LLM API key (OpenAI, Anthropic, or any Vercel AI SDK-supported provider)

Install

npm install @mastra/mcp @mastra/core

Full Example

import { writeFile } from "node:fs/promises";
import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";

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

const agent = new Agent({
  id: "xquik-agent",
  name: "Xquik Agent",
  instructions:
    "You help users interact with X (Twitter) via the Xquik API.",
  model: "anthropic/claude-sonnet-4-20250514",
  tools: await mcp.listTools(),
});

const handoffPrompt = (
  "Search for the latest tweets about AI agents. Return compact JSON " +
  "with query, route_used, tweets[{tweet_id,text,author_username,created_at}], " +
  "has_more, next_cursor, and key influencers."
);
const result = await agent.generate(handoffPrompt);

await writeFile("xquik-mastra-handoff.json", result.text, "utf8");

await mcp.disconnect();

The agent auto-discovers all Xquik tools and can call any of the 120 API endpoints. Mastra’s MCPClient loads tools with listTools() for agent setup and listToolsets() for per-call tools. For HTTP MCP servers, it uses requestInit for headers, tries Streamable HTTP from the URL, and falls back to SSE when needed. The MCP runtime returns normalized snake_case fields through xquik.request(), so keep prompts aligned with tweet_id, has_more, next_cursor, and returned job IDs.

Handoff Checklist

Tweet search rows

Store tweet_id, text, author_username, created_at, has_more, next_cursor, and the original q.

User profile rows

Store source id as user_id, plus username, name, followers, verified, profile_picture, has_more, next_cursor, and the source lookup or search query.

Trend rows

Store each trend name, rank, query, and description. Keep response count, woeid, and the requested region with the run checkpoint.

Monitor and webhook setup

Store the returned monitor id as monitor_id, event_types, next_billing_at, the returned webhook id as webhook_id, url, and the one-time secret in a secret manager. On production deliveries, store delivery_id for receiver retry de-dupe and stream_event_id when one monitor event should process once across endpoint changes.

Stored event replay

Store event_id, type, monitor_id, monitor_type, occurred_at, has_more, next_cursor, and the after query for the next page.

Extraction jobs

Store extraction_id, status, poll, and export_after_complete; poll before loading CSV, JSON, or XLSX rows.

Writes

Store tweet_id or write_action_id, reply_to_tweet_id, status, charged_credits, and poll; do not resend pending writes.

Media attachments

For tweets or replies, pass public URLs in media and store tweet_id or write_action_id. For DMs, upload first, pass one media_id in media_ids, store message_id, and leave reply_to_message_id unset.

Streaming Responses

import { writeFile } from "node:fs/promises";

const stream = await agent.stream(
  "What are the trending topics right now?"
);

let handoff = "";
for await (const chunk of stream.textStream) {
  handoff += chunk;
}

await writeFile("xquik-mastra-stream-handoff.json", handoff, "utf8");

Dynamic Toolsets (Per-User API Keys)

For multi-tenant apps, create an MCPClient per request with the user’s API key:

import { writeFile } from "node:fs/promises";
import { MCPClient } from "@mastra/mcp";
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "xquik-agent",
  name: "Xquik Agent",
  instructions: "You help users with X automation.",
  model: "openai/gpt-4o",
});

async function handleRequest(prompt: string, userApiKey: string) {
  const mcp = new MCPClient({
    servers: {
      xquik: {
        url: new URL("https://xquik.com/mcp"),
        requestInit: {
          headers: { "x-api-key": userApiKey },
        },
      },
    },
  });

  try {
    const response = await agent.generate(prompt, {
      toolsets: await mcp.listToolsets(),
    });

    await writeFile("xquik-mastra-user-handoff.json", response.text, "utf8");
    return response.text;
  } finally {
    await mcp.disconnect();
  }
}

Dynamic Headers with Custom Fetch

For request-context-aware headers (e.g., forwarding cookies):

const mcp = new MCPClient({
  servers: {
    xquik: {
      url: new URL("https://xquik.com/mcp"),
      fetch: async (url, init, requestContext) => {
        const headers = new Headers(init?.headers);
        headers.set("x-api-key", process.env.XQUIK_API_KEY!);
        return fetch(url, { ...init, headers });
      },
    },
  },
});

Environment Variables

.env

XQUIK_API_KEY=xq_YOUR_KEY_HERE
ANTHROPIC_API_KEY=sk-ant-...

Package Versions

Package	Version
`@mastra/mcp`	1.4.2+
`@mastra/core`	1.24.1+
`@modelcontextprotocol/sdk`	1.27.1+

Documentation Index

​Prerequisites

​Install

​Full Example

​Handoff Checklist