X MCP & Agent Tooling

Appearance

Configure Credentials Fresh ​

XMCP reads all of its configuration from the local .env file. This page details every credential XMCP needs, where it comes from, and how the OAuth 1.0a flow behaves at startup.

The required three ​

These must be set or the server will not start:

VariableSourcePurpose
X_OAUTH_CONSUMER_KEYDeveloper Console → your appOAuth 1.0a consumer (API) key
X_OAUTH_CONSUMER_SECRETDeveloper Console → your appOAuth 1.0a consumer secret
X_BEARER_TOKENDeveloper Console → your appApp-only Bearer token (keep set even when using OAuth 1.0a)
bash
X_OAUTH_CONSUMER_KEY=your_consumer_key
X_OAUTH_CONSUMER_SECRET=your_consumer_secret
X_BEARER_TOKEN=your_bearer_token

OAuth 1.0a callback settings ​

XMCP runs a tiny local web server to receive the OAuth 1.0a callback during consent. Defaults are fine for most setups:

bash
X_OAUTH_CALLBACK_HOST=127.0.0.1
X_OAUTH_CALLBACK_PORT=8976
X_OAUTH_CALLBACK_PATH=/oauth/callback
X_OAUTH_CALLBACK_TIMEOUT=300

The resulting callback URL - which you must register in the Developer Console - is:

http://127.0.0.1:8976/oauth/callback

OAuth 1.0a flow at startup ​

sequenceDiagram
    participant U as You
    participant S as XMCP server
    participant B as Browser
    participant X as X OAuth
    S->>B: Open consent URL on startup
    B->>X: Authorize app
    X-->>B: Redirect to callback URL
    B->>S: Deliver verifier to callback
    S->>X: Exchange for access tokens
    X-->>S: Access token + secret
    Note over S: Tokens held in memory only

Tokens are not persisted

OAuth tokens live in memory for the lifetime of the server process. Restart the server and you re-run consent.

For debugging the auth exchange:

bash
X_OAUTH_PRINT_TOKENS=1        # print tokens to the console
X_OAUTH_PRINT_AUTH_HEADER=1   # print the signed Authorization header

Server and API settings (optional) ​

bash
X_API_BASE_URL=https://api.x.com   # default
X_API_TIMEOUT=30                   # seconds
MCP_HOST=127.0.0.1                 # MCP bind host
MCP_PORT=8000                      # MCP bind port
X_API_DEBUG=1                      # verbose API logging

Tool filtering (optional) ​

Restrict which operations become tools. Comma-separated, applied at startup:

bash
X_API_TOOL_ALLOWLIST=getUsersByUsername,createPosts,searchPostsRecent

See Tool Allow-Listing for the full rationale and the Tool Catalog for every available name.

Optional: OAuth 2.0 and Grok client ​

bash
# OAuth 2.0 user token generation
CLIENT_ID=your_oauth2_client_id
CLIENT_SECRET=your_oauth2_client_secret
X_OAUTH_ACCESS_TOKEN=generated_access_token
X_OAUTH_ACCESS_TOKEN_SECRET=generated_token_secret   # if your flow returns one

# Grok MCP test client
XAI_API_KEY=your_xai_key
XAI_MODEL=grok-4-1-fast          # default
MCP_SERVER_URL=http://127.0.0.1:8000/mcp

See Generate an OAuth 2.0 Token for the full procedure.

Security best practices ​

Protect your secrets

  • Never commit .env to version control - add it to .gitignore.
  • Do not paste consumer secrets or tokens into shared chats, issues, or screenshots.
  • Use Tool Allow-Listing to limit what an agent can do (for example, read-only).
  • Regenerate credentials immediately if they are ever exposed.

Verification checklist ​

  • [ ] X_OAUTH_CONSUMER_KEY, X_OAUTH_CONSUMER_SECRET, X_BEARER_TOKEN all set
  • [ ] Callback URL matches the Developer Console registration
  • [ ] .env is gitignored
  • [ ] Optional allow-list configured if limiting scope

See also ​