Connect AI Agents via MCP

Xquik API MCP v2.5.4 exposes a credential-scoped REST catalog through 2 Model Context Protocol tools. Full account keys and OAuth tokens see 118 operations. Guest paid_reads keys see exactly 33 eligible GET routes.

All public X data reads need no connected X account. Every X write requires one. Private, account-scoped reads, including DMs and bookmarks, also require one. See Connect X account.

This page covers the API MCP server at https://xquik.com/mcp for authenticated account actions and guest paid reads. For public documentation search, use the Docs MCP server at https://docs.xquik.com/mcp.

Affected Codex and Goose releases discard the RFC 9207 iss value before token exchange. Xquik already returns the required issuer. Follow Codex and Goose OAuth issuer validation to use an environment-backed API key until your client includes a fix.

Connection

Protocol

Model Context Protocol over Streamable HTTP.

Endpoint

Connect clients to https://xquik.com/mcp.

Server version

Current API MCP server version: 2.5.4.

Authentication

Prefer OAuth 2.1. API keys remain available for clients with secure header storage.

Xquik compatibility discovery metadata is available at:

https://xquik.com/.well-known/mcp.json

GET and POST requests to /.well-known/mcp.json return an Xquik compatibility discovery document based on the official MCP Registry server.json manifest. GET /server.json and GET /.well-known/mcp/server-card.json return the same compatibility document. Its standard remotes entry identifies the streamable-http endpoint. Extra top-level convenience fields preserve compatibility with older clients, but they are not MCP Registry or experimental MCP Server Card fields. OAuth-aware clients read GET /.well-known/oauth-protected-resource/mcp for protected-resource metadata for https://xquik.com/mcp. Compatibility clients can also read GET /.well-known/oauth-protected-resource/.well-known/mcp.json, which redirects to the canonical metadata URL. Registry-compatible clients receive a streamable-http remote for https://xquik.com/mcp. OAuth-capable clients discover authentication from the endpoint. Clients without OAuth may send an API key as Authorization: Bearer {XQUIK_API_KEY} or x-api-key: {XQUIK_API_KEY}. Create API keys at https://dashboard.xquik.com/en/account?tab=api-keys. The direct client examples below use OAuth. Use the API-key fallback only when the client documents secure request headers. Agent discovery metadata is also available at https://xquik.com/.well-known/agent-index.json. That index lists com.xquik/mcp, https://xquik.com/mcp, https://xquik.com/.well-known/mcp.json, the OAuth authorization metadata, the protected-resource metadata, and https://xquik.com/auth.md. The auth.md file explains Client ID Metadata Documents (CIMD), Dynamic Client Registration (DCR), PKCE, and the mcp:tools scope. DCR at https://xquik.com/api/oauth/register is the supported anonymous OAuth client registration path when a client cannot use CIMD. Agent Skills discovery is available at https://xquik.com/.well-known/agent-skills/index.json. It publishes a SHA-256 digest for Xquik’s hosted SKILL.md so compatible agents can verify the downloaded instructions. Unauthenticated requests to https://xquik.com/mcp return 401 with a WWW-Authenticate: Bearer challenge. The challenge includes resource_metadata="https://xquik.com/.well-known/oauth-protected-resource/mcp", scope="mcp:tools", and the OAuth realm. The JSON body is { "error": "Authentication required" }. OAuth-capable clients use the challenge to discover the authorization metadata. API-key clients should send x-api-key on the first request. A supplied invalid bearer token adds error="invalid_token" and error_description="Invalid access token" to the challenge.

Authentication

The MCP server supports 2 authentication methods:

OAuth 2.1 (recommended): Compatible clients discover Xquik, open the browser login and consent flow, then store and refresh Bearer tokens. Xquik supports CIMD and DCR. No manual client ID, client secret, or API key is required for normal client setup.
API key (x-api-key or Authorization: Bearer xq_your_api_key_here): This is an Xquik-specific, non-OAuth fallback, not an OAuth access token. Clients must not apply OAuth discovery or refresh semantics to it. Use this fallback only when the client supports secure header storage but not OAuth. Full account keys expose 118 operations. Active guest keys expose only 33 paid_reads GET routes.

See OAuth 2.1 authorization for discovery URLs, token lifetimes, client registration, and implementation details. OAuth and full account API key behavior remain unchanged. A pending guest key cannot execute paid reads until verified payment activates it.

