Xquik

Máy chủ MCP được lưu trữ dành cho quy trình làm việc dữ liệu X (Twitter): tìm kiếm tweet, tra cứu người dùng, xuất người theo dõi, hành động phương tiện, giám sát và webhook.

Xem trên xquik.com

Tài liệu

Connect AI Agents via MCP for MCP & X API Agents

Connect AI agents to tweet search, profile lookup, follower exports, monitors, webhooks, and account actions with OAuth 2.1 and MCP. See tool examples.

For the complete documentation index, see llms.txt.

Xquik API MCP v2.6.0 exposes a scoped REST catalog through 2 Model Context Protocol tools. Full credentials see 120 catalog routes. Of these, 119 return JSON or text through MCP. Private support media downloads use REST. Guest paid_reads keys see exactly 33 GET routes.

Public tweet, profile, follower, reply, timeline, community, and list reads need no connected X account. Every X write requires one. Private reads, including DMs and bookmarks, also require one. See [Connect X account](/api-reference/x-accounts/connect). 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](/mcp/docs-mcp) 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](/guides/troubleshooting#codex-oauth-issuer-validation-error) to use an environment-backed API key until your client includes a fix.

Connection

Model Context Protocol over Streamable HTTP. Connect clients to `https://xquik.com/mcp`. Current API MCP server version: `2.6.0`. 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.

MCP 2026-07-28

Xquik supports MCP 2026-07-28 at the same Streamable HTTP endpoint. Current clients start with server/discover. They do not call initialize or create a session for a modern connection.

Use a current MCP SDK. It adds the request _meta envelope and required HTTP headers automatically. Modern requests must advertise both application/json and text/event-stream.

server/discover and tools/list include private cache hints with a 5-minute TTL. Clients can reuse those results for the same authorization context. Never share privately cached catalogs across users or credentials.

Xquik also accepts stateless 2025-era clients at the same endpoint. This keeps existing integrations working while current SDKs adopt 2026-07-28.

Modern Xquik connections are request-scoped. Ignore legacy session IDs and resume state. Let the client SDK negotiate the protocol.

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 fallback, not an OAuth token. Do not apply OAuth discovery or refresh rules. Use it only with secure header storage. Full account keys expose 120 catalog routes. Active guest keys expose 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:

Search the authenticated catalog. Full credentials see 120 routes. Guest keys see 33 GET routes. No network calls. No credits. Execute authenticated API calls. Cost follows the endpoint.

The AI agent writes async JavaScript arrow functions that run in a sandboxed environment. Authentication and required idempotency headers are 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 120-route full account catalog. The call uses no credits. MCP authentication remains required. 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;
  operationId: string;
  category: string; // account, composition, credits, extraction, media, monitoring, support, twitter, x-accounts, x-write
  free: boolean;
  injectedHeaders?: string[];
  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 | number | boolean>;
  }): Promise<unknown>;
};
declare const spec: { endpoints: EndpointInfo[] };

The agent writes code like async () => xquik.request('/api/v1/radar'). The server injects authentication and required idempotency headers. It reuses each generated key for bounded transient retries. After an unresolved write failure, verify state. Start a new attempt only when safe_to_retry is true.

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 128 operations. Full credentials expose 120 MCP catalog routes. These 8 credential and session operations stay outside the 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

The catalog includes private support attachment downloads. MCP rejects their binary responses. Use the REST download endpoint instead. The other 119 routes return MCP-compatible JSON or text.

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.

Use MCP for agents and IDE integrations. Full credentials expose 120 catalog routes. Guest keys expose 33 GET reads. Use REST for binary support downloads. Best for backend services, automation scripts, guest wallet credential routes, and direct programmatic access. The REST contract documents all 128 operations and file download responses.

When to use MCP: You're building an AI agent or working in an IDE. MCP lets the agent search tweets, inspect profiles, export followers, monitor accounts, and post 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](https://claude.ai) for OAuth login or [Claude Code](#setup) 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 automatic OAuth discovery and DCR; Streamable HTTP configuration uses `httpUrl`
Cursor	OAuth 2.1	Supports remote MCP OAuth and `cursor-agent mcp login`
GitHub Copilot CLI	OAuth 2.1	Uses the browser authorization code flow and DCR
Cline	OAuth 2.1	Completes OAuth 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

1. Open [Claude Connectors](https://claude.ai/settings/connectors) or **Customize > Connectors**. 2. Select **+**, then **Add custom connector**. 3. Enter `https://xquik.com/mcp`. 4. Select **Add**. 5. In a chat, select **+ > Connectors**, enable Xquik, then select **Connect** and approve access.

Leave the advanced client ID and client secret fields empty. Custom remote
connectors require Pro, Max, Team, or Enterprise. On Team and Enterprise,
an Owner or Primary Owner must add the connector first.

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:

```bash theme={null}
claude mcp add --transport http xquik https://xquik.com/mcp
```

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

1. In ChatGPT on the web, open **Settings > Security and login**. Enable **Developer mode**. 2. Open [**Settings > Plugins**](https://chatgpt.com/plugins). Select **+**. 3. Enter `https://xquik.com/mcp`, then select **Create**. 4. Sign in to Xquik and approve access. Confirm the tool list. 5. Start a new chat. Select **+ > More**, then select Xquik.

ChatGPT uses Xquik OAuth and cannot present a custom API key. Full MCP is in
beta for Business and Enterprise/Edu workspaces. Pro supports read and fetch
tools only. Link Xquik on the web first. The linked app then appears on
mobile. Follow
[OpenAI's current setup guide](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt)
when ChatGPT changes its labels.

OpenAI

Current Codex releases affected by [openai/codex#31573](https://github.com/openai/codex/issues/31573) must use the [Codex API-key fallback](#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:

```bash theme={null}
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](#codex-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](#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`:

```toml theme={null}
[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

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

```json theme={null}
{
  "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):

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "mcp": {
    "xquik": {
      "type": "remote",
      "url": "https://xquik.com/mcp"
    }
  }
}
```

Then run:

```bash theme={null}
opencode mcp auth xquik
opencode mcp list
```

Other terminal clients

Add the remote server:

```bash theme={null}
copilot mcp add xquik --type http --url 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:

```bash theme={null}
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:

```json theme={null}
{
  "mcpServers": {
    "xquik": {
      "httpUrl": "https://xquik.com/mcp"
    }
  }
}
```

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:

```bash theme={null}
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:

```json theme={null}
{
  "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.

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

```bash theme={null}
export XQUIK_API_KEY="xq_your_api_key_here"
```

```yaml theme={null}
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](/guides/troubleshooting#codex-oauth-issuer-validation-error).

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`:

```json theme={null}
{
  "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.

Pi's coding agent has no native MCP client. Install and audit a community MCP adapter before connecting Xquik, or call the [REST API](/api-reference/overview) from a Pi extension. Xquik does not claim native Pi compatibility.

Example prompts

Once connected, ask:

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 cursor.
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 current Reddit posts with text, links, media, and engagement signals.
Show top developer trends today.
Show startups ranked by available growth metrics.
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.
Research a fresh angle from Compose's Radar recommendations.
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:

Python agents with LangChain + LangGraph Multi-agent crews with CrewAI Type-safe agents with Pydantic AI Multi-agent assistants with Google ADK TypeScript agents with Mastra Python agents with Microsoft Agent Framework 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 Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, VS Code, Gemini CLI, and other Skill-capable agents. It covers MCP tools and 128 REST API operations.

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