Servidores MCP para a X API e a documentação

Dois servidores MCP (Model Context Protocol) estão disponíveis para trabalhar com o X a partir de ferramentas de IA:

Servidor	O que faz	URL
X MCP	Chama endpoints da X API (busca de posts, consulta de usuários, bookmarks, trends, news, Articles e muito mais)	`https://api.x.com/mcp` (hospedado; conecte via `xurl mcp`)
Docs MCP	Pesquisa e lê a documentação da X API	`https://docs.x.com/mcp` (hospedado)

X MCP — X API

Conecte qualquer ferramenta de IA compatível com MCP (Grok Build, Cursor, Claude, VS Code, entre outras) diretamente à X API. O modelo pode então pesquisar todo o arquivo, consultar usuários, gerenciar bookmarks, buscar trends e news e redigir Articles — tudo com as permissões da sua própria conta X. A X API expõe um servidor MCP hospedado em Streamable HTTP em https://api.x.com/mcp (protocolo 2025-06-18, serverInfo: xmcp). Você o acessa por meio da ponte open-source xurl mcp, que cuida do OAuth para você e injeta um Bearer token novo em cada chamada.

Recursos em resumo

Categoria	O que o modelo pode fazer
Posts	Buscar posts, ver quem curtiu / repostou / citou, contagens recentes
Search	Busca de posts em todo o arquivo, busca de usuários, busca de news
Users	Resolver o usuário atual, consultar por id / handle, ler os posts, timeline e menções de um usuário
Bookmarks	Listar / adicionar / remover bookmarks e gerenciar pastas de bookmarks
News & Trends	Obter notícias, obter trends por localização (WOEID)
Articles	Criar rascunhos de Articles e publicá-los

Como funciona

O OAuth do X exige seu próprio app de desenvolvedor. Não há registro dinâmico de cliente, e api.x.com/mcp não anuncia descoberta nativa de OAuth do MCP. Em vez de apontar seu cliente diretamente para a URL, você executa uma pequena ponte local. A ponte detém a identidade do app, realiza o login único e mantém o token sempre atualizado.

A ponte roda via o lançador npm (npx), portanto não há etapa de instalação separada.
Na primeira execução sem token em cache, ela abre seu navegador para um login OAuth2 único, e depois faz cache e atualiza automaticamente o token para sempre.
Todos os diagnósticos vão para o stderr; o stdout permanece um canal JSON-RPC limpo.

Primeiros passos

Escolha um dos dois caminhos:

Simples — Bearer app-only. Cole o Bearer token do seu app em um cabeçalho Authorization no cliente MCP. Sem ponte, sem login pelo navegador. Endpoints somente de leitura; sem contexto de usuário (não age em seu nome). Funciona com clientes que suportam MCP remoto com cabeçalhos customizados.
Completo — ponte xurl mcp (contexto de usuário OAuth 2.0). Uma ponte local cuida do login OAuth 2.0 PKCE e atualiza os tokens automaticamente, então o modelo age com os escopos da sua conta. Necessário para escritas (bookmarks, Articles) e qualquer ferramenta de contexto de usuário.

Caminho simples (Bearer app-only)

Crie um app X no Portal do Desenvolvedor X.
Copie seu Bearer token App-only na página “Keys and tokens” do app.
Aponte seu cliente para https://api.x.com/mcp com o token em um cabeçalho Authorization — veja App-only (URL direta, sem ponte) abaixo para o snippet.

Caminho completo (ponte xurl)

Crie um app X com OAuth 2.0 habilitado.
Registre o redirect URI http://localhost:8080/callback no app (necessário para o login pelo navegador na primeira execução). Para usar outro, defina REDIRECT_URI e registre esse no lugar.
Copie seu CLIENT_ID e CLIENT_SECRET — você os colocará na configuração do cliente. Se algum dia você executar xurl auth oauth2 manualmente (por exemplo, no fluxo headless abaixo), exporte-os como variáveis de ambiente nesse shell antes — o login falha no navegador sem eles.
Tenha o Node.js instalado (para o npx).

Recomendamos que você instale o xurl:

brew install --cask xdevplatform/tap/xurl      # Homebrew
npm install -g @xdevplatform/xurl              # npm (global)
curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash

O primeiro login precisa de um navegador. Em uma máquina headless/remota, autentique-se primeiro fora de banda com xurl auth oauth2 --headless (fluxo de colar-código), depois a ponte simplesmente reutiliza o token em cache. Veja Headless.

Conecte seu cliente

1. Grok Build

