Conecte qualquer ferramenta de IA compatível com MCP (Grok Build, Cursor, Claude, VS Code, …) 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.
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.
Simples — Bearer app-only. Cole o Bearer token do seu app em um cabeçalho Authorization no cliente MCP. Sem ponte, sem login no 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.
Registre o redirect URIhttp://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 em algum momento você executar xurl auth oauth2 manualmente (por exemplo, no fluxo headless abaixo), exporte-os como variáveis de ambiente naquela shell primeiro — sem eles, o login falha no navegador.
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.
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.
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.
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 nesta 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/codexurl auth oauth2 --app my-app --headless # for a specific app
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:
O login OAuth autoriza qualquer conta X que estiver logada quando o navegador abrir — não necessariamente a conta que é dona do app. Se você está 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 previamente autorizado).
xurl --app my-app mcp # bridge using a specific registered appxurl 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.
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 é executado → coloque-os no bloco env do cliente, ou use export para defini-los na sua 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
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.
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.
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.
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):
Você pode usá-la para gerar automaticamente clientes de API, importar no Postman, alimentar agentes de IA customizados ou validar schemas de request/response.