How it works

The MCP server uses a code-execution sandbox model with 2 tools:

explore

Search the authenticated catalog. Full credentials see 118 operations. Guest keys see 33 eligible GET routes. Read-only, no network calls, no credits.

xquik

Execute authenticated API calls. Cost follows the endpoint.

The AI agent writes async JavaScript arrow functions that run in a sandboxed environment. Auth is injected automatically. The code-mode design keeps the endpoint catalog outside the client context. Both tools publish titles and Model Context Protocol safety annotations so clients can distinguish read-only discovery from authenticated execution.

Tool	Title	Safety annotations
`explore`	Explore Xquik API	Read-only, idempotent, closed-world, non-destructive
`xquik`	Run Xquik API Calls	May mutate data, may access live services, not idempotent

For a guest paid_reads session, xquik is read-only, idempotent, and limited to live calls across the 33 eligible GET routes.

`explore` tool

Searches the 118-operation full account catalog. Free means no usage credits; the call still requires MCP authentication through an API key or OAuth Bearer token. The sandbox provides: With a guest paid_reads key, spec.endpoints contains only the 33 eligible GET read routes.

interface EndpointInfo {
  method: string;
  path: string;
  summary: string;
  category: string; // account, composition, credits, extraction, media, monitoring, support, twitter, x-accounts, x-write
  free: boolean;
  parameters?: Array<{ name: string; in: 'query' | 'path' | 'body'; required: boolean; type: string; description: string }>;
  responseShape?: string;
}

declare const spec: { endpoints: EndpointInfo[] };

`xquik` tool

Executes API calls. The sandbox provides:

declare const xquik: {
  request(path: string, options?: {
    method?: string;  // default: 'GET'
    body?: unknown;
    query?: Record<string, string>;
  }): Promise<unknown>;
};
declare const spec: { endpoints: EndpointInfo[] };

The agent writes code like async () => xquik.request('/api/v1/radar') and the server executes it with auth injected. xquik.request() automatically uses the normalized v1 contract. Responses use snake_case fields, date-time fields as Unix seconds, structured error objects, has_more, and next_cursor. A default REST createdAt field becomes created, not created_at, in MCP results.

MCP operation boundary

The REST contract documents 126 operations. A full account key or OAuth token exposes 118 through MCP. These 8 credential or session-bound operations stay outside the executable catalog:

Create, list, or revoke account API keys
Charge a saved payment method through quick top-up
Open the session-based account top-up redirect route
Create, poll, or top up a guest wallet

Guest wallet credential routes remain direct REST only. MCP cannot execute POST /api/v1/guest-wallets, POST /api/v1/guest-wallets/topups, or GET /api/v1/guest-wallets/status. Follow the accountless guest wallet guide for confirmation, checkout, polling, and top-up steps. A guest paid_reads MCP session exposes exactly the 33 eligible paid-read routes. It cannot execute mutations or noneligible routes. Never start checkout, top-up, subscription, or billing actions because another call returned 402. Report the choices, ask the user to select an amount and option, then wait for explicit confirmation. After confirmation, MCP may execute only an account checkout action present in the full catalog. Guest wallet actions remain direct REST.

MCP vs REST API

MCP follows REST authentication, authorization, billing, and response contracts for every exposed operation.

MCP Server

Best for AI agents, IDE integrations, and natural language workflows. Full account credentials expose 118 operations. Guest keys expose 33 eligible GET reads.

REST API

Best for backend services, automation scripts, guest wallet credential routes, and direct programmatic access. The REST contract documents all 126 operations and file download responses.

When to use MCP: You’re building an AI agent or working in an IDE (Claude Code, Cursor, VS Code, Windsurf) and want the agent to interact with X data through natural language. When to use REST: You’re building a backend service, automation pipeline, or need fine-grained control over API calls, pagination, and file exports.

Start with Claude.ai for OAuth login or Claude Code for terminal setup.

Client compatibility

Choose the authentication path that your current client can complete. Xquik keeps OAuth issuer, redirect, resource, and Proof Key for Code Exchange (PKCE) validation enabled for every client.

