x-search-mcp

Minimal MCP server for xAI X search using the Responses API and structured outputs.

Features

Single MCP tool: x_search
Uses xAI Responses API with x_search tool calling
Structured output parsing + citation normalization

Requirements

Node.js >= 18
XAI_API_KEY environment variable

Install

npm install npm run build

Run (stdio)

XAI_API_KEY=your-key-here node dist/index.js

Codex MCP config (example)

[mcp_servers.x-search] command = "node" args = ["/path/to/x-search-mcp/dist/index.js"] [mcp_servers.x-search.env] XAI_API_KEY = "your-key-here"

Smoke test (optional)

XAI_API_KEY=your-key-here npm run build XAI_API_KEY=your-key-here npm run smoke-test

Note: this test requires network access and may fail in restricted environments.

MCP Tool

`x_search`

Searches X with optional filters.

Input

{ "query": "string", "allowed_x_handles": ["string"], "excluded_x_handles": ["string"], "from_date": "YYYY-MM-DD", "to_date": "YYYY-MM-DD", "enable_image_understanding": true, "enable_video_understanding": true, "include_raw_response": false }

Output

{ "answer": "string", "citations": ["https://x.com/..."], "inline_citations": [ { "url": "https://x.com/...", "start_index": 10, "end_index": 42, "title": "1" } ], "raw_response": {} }

Environment Variables

XAI_API_KEY (required)
XAI_MODEL (default: grok-4-1-fast)
XAI_BASE_URL (default: https://api.x.ai/v1)
XAI_TIMEOUT (default: 30000)

Notes

allowed_x_handles and excluded_x_handles are mutually exclusive.
Date filters must be YYYY-MM-DD and from_date must be <= to_date.
Tool responses are returned as MCP structuredContent (with a text fallback for display).
Citations are normalized from xAI response annotations when available.