Skip to content
Twexapi
English
Esc
↑↓navigate↵open⌘Jpreview
On this page

MCP Server

Connect Claude, ChatGPT, Cursor, and other AI agents to TwexAPI through the Model Context Protocol. Sign in with your TwexAPI account or use an API key.

TwexAPI runs a Model Context Protocol server at https://api.twexapi.io/mcp. AI assistants and coding agents can use it to search tweets, read profiles, followers, replies, threads, communities, lists, and trends. Every call uses your TwexAPI credits, the same as a REST request.

This page covers the API MCP server. To let an agent search the TwexAPI documentation instead, use the Docs MCP server at https://docs.twexapi.io/mcp, which needs no sign-in.

Quick start

Add the server

In your MCP client, add a remote server with the URL https://api.twexapi.io/mcp (Streamable HTTP). Leave API key and header fields empty if you want to sign in.

Sign in

Your client opens a browser at twexapi.io. Sign in with your TwexAPI account (email or Google), check where you will return to, choose whether to grant write access, and select Approve.

Ask

Start a chat and ask, for example: “Use TwexAPI to find trending topics in the United States and summarize the top tweets.”

Client-specific steps:

Authentication

The server accepts two kinds of credentials:

Method Use it for How
Sign in with TwexAPI (OAuth 2.1), recommended Clients that support MCP authorization: Claude.ai, Claude Desktop, Claude Code, ChatGPT, Cursor, Codex, VS Code, OpenCode Add only the server URL. The client handles sign-in.
API key Clients without MCP sign-in, scripts, and agent frameworks Send x-api-key: YOUR_API_KEY or Authorization: Bearer YOUR_API_KEY.

Create or copy your API key in the TwexAPI dashboard. ChatGPT cannot send custom headers, so it always uses sign-in.

What signing in grants

  • The app receives a token that works only on https://api.twexapi.io/mcp. It never sees your password or API key, and it cannot change your account or read your dashboard.
  • Calls are billed to your account’s credits, exactly like calls made with your API key.
  • Read access is always granted. Write access (posting tweets and replies through twexapi_write) is a checkbox on the consent page; clear it to connect read-only.
  • Access tokens last one hour and clients renew them automatically. An authorization that no app uses for 30 days expires.
  • Each time you connect a client, a new entry appears under Authorized apps in the dashboard. Select Revoke to cut an app off immediately. Removing a connector inside the client does not revoke it on our side.

Before you approve

  • Your account needs an active API key with credits left. Without credits, the consent page asks you to top up first. The request stays valid for 10 minutes, so you can top up and select Approve again.
  • Check the line After you approve, you will return to. It should name the app you are using, such as claude.ai, chatgpt.com, or a 127.0.0.1 address for desktop apps.

Discovery

MCP clients find everything they need from the server itself:

URL Purpose
https://api.twexapi.io/.well-known/oauth-protected-resource/mcp Protected resource metadata: points clients to the authorization server.
https://api.twexapi.io/.well-known/oauth-authorization-server Authorization server metadata: sign-in, token, registration, and revocation endpoints.
https://api.twexapi.io/.well-known/mcp.json MCP server card for registries. Also served at /.well-known/mcp/server-card.json.

A request without credentials returns 401 with a WWW-Authenticate: Bearer challenge that names the protected resource metadata URL. That challenge is how clients know to start sign-in. See OAuth for MCP clients for the full flow.

Tools

Tool What it does Available
explore Searches the endpoint catalog and returns methods, paths, parameters, examples, and which tool calls each endpoint. Uses no credits. Always
twexapi_request Calls a read-only endpoint, such as search, profiles, followers, replies, communities, lists, and trends. Always
twexapi_write Calls a write endpoint. Today this is posting a tweet or reply, which needs your X account cookie. When write access is granted

Clients such as Claude ask for confirmation before every twexapi_write call. Other write actions, such as likes, follows, and direct messages, are available through the REST API only. See the MCP tools reference for inputs, outputs, and the full catalog.

Credits and errors

Situation What you see
No credentials 401 with a sign-in challenge. Clients that support sign-in start it automatically.
Invalid API key, or an expired or revoked sign-in 401 with error="invalid_token". Sign in again, or check the key.
API key disabled in the dashboard 403 with “This TwexAPI API key is disabled.”
No credits left The connection still works and explore is free. Tool calls return “No credits left on this TwexAPI account. Top up at https://twexapi.io/dashboard and try again.”
Read-only authorization twexapi_write is hidden. Reconnect and keep the write checkbox selected to post.

