Skip to main content

​
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

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.
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

1

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
      };
    }
  };
2

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),
});
3

Use the X Live Search service in your agent