# Hosted MCP server

> Connect Claude, ChatGPT, Claude Code, Cursor or VS Code to TwittrAPI by URL. Nothing to install; sign in with your TwittrAPI account (OAuth) or send your API key in a header.

HTML page: https://www.twittrapi.com/docs/hosted-mcp

{/* Server: twittrapi-mcp --http (Streamable HTTP, stateless). OAuth authorization server: TwitterDash /oauth/* and /.well-known/oauth-authorization-server. */}

The hosted MCP server gives AI apps the same read-only tools as the [twittrapi-mcp](https://github.com/twittrapi/twittrapi-mcp) package (profiles, tweets, followers, search, lists, communities, trends), without installing anything:

```text
https://mcp.twittrapi.com/mcp
```

Use the URL exactly like this, **with `/mcp` at the end**. `https://mcp.twittrapi.com` on its own is not the MCP endpoint; apps report "404 Not found" or cannot find the sign-in for it.

It speaks MCP over Streamable HTTP. Every tool call is one billed API call on your TwittrAPI balance, at your normal price and rate limit. Results use the [simple format](https://www.twittrapi.com/docs/simple-format) by default.

Video: [Connect your AI agent: hosted MCP server and agent skill](https://www.youtube.com/watch?v=sI4Ma2LQGug)

There are two ways to sign in:

| | How | For |
| --- | --- | --- |
| **OAuth** | The app opens a TwittrAPI page, you log in and click **Allow access**. The app never sees your API key. | Claude.ai, Claude Desktop, ChatGPT, Claude Code, VS Code |
| **API key header** | The app sends `Authorization: Bearer YOUR_API_KEY` or `X-API-KEY: YOUR_API_KEY` on every request. | Cursor, Claude Code, scripts, any client that lets you set headers |

## Claude.ai and Claude Desktop

1. Open **Settings > Connectors** and choose **Add custom connector**. On Team and Enterprise plans an owner adds it under the organization's connector settings first.
2. Name: `TwittrAPI`, URL: `https://mcp.twittrapi.com/mcp` (with `/mcp` at the end). Leave the advanced OAuth fields empty.
3. Click **Connect**, log in to your TwittrAPI account and click **Allow access**.

Claude Desktop uses the connectors of your Claude account, so the connector shows up there too.

## ChatGPT

1. Open **Settings > Apps & Connectors > Advanced settings** and turn on **Developer mode** (available on the plans that offer custom connectors).
2. Choose **Create**, enter the name `TwittrAPI`, the MCP server URL `https://mcp.twittrapi.com/mcp` and authentication **OAuth**.
3. Log in to your TwittrAPI account and click **Allow access**.

## Claude Code

With OAuth (Claude Code opens the browser when you authenticate in `/mcp`):

```bash
claude mcp add --transport http twittrapi https://mcp.twittrapi.com/mcp
```

With your API key instead:

```bash
claude mcp add --transport http twittrapi https://mcp.twittrapi.com/mcp \
  --header "Authorization: Bearer $TWITTRAPI_API_KEY"
```

## Cursor

Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project). Cursor reads the key from your environment:

```json
{
  "mcpServers": {
    "twittrapi": {
      "url": "https://mcp.twittrapi.com/mcp",
      "headers": { "X-API-KEY": "${env:TWITTRAPI_API_KEY}" }
    }
  }
}
```

## VS Code (GitHub Copilot agent mode)

Add `.vscode/mcp.json` to the workspace. VS Code signs you in with OAuth when the server starts:

```json
{
  "servers": {
    "twittrapi": {
      "type": "http",
      "url": "https://mcp.twittrapi.com/mcp"
    }
  }
}
```

To use your API key instead, add an input so the key is not stored in the file:

```json
{
  "inputs": [
    { "type": "promptString", "id": "twittrapi-key", "description": "TwittrAPI API key", "password": true }
  ],
  "servers": {
    "twittrapi": {
      "type": "http",
      "url": "https://mcp.twittrapi.com/mcp",
      "headers": { "X-API-KEY": "${input:twittrapi-key}" }
    }
  }
}
```

## Other clients

Any MCP client with Streamable HTTP support works. Send JSON-RPC as `POST` to `https://mcp.twittrapi.com/mcp` with your key in `X-API-KEY` or `Authorization: Bearer`. The server is stateless: there are no sessions and no server-sent event stream (`GET` returns 405), and the old SSE transport is not offered. Clients that only support stdio can use the [npm package](https://github.com/twittrapi/twittrapi-mcp) instead (`npx -y twittrapi-mcp`).

## What you approve, and how to disconnect

The consent page shows the app's name as the app registered it, the address the app receives the sign-in at, and that its calls are billed to your balance. Only continue if you started the connection yourself.

- Your apps are listed under **Connected apps** in the dashboard, with when they were connected and last used. **Disconnect** ends an app's access within a minute.
- Regenerating your API key disconnects every app. Reconnect them afterwards.
- Access tokens last one hour and are renewed by the app with a refresh token, which works once and expires after 30 days without use.
- The server only accepts tokens issued for it. Apps can register themselves (OAuth dynamic client registration) and must use PKCE; sign-in addresses must be `https` or a local address on your own computer.

## Limits and errors

- The same [rate limit](https://www.twittrapi.com/docs/helpful-infos/rate-limits) as your key applies, plus at most 8 requests in flight per key on the MCP server.
- A request may take up to 90 seconds and carry up to 256 KB.
- Tool errors come back as readable tool results: **402** means the balance is used up (top up, do not retry), **429** means slow down. Details: [Errors](https://www.twittrapi.com/docs/helpful-infos/error-handling).

## Troubleshooting

| Message | Fix |
| --- | --- |
| "Connecting to the server: 404 Not found" or "Couldn't determine how this server signs in" | The URL is missing `/mcp`. Remove the connector and add it again with `https://mcp.twittrapi.com/mcp`. Do not continue with manual configuration. |
| The login page says "Could not reach the server" | Reload the login page and log in again. |
| The app says it is not authorized after it worked before | The app was disconnected or your API key was regenerated. Remove the connector and connect it again. |

To run your own instance (for example inside a company network), see "HTTP mode" in the [twittrapi-mcp README](https://github.com/twittrapi/twittrapi-mcp).