[mcp_servers.xapi]
command = "npx"
args = ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"]
enabled = true
startup_timeout_sec = 300          # give the first-run browser login time

[mcp_servers.xapi.env]
CLIENT_ID = "YOUR_X_APP_CLIENT_ID"
CLIENT_SECRET = "YOUR_X_APP_CLIENT_SECRET"

[mcp_servers.xapi]
url = "https://api.x.com/mcp"
enabled = true

[mcp_servers.xapi.headers]
Authorization = "Bearer YOUR_APP_ONLY_BEARER_TOKEN"

Ou adicione a ponte xurl com um único comando (as flags -e viram o environment do servidor, e os args após -- vão para o npx):

grok mcp add xapi npx \
  -e CLIENT_ID=YOUR_X_APP_CLIENT_ID \
  -e CLIENT_SECRET=YOUR_X_APP_CLIENT_SECRET \
  -- -y @xdevplatform/xurl mcp https://api.x.com/mcp

Verifique e liste:

grok mcp doctor xapi      # ✓ server started, ✓ handshake OK, ✓ tools discovered
grok mcp list

Na primeira vez que uma ferramenta for invocada (ou no doctor), seu navegador abrirá para o login no X — conclua uma vez e está pronto.

2. Cursor

Crie ~/.cursor/mcp.json (global, todos os projetos) ou .cursor/mcp.json (apenas este projeto):

{
  "mcpServers": {
    "xapi": {
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": {
        "CLIENT_ID": "YOUR_X_APP_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET"
      }
    }
  }
}

{
  "mcpServers": {
    "xapi": {
      "url": "https://api.x.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_APP_ONLY_BEARER_TOKEN"
      }
    }
  }
}

Depois abra Cursor → Settings → MCP, confirme que xapi mostra um ponto verde e suas ferramentas. Na primeira utilização, o Cursor inicia a ponte e seu navegador abre para o login; a lista de ferramentas é preenchida assim que o handshake é concluído.

3. Claude Desktop

Edite claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "xapi": {
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": { "CLIENT_ID": "YOUR_X_APP_CLIENT_ID", "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET" }
    }
  }
}

{
  "mcpServers": {
    "xapi": {
      "url": "https://api.x.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_APP_ONLY_BEARER_TOKEN" }
    }
  }
}

Reinicie o Claude Desktop; as ferramentas do X aparecem no menu de ferramentas (🔌).

4. VS Code (GitHub Copilot / modo Agent)

Adicione a .vscode/mcp.json:

{
  "servers": {
    "xapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": { "CLIENT_ID": "YOUR_X_APP_CLIENT_ID", "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET" }
    }
  }
}

{
  "servers": {
    "xapi": {
      "type": "http",
      "url": "https://api.x.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_APP_ONLY_BEARER_TOKEN" }
    }
  }
}

5. Qualquer cliente MCP

Ponte xurl (stdio):

Campo	Valor
`command`	`npx`
`args`	`["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"]`
`env`	`CLIENT_ID`, `CLIENT_SECRET`
timeout de inicialização	≥ 300s (para que o login da primeira execução possa concluir)

Se você instalou o xurl nativamente, substitua command/args por "command": "xurl", "args": ["mcp", "https://api.x.com/mcp"]. Bearer App-only (HTTP remoto):

Campo	Valor
`url`	`https://api.x.com/mcp`
`headers.Authorization`	`Bearer YOUR_APP_ONLY_BEARER_TOKEN`

Autenticação

Contexto de usuário OAuth 2.0 (padrão)

A ponte autentica como você (fluxo PKCE), então as ferramentas agem com os escopos da sua conta. Ordem de resolução das credenciais: vars de ambiente CLIENT_ID/CLIENT_SECRET → o app ativo em ~/.xurl. A ponte armazena os tokens em cache em ~/.xurl e os atualiza automaticamente (incluindo uma atualização forçada após um 401). Sem token em cache, a ponte imprime no stderr e abre seu navegador:

[xurl mcp] no valid OAuth2 token; opening the browser to sign in -- complete the login to start the bridge...
[xurl mcp] authentication complete; starting bridge

O handshake do MCP fica em espera até você concluir — por isso os clientes precisam de um startup_timeout_sec generoso.

Máquinas headless / remotas

Sem navegador acessível? Autentique-se uma vez fora de banda e depois inicie o cliente:

# Obrigatório: o bloco env na configuração do seu cliente só se aplica à ponte,
# não a execuções manuais do xurl — exporte as credenciais neste shell primeiro.
export CLIENT_ID="YOUR_X_APP_CLIENT_ID"
export CLIENT_SECRET="YOUR_X_APP_CLIENT_SECRET"