Client	API MCP authentication today	Registration and behavior
Claude Code	OAuth 2.1	Uses Client ID Metadata Documents (CIMD), secure token storage, and automatic refresh
OpenCode	OAuth 2.1	Uses Dynamic Client Registration (DCR) and refreshes tokens
Gemini CLI	OAuth 2.1	Uses DCR and prefers `url` with `type: "http"`; older builds also accept `httpUrl`
Cursor	OAuth 2.1	Uses DCR and accepts Cursor callback URLs
GitHub Copilot CLI	OAuth 2.1	Uses the browser authorization code flow and DCR
Cline	OAuth 2.1	Uses DCR from its MCP configuration flow
Qwen Code	OAuth 2.1	Uses DCR and its `httpUrl` Streamable HTTP field
Codex	Environment-backed API key	Affected releases can discard the required RFC 9207 `iss` callback value
Goose	Environment-backed API key	Affected releases can discard the required RFC 9207 `iss` callback value
Roo Code	Environment-backed API key	Roo Code’s archived final release has Streamable HTTP but no MCP OAuth provider
Pi	No native MCP path	Pi requires a separately installed and tested MCP adapter

Clients that ignore the optional RFC 9207 iss response parameter can still complete OAuth. Affected Codex and Goose releases instead require the parameter after discarding it, so retrying OAuth cannot repair the callback. Xquik does not weaken issuer validation for those releases.

Setup

Web and terminal clients

Claude.ai (Web)
Claude Desktop
Claude Code
ChatGPT

Open Claude Connectors or Customize > Connectors.
Select +, then Add custom connector.
Enter https://xquik.com/mcp.
Select Add.
In a chat, select + > Connectors, enable Xquik, then select Connect and approve access.

Leave the advanced client ID and client secret fields empty. Free accounts can add 1 custom connector. On Team and Enterprise plans, an Owner or Primary Owner must first add the Web connector under **Organization settings

Connectors > Add > Custom**. The feature is currently beta.

Claude Desktop uses the same remote custom connectors as Claude.ai. Open Customize > Connectors, add https://xquik.com/mcp, then complete the browser authorization flow.

Add the remote server:

claude mcp add --transport http xquik https://xquik.com/mcp

Run /mcp inside Claude Code, select xquik, then authenticate.

In ChatGPT on the web, open Settings > Apps > Advanced settings and enable Developer mode.
Open Settings > Apps > Create. Workspace administrators may instead use Workspace settings > Apps > Create.
Enter https://xquik.com/mcp, choose OAuth, then select Scan tools.
Complete Xquik authorization and select Create.

ChatGPT uses Xquik OAuth and cannot present a custom API key. Business and Enterprise/Edu workspaces support full MCP, including write tools. Pro supports read and fetch tools only. Custom MCP apps are web-only.

OpenAI

Codex CLI
Codex Desktop
Codex Config

Current Codex releases affected by openai/codex#31573 must use the Codex API-key fallback below. Do not run codex mcp login xquik while that fallback is active.After your Codex release includes the upstream issuer fix, remove bearer_token_env_var, then add Xquik and complete OAuth:

codex mcp add xquik --url https://xquik.com/mcp
codex mcp login xquik
codex mcp list

Codex CLI, the IDE extension, and the ChatGPT desktop app share the same config.toml MCP configuration.

Current affected releases use the environment-backed API-key fallback through the shared config.toml, then restart Codex Desktop. After your release includes the upstream fix, open Settings > MCP servers, add https://xquik.com/mcp as Streamable HTTP, select Authenticate, then restart.

Current affected releases use the bearer_token_env_var configuration in Codex API-key fallback. After your release includes the upstream fix, use this OAuth configuration in ~/.codex/config.toml or a trusted project’s .codex/config.toml:

[mcp_servers.xquik]
url = "https://xquik.com/mcp"

Then run codex mcp login xquik.

Codex API-key fallback

Use an environment-backed API key if Codex reports Authorization server response missing required issuer: expected https://xquik.com:

export XQUIK_API_KEY="xq_your_api_key_here"

Add this configuration to ~/.codex/config.toml or a trusted project’s .codex/config.toml:

[mcp_servers.xquik]
url = "https://xquik.com/mcp"
bearer_token_env_var = "XQUIK_API_KEY"

Restart Codex, then run codex mcp list. Do not run codex mcp login xquik while using the bearer-token fallback. Never commit the key or place its value directly in config.toml. See Codex OAuth issuer validation error for the client regression and recovery steps. Track the upstream Codex issue for a fixed release.

