X Live Search

Overview

Use the X Live Search MCP server from your ATXP-powered agent to search X (formerly Twitter) for posts and conversations using xAI’s Grok models. Powered by xAI’s Agentic Search Tools API, the server uses AI agents that autonomously explore and make follow-up queries to provide comprehensive search results with citations.

Example prompts

“What are the latest updates from Stripe?”
“Find popular tweets about AI from the last week with at least 100 likes”
“Search for posts from @elonmusk about SpaceX”

Tools

x_live_search

Searches X (formerly Twitter) for posts matching the query and optional filters using xAI’s Agentic Search Tools API. The AI agent autonomously explores and makes follow-up queries to provide comprehensive results with citations to source posts.

Arguments

Accepts a JSON object with the following properties:

query

string

required

The search query to execute on X (formerly Twitter). Natural language queries work best with the agentic search API.

allowed_x_handles

string[]

List of X handles to include in search (up to 10). Format without @ symbol, e.g., [“elonmusk”, “OpenAI”].

excluded_x_handles

string[]

List of X handles to exclude from search (up to 10). Format without @ symbol.

from_date

string

Start date for posts in ISO8601 format (YYYY-MM-DD).

to_date

string

End date for posts in ISO8601 format (YYYY-MM-DD).

enable_image_understanding

boolean

Enable AI analysis of images in posts. Increases token usage.

enable_video_understanding

boolean

Enable AI analysis of videos in X posts. Increases token usage.

enable_web_search

boolean

Enable web search beyond X to find additional context and information.

allowed_domains

string[]

When web search is enabled, limit results to these domains (e.g., [“arxiv.org”, “openai.com”]).

min_likes

number

Minimum number of likes/favorites. Only returns posts with at least this many likes.

min_retweets

number

Minimum number of retweets. Only returns posts with at least this many retweets.

min_replies

number

Minimum number of replies. Only returns posts with at least this many replies.

Response

Returns a JSON object with the following properties:

status

string

The status of the search operation. Returns “success” when the search completes successfully, or “error” on failure.

query

string

The original search query that was executed.

message

string

AI-generated summary of the search findings. Only present when status is “success”.

citations

string[]

Array of X post URLs used as sources for the summary. Only present when status is “success”.

toolCalls

object[]

Array of tool calls made by the AI agent during search, showing what searches were performed. Each object contains function name and arguments. Only present when status is “success”.

errorMessage

string

Error details if the search failed. Only present when status is “error”.

x_live_search_async

Starts an asynchronous search of X (formerly Twitter) for posts matching the query and optional filters using xAI’s Agentic Search Tools API. Returns a task ID immediately that can be used to check status and retrieve results. This is useful for avoiding timeouts on long-running searches.

Arguments

Accepts a JSON object with the following properties:

query

string

required

The search query to execute on X (formerly Twitter). Natural language queries work best with the agentic search API.

allowed_x_handles

string[]

List of X handles to include in search (up to 10). Format without @ symbol, e.g., [“elonmusk”, “OpenAI”].

excluded_x_handles

string[]

List of X handles to exclude from search (up to 10). Format without @ symbol.

from_date

string

Start date for posts in ISO8601 format (YYYY-MM-DD).

to_date

string

End date for posts in ISO8601 format (YYYY-MM-DD).

enable_image_understanding

boolean

Enable AI analysis of images in posts. Increases token usage.

enable_video_understanding

boolean

Enable AI analysis of videos in X posts. Increases token usage.

enable_web_search

boolean

Enable web search beyond X to find additional context and information.

allowed_domains

string[]

When web search is enabled, limit results to these domains (e.g., [“arxiv.org”, “openai.com”]).

min_likes

number

Minimum number of likes/favorites. Only returns posts with at least this many likes.

min_retweets

number

Minimum number of retweets. Only returns posts with at least this many retweets.

min_replies

number

Minimum number of replies. Only returns posts with at least this many replies.

Response

Returns a JSON object with the following properties:

taskId

string

A unique task identifier that can be used with x_get_search_async to check the status and retrieve the result.

x_get_search_async

Retrieves the status and result of an asynchronous X search task using the task ID. Tasks expire after 12 hours.

Arguments

Accepts a JSON object with the following properties:

taskId

string

required

The task ID returned from x_live_search_async.

Response

Returns a JSON object with the following properties:

status

string

The current status of the task. Can be “pending”, “in_progress”, “completed”, or “error”.