Include the X-Request-Id response header and the UTC time when you report a connection problem.

Pay per call without an account

MCP clients that pay with the Machine Payments Protocol instead of an API key connect to https://api.twexapi.io/mcp/pay. That endpoint accepts anonymous requests and answers eligible tool calls with a payment challenge. The main /mcp endpoint always requires sign-in or an API key.

Claude.ai and Claude Desktop

Claude.ai and Claude Desktop share the same connectors, so you only add TwexAPI once.

Add a custom connector

Open Settings → Connectors and select Add custom connector. Enter TwexAPI as the name and https://api.twexapi.io/mcp as the URL. Leave the OAuth client ID and secret empty, then select Add.

Connect

Select Connect. Sign in on the TwexAPI page that opens and select Approve.

Use it in a chat

In a chat, open the + menu, enable TwexAPI under connectors, and ask your question.

On Team and Enterprise plans, an owner may need to allow custom connectors first.

Agent frameworks

Agent runtimes and scripts usually send an API key. For example, with the OpenAI Agents SDK:

from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(
    params={
        "url": "https://api.twexapi.io/mcp",
        "headers": {"x-api-key": "YOUR_API_KEY"},
    },
) as twexapi:
    # use TwexAPI as a tool provider
    pass

Load the key from an environment variable or secret store instead of hard-coding it.

MCP vs REST API

MCP Server

Best for AI assistants, IDE agents, and natural language workflows. The agent finds endpoints with explore and calls them with twexapi_request or twexapi_write.

REST API

Best for backend services, scheduled jobs, and direct integrations. Call https://api.twexapi.io/* with Authorization: Bearer YOUR_API_KEY. Use the API reference when you need every endpoint, fine-grained pagination, or SDK code.

Use MCP when you want an agent to work with X/Twitter data through natural language. Use REST when you are building a production backend or storing large result sets.

Example prompts

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

Search and lookup

  • Search recent X posts about AI agents from the last 24 hours. Return the top 20 tweets with tweet ID, author, created time, likes, reposts, and a one-line summary.
  • Find recent tweets from @elonmusk that mention Grok or AI. Group the results by topic and include direct X links.
  • Read this tweet: https://x.com/elonmusk/status/2104354931595423762. Summarize the post, then pull the most relevant replies and show reply IDs.
  • Get similar tweets for tweet ID 2104354931595423762 and explain why each result is related.

User profiles and follows

  • Read @openai profile bio and return username, display name, user ID, location, follower count, and profile URL.
  • Search X users for AI infrastructure. Return 25 accounts with username, bio, follower count, and why they match.
  • Get the latest followers for @elonmusk, then identify which accounts mention AI, startups, or crypto in their bios.
  • Pull one cursor-paginated followers page for @sama, return the first 20 users, and preserve the next_cursor for the next run.
  • Show all supported global trend countries, then fetch top trend topics for united-states.
  • Fetch trending tweets for united-states with topic technology and content tag AI. Return tweet IDs, authors, and engagement metrics.
  • Compare trending topics for united-states, japan, and united-kingdom and summarize what differs by region.

Replies, quotes, and threads

  • Pull replies to https://x.com/elonmusk/status/2104354931595423762, sort them by relevance, and return reply ID, author, text, and like count.
  • List 50 users who retweeted tweet ID 2104354931595423762. Return user ID, username, display name, and follower count if available.
  • Get quote tweets for tweet ID 2104354931595423762, then classify quotes as supportive, critical, or neutral.
  • Extract the full thread for tweet ID 2104354931595423762 and turn it into a Markdown outline.

Articles, communities, and lists

  • Fetch X article 2104354931595423762 as Markdown and convert it into a 5-bullet executive brief.
  • Search X communities for AI builders. Return community ID, name, member count, and description.
  • Search lists for AI founders. Return the top 10 lists with list ID, name, description, and member count.

Framework guides

Build agents with TwexAPI MCP tools in your preferred framework:

AI agent skill

The TwexAPI skill gives AI coding agents deep knowledge of the TwexAPI API without requiring an MCP connection. Install it to let your agent write API integrations, configure MCP connections, and use TwexAPI best practices.

npx skills add twexapi-dev/x-api-scraper-cli

Was this page helpful?