Editor clients

Cursor
VS Code
Windsurf
OpenCode

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "xquik": {
      "url": "https://xquik.com/mcp"
    }
  }
}

Cursor starts OAuth when the server first returns 401. You can also run cursor-agent mcp login xquik. Cursor currently lists MCP access on its paid Individual, Teams, and Enterprise plans.

Add to .vscode/mcp.json (project) or use MCP: Open User Configuration (global):

{
  "servers": {
    "xquik": {
      "type": "http",
      "url": "https://xquik.com/mcp"
    }
  }
}

Start the server from the MCP view and follow the OAuth prompt. VS Code stores the resulting authentication state.

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "xquik": {
      "serverUrl": "https://xquik.com/mcp"
    }
  }
}

Enable the server in Windsurf Settings > Cascade > MCP Servers, then complete OAuth. Enterprise users must enable MCP manually. Team policies may disable MCP or restrict servers to an allowlist.

Add to opencode.json:

{
  "mcp": {
    "xquik": {
      "type": "remote",
      "url": "https://xquik.com/mcp"
    }
  }
}

Then run:

opencode mcp auth xquik
opencode mcp list

Other terminal clients

GitHub Copilot CLI
Gemini CLI
Cline
Qwen Code

Add the remote server:

copilot mcp add --transport http xquik https://xquik.com/mcp

If your installed build does not expose the noninteractive add flags, start Copilot CLI and run /mcp add. Enter xquik, choose HTTP, enter https://xquik.com/mcp, keep * for tools, then press Ctrl+S. Run /mcp auth xquik after the server appears. Enterprise policy may block servers outside the organization allowlist.

Add the remote server:

gemini mcp add --transport http xquik https://xquik.com/mcp

Or add it to ~/.gemini/settings.json for user scope or .gemini/settings.json for project scope:

{
  "mcpServers": {
    "xquik": {
      "type": "http",
      "url": "https://xquik.com/mcp"
    }
  }
}

Older Gemini CLI builds also accept the legacy httpUrl field.Run /mcp auth xquik to complete OAuth.

Run cline mcp, add a Streamable HTTP server, and enter https://xquik.com/mcp. Select Authorize OAuth when Cline reports that authentication is required.

Enable encrypted token storage before adding Xquik:

export QWEN_CODE_FORCE_ENCRYPTED_FILE_STORAGE=true
qwen mcp add --transport http xquik https://xquik.com/mcp

Start Qwen Code, open /mcp, then authorize xquik. Qwen Code still uses httpUrl for manual Streamable HTTP configuration:

{
  "mcpServers": {
    "xquik": {
      "httpUrl": "https://xquik.com/mcp"
    }
  }
}

Remaining API-key and adapter paths

API-key fallback is client-specific. ChatGPT custom apps require OAuth and cannot present custom API keys. Codex uses the environment-backed bearer_token_env_var configuration above. For other clients, follow that client’s documented secret-input or environment-variable syntax. Never copy a generic header example into an incompatible schema, place a literal key in a configuration file, or commit a key.

Goose
Roo Code
Pi

Export your key, then add this entry to ~/.config/goose/config.yaml:

export XQUIK_API_KEY="xq_your_api_key_here"

extensions:
  xquik:
    type: streamable_http
    name: xquik
    enabled: true
    uri: "https://xquik.com/mcp"
    headers:
      Authorization: "Bearer ${XQUIK_API_KEY}"
    env_keys:
      - XQUIK_API_KEY
    envs: {}

Goose substitutes the environment variable before sending the header. Its current OAuth callback has the same RFC 9207 issuer handling defect as Codex. Follow Codex and Goose OAuth issuer validation.

Roo Code’s archived final release supports API-key headers, not MCP OAuth. Add this to global mcp_settings.json or project .roo/mcp.json:

{
  "mcpServers": {
    "xquik": {
      "type": "streamable-http",
      "url": "https://xquik.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XQUIK_API_KEY}"
      }
    }
  }
}

Export XQUIK_API_KEY before starting the editor. Do not place the key value in the JSON file.

Example prompts

Once connected, you can ask your AI agent things like: Monitoring & Events

Start watching @elonmusk for new tweets and replies.
List the accounts I am currently monitoring.
Show monitored account activity from today.
Replay stored events for monitor mon_123 using the last next_cursor as after.
Stop tracking @elonmusk.