result

object

The search result object. Only present when status is “completed”. Contains the same fields as the x_live_search response (status, query, message, citations, toolCalls).

error

string

Error details if the search failed. Only present when status is “error”.

createdAt

number

Unix timestamp (in milliseconds) when the task was created.

completedAt

number

Unix timestamp (in milliseconds) when the task completed. Only present when status is “completed” or “error”.

Usage

Define the X Live Search service

Create a reusable service configuration that points to the MCP server and standardizes how you pass arguments and read results. This lets your agent easily interact with the X Live Search tool in a consistent manner.

const xLiveSearchService = {
    mcpServer: 'https://x-live-search.mcp.atxp.ai/',
    toolName: 'x_live_search',
    asyncSearchToolName: 'x_live_search_async',
    getSearchAsyncToolName: 'x_get_search_async',
    description: 'ATXP X Live Search MCP server',
    getArguments: (params: {
      query: string,
      allowed_x_handles?: string[],
      excluded_x_handles?: string[],
      from_date?: string,
      to_date?: string,
      enable_image_understanding?: boolean,
      enable_video_understanding?: boolean,
      enable_web_search?: boolean,
      allowed_domains?: string[],
      min_likes?: number,
      min_retweets?: number,
      min_replies?: number
    }) => params,
    getResult: (result: any) => {
      const jsonResult = result.content[0].text;
      const parsed = JSON.parse(jsonResult);
      return {
        status: parsed.status,
        query: parsed.query,
        message: parsed.message,
        citations: parsed.citations,
        toolCalls: parsed.toolCalls,
        errorMessage: parsed.errorMessage
      };
    },
    getAsyncCreateResult: (result: any) => {
      const jsonResult = result.content[0].text;
      const parsed = JSON.parse(jsonResult);
      return { taskId: parsed.taskId };
    },
    getAsyncStatusResult: (result: any) => {
      const jsonResult = result.content[0].text;
      const parsed = JSON.parse(jsonResult);
      return {
        status: parsed.status,
        result: parsed.result,
        error: parsed.error,
        createdAt: parsed.createdAt,
        completedAt: parsed.completedAt
      };
    }
  };

Create an ATXP client

Using an ATXP account
Using a Base account
Using a Solana account
Using a Worldchain account
Using a Polygon account

Create a client using an ATXP account by importing the ATXP client SDK and other dependencies.

// Import the ATXP client SDK
import { atxpClient, ATXPAccount } from '@atxp/client';

// Read the ATXP account details from environment variables
const atxpConnectionString = process.env.ATXP_CONNECTION;

// Create a client using the `atxpClient` function
const client = await atxpClient({
  mcpServer: xLiveSearchService.mcpServer,
  account: new ATXPAccount(atxpConnectionString),
});

Create a client using a Base account by importing the ATXP client SDK and other dependencies.

// Import the ATXP client SDK and Base account
import { atxpClient } from '@atxp/client';
import { BaseAccount } from '@atxp/base';

// Read the Base account details from the environment variables
const baseRpcUrl = process.env.BASE_RPC_URL;
const basePrivateKey = process.env.BASE_PRIVATE_KEY;

// Create a client using the `atxpClient` function
const client = await atxpClient({
  mcpServer: xLiveSearchService.mcpServer,
  account: new BaseAccount(baseRpcUrl, basePrivateKey),
});

Create a client using a Solana account by importing the ATXP client SDK and other dependencies.

// Import the ATXP client SDK and Solana account
import { atxpClient } from '@atxp/client';
import { SolanaAccount } from '@atxp/solana';

// Read the Solana account details from the environment variables
const solanaRpcUrl = process.env.SOLANA_RPC_URL;
const solanaPrivateKey = process.env.SOLANA_PRIVATE_KEY;

// Create a client using the `atxpClient` function
const client = await atxpClient({
  mcpServer: xLiveSearchService.mcpServer,
  account: new SolanaAccount(solanaRpcUrl, solanaPrivateKey),
});

Create a client using a Worldchain account with MiniKit integration.

// Import the ATXP client SDK and Worldchain account creator
import { atxpClient } from '@atxp/client';
import { createMiniKitWorldchainAccount } from '@atxp/worldchain';
import { MiniKit } from '@worldcoin/minikit-js';

// Create a Worldchain account using MiniKit
const account = await createMiniKitWorldchainAccount({
  walletAddress: '0x1234...', // User's wallet address
  miniKit: MiniKit
});