xurl auth oauth2 --headless                 # prints an auth URL; you paste back the redirect URL/code
xurl auth oauth2 --app my-app --headless    # for a specific app

App-only (URL direta, sem ponte)

Para endpoints de leitura, você pode pular a ponte e apontar um cliente direto para a URL com um Bearer token App-only estático. Isso é útil para clientes que suportam MCP remoto com cabeçalhos customizados:

# ~/.grok/config.toml
[mcp_servers.xapi_direct]
url = "https://api.x.com/mcp"
enabled = true

[mcp_servers.xapi_direct.headers]
Authorization = "Bearer YOUR_APP_ONLY_BEARER_TOKEN"

Contrapartida: sem auto-refresh e sem contexto de usuário (sem ações em seu nome). A ponte é recomendada para funcionalidade completa.

Múltiplos apps e contas

O login OAuth autoriza a conta X que estiver logada quando o navegador abrir — não necessariamente a conta dona do app. Se você estiver postando em nome de uma conta secundária/bot, troque para essa conta no seu navegador antes de concluir o login (ou use -u para escolher um usuário já autorizado).

xurl --app my-app mcp                  # bridge using a specific registered app
xurl mcp -u alice https://api.x.com/mcp  # act as a specific OAuth2 user

Na configuração do cliente, adicione "--app", "my-app" ou "-u", "alice" aos args.

Referência de configuração

Configuração	Onde	Notas
`CLIENT_ID` / `CLIENT_SECRET`	`env`	Credenciais do seu app X (ou confie em um app registrado em `~/.xurl`)
`REDIRECT_URI`	`env`	Sobrescreve o callback; deve estar registrado no app. Padrão `http://localhost:8080/callback`
`startup_timeout_sec`	configuração do cliente	Defina ≥ 300 para que o login da primeira execução possa concluir
`[URL]` posicional	`args`	Padrão `https://api.x.com/mcp`
`--app NAME`	`args`	Usar um app registrado específico
`-u, --username`	`args`	Agir como um usuário OAuth2 específico

Overrides avançados de env (raramente necessários): AUTH_URL, TOKEN_URL, API_BASE_URL, INFO_URL.

Verificar e solucionar problemas

grok mcp doctor xapi          # Grok Build: end-to-end check
# or test the bridge by hand (Ctrl-C to exit):
npx -y @xdevplatform/xurl mcp https://api.x.com/mcp

Sintoma	Causa / Solução
Cliente expira na inicialização	Aumente `startup_timeout_sec` para 300+; a ponte está esperando seu login pelo navegador
Navegador nunca abre	Sem display (headless) → execute `xurl auth oauth2 --headless` primeiro; garanta que `npx` resolva
`401` / `token refresh failed`	Credenciais do app erradas, ou refresh token revogado → refaça o login (`xurl auth oauth2 [--app NAME]`)
Navegador mostra “Something went wrong — You weren’t able to give access to the App”	`CLIENT_ID`/`CLIENT_SECRET` não definidos onde o `xurl` roda → coloque-os no bloco `env` do cliente, ou faça `export` deles no seu shell antes de executar `xurl auth oauth2` manualmente
Erro de redirect/callback no navegador	`http://localhost:8080/callback` não registrado no app (ou `REDIRECT_URI` divergente)
`client-not-enrolled` após login	O app não está no pacote/ambiente X correto → no portal, mova-o para Pay-per-use + Production
`npx` puxa uma versão antiga	Um mirror de registry privado está como padrão → fixe `--registry=https://registry.npmjs.org/` em `args`
Saída de ferramenta vazia/corrompida	Não execute o cliente com `--verbose`; o stdout precisa permanecer um canal JSON-RPC limpo

Segurança e boas práticas

Trate ~/.xurl e os access tokens como segredos — não os cole em chats, logs ou configurações compartilhadas. Prefira .mcp.json/.grok/config.toml por projeto que referenciem variáveis de ambiente em vez de versionar segredos em texto puro.
Use um app dedicado para MCP somente com os escopos de que você precisa.
Operações de escrita contam contra rate limits (bookmarks, article_publish) e são mais restritas que as de leitura; espere 429s ocasionais e faça backoff.
A ponte é local — suas credenciais nunca saem da sua máquina, exceto como um Bearer token enviado por TLS para api.x.com.

Docs MCP — busca na documentação

