Troubleshooting Fresh

Common problems setting up and running the X MCP servers, and how to fix them.

XMCP server

Symptom	Likely cause	Fix
Server exits on startup	Missing required .env values	Set X_OAUTH_CONSUMER_KEY, X_OAUTH_CONSUMER_SECRET, X_BEARER_TOKEN
OAuth callback never returns	Callback URL not registered or mismatched	Make .env callback exactly match the Developer Console registration
Browser does not open for consent	Headless environment	Set X_OAUTH_PRINT_TOKENS=1 / X_OAUTH_PRINT_AUTH_HEADER=1 and complete consent manually
Tools missing after a spec change	Spec cached at startup	Restart server.py
Auth works, then breaks after restart	Tokens are in-memory only	Re-run consent after each restart
Allow-list ignored	Changed .env without restart	Restart the server (the allow-list is applied at startup)

MCP client connection

Symptom	Likely cause	Fix
Client lists no tools	Server not running or wrong URL	Confirm server.py is up; match the URL and port
Connection refused	Port blocked or MCP_PORT changed	Align the client URL with MCP_HOST / MCP_PORT
Remote client cannot reach the server	No public tunnel	Tunnel the local server (for example ngrok http 8000) and use the public /mcp URL
Docs MCP returns nothing	Wrong URL	Use exactly https://docs.x.com/mcp

X API request errors

flowchart TD
    Err{Status code?} -->|401| A[Unauthorized]
    Err -->|403| B[Forbidden]
    Err -->|429| C[Too Many Requests]
    A --> A1[Check Bearer Token is correct and not regenerated; verify header format Bearer YOUR_TOKEN]
    B --> B1[App may lack access; endpoint may need user context OAuth 1.0a/2.0; check app permissions]
    C --> C1[Rate limited; check x-rate-limit-reset; use exponential backoff]

401 Unauthorized

• Check that your Bearer Token is correct.
• Ensure the token has not been regenerated.
• Verify the Authorization header format: Bearer YOUR_TOKEN.

403 Forbidden

• Your app may not have access to this endpoint.
• Some endpoints require user-context authentication (OAuth 1.0a or 2.0).
• Check your app's permissions in the Developer Console.

429 Too Many Requests

• You have hit a rate limit.
• Check the x-rate-limit-reset header for when to retry.
• Implement exponential backoff. See Rate Limits.

Grok test client

Symptom	Likely cause	Fix
Client cannot reach XMCP	Grok runs off-machine	Tunnel the server and set MCP_SERVER_URL to the public /mcp URL
Auth errors on tool calls	OAuth consent not completed	Start XMCP and finish the browser consent first
No xAI access	XAI_API_KEY missing	Set XAI_API_KEY in .env

See also

• Install XMCP
• Configure Credentials
• Rate Limits
• Limitations