X MCP & Agent Tooling

Appearance

Connect an MCP Client Fresh ​

Once XMCP is running locally, point any MCP-compatible client at its endpoint. XMCP works with Cursor, Windsurf, custom agents, and any client that speaks the Model Context Protocol.

The connection ​

XMCP serves its MCP endpoint at:

http://127.0.0.1:8000/mcp

(unless you changed MCP_HOST / MCP_PORT).

Configuration ​

Add XMCP to your MCP client settings:

json
{
  "mcpServers": {
    "xmcp": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

That is the entire client-side setup. The server handles auth, the OpenAPI spec, and tool generation.

What you can ask ​

Once connected, your AI assistant can interact with X directly in natural language:

  • "search for recent posts about AI"
  • "look up @XDevelopers"
  • "create a post that says hello from my agent"
  • "who liked post 1460323737035677698?"

Each request maps to one of the generated tools (for example searchPostsRecent, getUsersByUsername, createPosts, getPostsLikingUsers). See the full Tool Catalog.

Local vs remote clients ​

flowchart TD
    subgraph Local
        C1[MCP client on same machine] --> L[127.0.0.1:8000/mcp]
    end
    subgraph Remote
        C2[Remote client / Grok] --> T[Tunnel e.g. ngrok]
        T --> L2[Local XMCP server]
    end
Client locationHow to connect
LocalPoint directly at http://127.0.0.1:8000/mcp
RemoteTunnel the local server (for example with ngrok) and use the public HTTPS URL ending in /mcp

For a remote client, expose the local server and use the public URL:

bash
ngrok http 8000
# then use: https://<id>.ngrok-free.dev/mcp

Connect both servers ​

You can run XMCP and the hosted Docs MCP at the same time so your assistant can both read documentation and call the API:

json
{
  "mcpServers": {
    "xmcp": {
      "url": "http://127.0.0.1:8000/mcp"
    },
    "x-docs": {
      "url": "https://docs.x.com/mcp"
    }
  }
}

See Run Both Servers Together for the combined workflow.

Verification checklist ​

  • [ ] XMCP server is running (python server.py)
  • [ ] Client config points at the correct URL and port
  • [ ] Client lists XMCP tools after connecting
  • [ ] A test prompt (for example a user lookup) returns data

Troubleshooting ​

SymptomLikely causeFix
Client shows no toolsServer not running or wrong URLConfirm server.py is up and the URL/port match
Connection refusedPort blocked or MCP_PORT changedAlign the client URL with MCP_HOST/MCP_PORT
Tools fail with auth errorsOAuth consent not completedRestart the server and complete the browser consent
Remote client cannot reach serverNo public tunnelRun a tunnel and use the public /mcp URL

See also ​