O X hospeda um servidor MCP para a documentação da X API em https://docs.x.com/mcp. Conecte-o à sua ferramenta de IA para pesquisar e ler páginas de documentação sem sair do seu fluxo de trabalho.

Ferramentas disponíveis

Ferramenta	Descrição
`search_x`	Pesquisa na documentação do X por informações relevantes, exemplos de código, referências de API e guias
`get_page_x`	Recupera o conteúdo completo de uma página específica da documentação pelo caminho

Configuração

Adicione o servidor docs MCP à configuração do seu cliente MCP:

{
  "mcpServers": {
    "x-docs": {
      "url": "https://docs.x.com/mcp"
    }
  }
}

Isso é útil quando você está desenvolvendo com a X API e quer que seu assistente de IA consulte detalhes de endpoints, guias de autenticação ou exemplos de código em tempo real.

Usando ambos os servidores juntos

Você pode conectar os dois servidores MCP simultaneamente. Isso dá ao seu assistente de IA a capacidade de tanto consultar a documentação quanto chamar a API. Grok Build (~/.grok/config.toml):

[mcp_servers.xapi]
command = "npx"
args = ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"]
enabled = true
startup_timeout_sec = 300

[mcp_servers.xapi.env]
CLIENT_ID = "YOUR_X_APP_CLIENT_ID"
CLIENT_SECRET = "YOUR_X_APP_CLIENT_SECRET"

[mcp_servers.x-docs]
url = "https://docs.x.com/mcp"
enabled = true

Estilo Cursor / Claude (mcp.json):

{
  "mcpServers": {
    "xapi": {
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": {
        "CLIENT_ID": "YOUR_X_APP_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET"
      }
    },
    "x-docs": {
      "url": "https://docs.x.com/mcp"
    }
  }
}

Especificação OpenAPI

A especificação de API legível por máquina para todos os endpoints da X API v2.

Recurso	URL
OpenAPI Spec (JSON)	`https://api.x.com/2/openapi.json`

curl https://api.x.com/2/openapi.json -o openapi.json

Você pode usá-la para gerar automaticamente clientes de API, importar no Postman, alimentar agentes de IA customizados ou validar schemas de request/response.

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Servidores MCP para a X API e a documentação

X MCP — X API

Recursos em resumo

Como funciona

Primeiros passos

Caminho simples (Bearer app-only)

Caminho completo (ponte xurl)

Conecte seu cliente

1. Grok Build

2. Cursor

3. Claude Desktop

4. VS Code (GitHub Copilot / modo Agent)

5. Qualquer cliente MCP

Autenticação

Contexto de usuário OAuth 2.0 (padrão)

Máquinas headless / remotas

App-only (URL direta, sem ponte)

Múltiplos apps e contas

Referência de configuração

Verificar e solucionar problemas

Segurança e boas práticas

Docs MCP — busca na documentação

Ferramentas disponíveis

Configuração

Usando ambos os servidores juntos

Especificação OpenAPI

​X MCP — X API

​Recursos em resumo

​Como funciona

​Primeiros passos

​Caminho simples (Bearer app-only)

​Caminho completo (ponte xurl)

​Conecte seu cliente

​1. Grok Build

​2. Cursor

​3. Claude Desktop

​4. VS Code (GitHub Copilot / modo Agent)

​5. Qualquer cliente MCP

​Autenticação

​Contexto de usuário OAuth 2.0 (padrão)

​Login pelo navegador na primeira execução

​Máquinas headless / remotas

​App-only (URL direta, sem ponte)

​Múltiplos apps e contas

​Referência de configuração

​Verificar e solucionar problemas

​Segurança e boas práticas

​Docs MCP — busca na documentação

​Ferramentas disponíveis

​Configuração

​Usando ambos os servidores juntos

​Especificação OpenAPI

X MCP — X API

Recursos em resumo

Como funciona

Primeiros passos

Caminho simples (Bearer app-only)

Caminho completo (ponte xurl)

Conecte seu cliente

1. Grok Build

2. Cursor

3. Claude Desktop

4. VS Code (GitHub Copilot / modo Agent)

5. Qualquer cliente MCP

Autenticação

Contexto de usuário OAuth 2.0 (padrão)

Login pelo navegador na primeira execução

Máquinas headless / remotas

App-only (URL direta, sem ponte)

Múltiplos apps e contas

Referência de configuração

Verificar e solucionar problemas

Segurança e boas práticas

Docs MCP — busca na documentação

Ferramentas disponíveis

Configuração

Usando ambos os servidores juntos

Especificação OpenAPI