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:
Claude.ai and Claude Desktop
Add TwexAPI as a custom connector.
ChatGPT
Connect with Developer mode on the web or desktop app.
Coding agents and editors
Claude Code, Codex, Cursor, VS Code, OpenCode, and Windsurf.
Build your own client
OAuth 2.1 endpoints, PKCE, scopes, and token lifetimes.
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 a127.0.0.1address 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 agentsfrom 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
@elonmuskthat mentionGrokorAI. 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
2104354931595423762and explain why each result is related.
User profiles and follows
- Read
@openaiprofile 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 thenext_cursorfor the next run.
Trends
- Show all supported global trend countries, then fetch top trend topics for
united-states. - Fetch trending tweets for
united-stateswith topictechnologyand content tagAI. Return tweet IDs, authors, and engagement metrics. - Compare trending topics for
united-states,japan, andunited-kingdomand 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
2104354931595423762and turn it into a Markdown outline.
Articles, communities, and lists
- Fetch X article
2104354931595423762as 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:
LangChain
Connect TwexAPI MCP tools to LangChain and LangGraph agents.
CrewAI
Build research crews that share one TwexAPI MCP connection.
Pydantic AI
Use type-safe agents with Streamable HTTP MCP tools.
Google ADK
Add TwexAPI tools to Gemini-powered ADK agents.
Mastra
Connect TypeScript agents to remote TwexAPI MCP tools.
No-code workflows
Hand off agent outputs to n8n, Zapier, Make, and Pipedream.
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