Search & Lookup

Search recent X posts about TypeScript.
Find recent tweets from @vercel.
Read this tweet: https://x.com/elonmusk/status/1893456789012345678
Get metrics for this tweet: https://x.com/vercel/status/1893704267862470862

User Profiles & Follows

Get @username follower count.
Read @openai profile bio.
Check whether @elonmusk follows @SpaceX.
Check whether @vercel and @nextjs follow each other.

Trends

Show current X trends.
Show top trending topics in the US.
Check whether AI is trending today.

Radar & News

Show current Radar trends.
Show top developer trends today.
Show fastest-growing startup trends.
Get technology topics from the last 12 hours.
Show popular knowledge topics right now.
Show regional trends for a selected region.
Find trending tech news and draft a tweet about one item.

Extractions

Pull all replies to this tweet: https://x.com/elonmusk/status/1893456789012345678
List users who retweeted this tweet: https://x.com/vercel/status/1893704267862470862
Estimate the cost to extract all followers of @elonmusk.
Get quote tweets for this post: https://x.com/openai/status/1893456789012345678
Extract the full thread for this tweet: https://x.com/elonmusk/status/1893704267862470862

Giveaways

Pick 3 random winners from this tweet: https://x.com/example_user/status/1893456789012345678
Run a giveaway draw where participants must have retweeted and have at least 100 followers.
Show the results of my last giveaway draw.

Webhooks

Set up a webhook at https://my-server.com/events for new tweets.
List configured webhook endpoints.
Remove the webhook pointing to my old server.

Tweet Composition

Write a casual launch tweet for my new product.
Optimize the draft for engagement.
Score this draft: Just shipped v2.0 of our API. What do you think?
Improve this tweet to get more replies.

Style Analysis & Drafts

Analyze how @elonmusk tweets.
Compare @vercel and @nextjs tweeting styles.
Show cached tweet performance.
Save this tweet draft for later.
Show all saved drafts.
Set my X account to @myusername.

X Write Actions

Post a tweet saying: Just shipped v2.0!
Like this tweet: https://x.com/vercel/status/1893704267862470862
Retweet this: https://x.com/openai/status/1893456789012345678
Follow @vercel from my connected account.
Send a DM to user ID 44196397 saying hello.
Post a tweet saying: New feature! Use public image URL https://example.com/launch.png.

Account & Usage

Show my plan and month-to-date usage.
Check whether I have enough budget left for a large extraction.

Framework guides

Build agents with Xquik’s MCP tools in your preferred framework:

LangChain

Python agents with LangChain + LangGraph

CrewAI

Multi-agent crews with CrewAI

Pydantic AI

Type-safe agents with Pydantic AI

Google ADK

Multi-agent assistants with Google ADK

Mastra

TypeScript agents with Mastra

Microsoft Agent Framework

Python agents with Microsoft Agent Framework

Migrate from Composio

Move an existing Composio workflow to Xquik

AI agent skill

The Xquik Skill gives AI coding agents deep knowledge of the Xquik API without requiring an MCP connection. Install it to let your agent write API integrations, set up webhooks, and configure MCP connections using Xquik best practices. Works with 40+ AI coding agents including Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, VS Code, Gemini CLI, and more. The skill covers MCP tools and 126 REST API operations.

npx skills add Xquik-dev/x-twitter-scraper

​Connection

Protocol

Endpoint

Server version

Authentication

​Authentication

​How it works

explore

xquik

​explore tool

​xquik tool

​MCP operation boundary

​MCP vs REST API

MCP Server

REST API

​Client compatibility

​Setup

​Web and terminal clients

​OpenAI

​Codex API-key fallback

​Editor clients

​Other terminal clients

​Remaining API-key and adapter paths

​Example prompts

​Framework guides

LangChain

CrewAI

Pydantic AI

Google ADK

Mastra

Microsoft Agent Framework

Migrate from Composio

​AI agent skill

Connection

Authentication

How it works

`explore` tool

`xquik` tool

MCP operation boundary

MCP vs REST API

Client compatibility

Setup

Web and terminal clients

OpenAI

Codex API-key fallback

Editor clients

Other terminal clients

Remaining API-key and adapter paths

Example prompts

Framework guides

AI agent skill