// Create a client using the `atxpClient` function
const client = await atxpClient({
  mcpServer: xLiveSearchService.mcpServer,
  account,
});

Browser applications:

// Import the ATXP client SDK and Polygon browser account
import { atxpClient } from '@atxp/client';
import { PolygonBrowserAccount } from '@atxp/polygon';

// Initialize the Polygon browser account with wallet provider
const account = await PolygonBrowserAccount.initialize({
  provider: window.ethereum, // or any EIP-1193 provider
  walletAddress: '0x1234...', // User's wallet address
});

// Create a client using the `atxpClient` function
const client = await atxpClient({
  mcpServer: xLiveSearchService.mcpServer,
  account,
});

Server/CLI applications:

// Import the ATXP client SDK and Polygon server account
import { atxpClient } from '@atxp/client';
import { PolygonServerAccount } from '@atxp/polygon';

// Read the Polygon account details from the environment variables
const polygonRpcUrl = process.env.POLYGON_RPC_URL;
const polygonPrivateKey = process.env.POLYGON_PRIVATE_KEY;

// Create a Polygon server account
const account = new PolygonServerAccount(
  polygonRpcUrl,
  polygonPrivateKey,
  137 // Chain ID: 137 = Polygon mainnet, 80002 = Amoy testnet
);

// Create a client using the `atxpClient` function
const client = await atxpClient({
  mcpServer: xLiveSearchService.mcpServer,
  account,
});

Use the X Live Search service in your agent

Synchronous Search
Asynchronous Search

Call the X Live Search tool by passing your search query and optional filters as arguments.Read the response using the getResult method.

const searchParams = {
  query: "What are the latest updates from Stripe?",
  allowed_x_handles: ["stripe"],
  from_date: "2024-01-01",
  min_likes: 100  // Only show posts with at least 100 likes
};

try {
  const result = await client.callTool({
      name: xLiveSearchService.toolName,
      arguments: xLiveSearchService.getArguments(searchParams),
  });
  const { status, query, message, citations, toolCalls, errorMessage } = xLiveSearchService.getResult(result);

  if (status === 'success') {
    console.log('Query:', query);
    console.log('Summary:', message);
    console.log('Citations:', citations);
    console.log('Tool Calls:', toolCalls); // See what the agent did
  } else {
    console.error('Search failed:', errorMessage);
  }
} catch (error) {
  console.error(`Error with ${xLiveSearchService.description}:`, error);
  process.exit(1);
}

You should see the search summary and citations printed in your console.

For longer search tasks or to avoid timeouts, use the async tools to start the search and poll for completion.

const searchParams = {
  query: "What are the latest updates from Stripe?",
  allowed_x_handles: ["stripe"],
  from_date: "2024-01-01",
  min_likes: 100  // Only show posts with at least 100 likes
};

try {
  // Start async search
  const asyncResult = await client.callTool({
      name: xLiveSearchService.asyncSearchToolName,
      arguments: xLiveSearchService.getArguments(searchParams),
  });
  const { taskId } = xLiveSearchService.getAsyncCreateResult(asyncResult);
  console.log('Search started with task ID:', taskId);

  // Poll for completion
  let completed = false;
  while (!completed) {
    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds

    const statusResult = await client.callTool({
        name: xLiveSearchService.getSearchAsyncToolName,
        arguments: { taskId },
    });
    const { status, result, error } = xLiveSearchService.getAsyncStatusResult(statusResult);

    console.log('Status:', status);

    if (status === 'completed') {
      console.log('Query:', result.query);
      console.log('Summary:', result.message);
      console.log('Citations:', result.citations);
      console.log('Tool Calls:', result.toolCalls); // See what the agent did
      completed = true;
    } else if (status === 'error') {
      console.error('Search failed:', error);
      completed = true;
    }
  }
} catch (error) {
  console.error(`Error with ${xLiveSearchService.description}:`, error);
  process.exit(1);
}

You should see the task ID printed first, followed by status updates, and finally the search summary and citations when the search completes.

Overview

Web and Data

Storage

Creative

Development

Other

Overview

Example prompts

Tools

Arguments

Response

Arguments

Response

Arguments

Response

Usage

​Overview

​Example prompts

​Tools

​Arguments

​Response

​Arguments

​Response

​Arguments

​Response

​Usage

Overview

Example prompts

Tools

Arguments

Response

Arguments

Response

Arguments

Response

Usage