x-mcp

x-mcp is an X API MCP server built in Node.js. It exposes dedicated MCP tools generated from the upstream X OpenAPI spec, keeps secrets in Vault, keeps non-secret configuration in Postgres, and enforces tenant-aware auth scope as tenant/user or tenant/account.

The scope model is tenant/user or tenant/account.

What It Does

• Generates one x_api_* MCP tool per documented X API operationId
• Exposes discovery tools for LLMs: x_schema_discovery and x_query_suggestion
• Stores tenant-scoped app credentials and tenant/principal-scoped user credentials in Vault-backed profiles
• Stores defaults, metadata, and non-secret runtime configuration in Postgres
• Protects mutating tools with authorizationKey when MCP_ADMIN_AUTH_KEY is configured
• Supports stdio, HTTP, or both MCP transports

Runtime Layout

Key files:

• src/config/env.js: environment parsing and validation
• src/runtime/createRuntimeContext.js: shared runtime bootstrap
• src/services/xInventory.js: generated inventory loading and search
• src/services/xAuth.js: Vault/Postgres-backed credential profile storage and auth resolution
• src/services/xApi.js: authenticated X API execution layer
• src/mcp/server.js: MCP tool registration, mutation guards, and generated endpoint wiring
• src/http/server.js: HTTP MCP transport with auth, limits, and access logging

Persistence model:

• Vault stores actual secret values.
• Postgres stores profile metadata, default profile selectors, and all non-secret config.
• APP_NAME is the single naming source for derived Vault paths and Postgres table names.

Generated Inventory

Committed artifacts:

• artifacts/x-api.openapi.json
• artifacts/x-api.endpoint-inventory.json

Generate them with:

npm run inventory:generate

Check that the committed artifacts are current with:

npm run inventory:check

MCP Tool Families

All tools return JSON inside MCP text content.

Core tools:

• x_connection_info: runtime, inventory, Vault, and Postgres connection metadata
• x_scope_info: resolve tenant/principal scope paths and persistence details
• x_health_check: validate Vault and Postgres connectivity for a selected scope
• x_schema_discovery: search the generated X endpoint inventory
• x_query_suggestion: recommend a safe tool sequence for a workflow

Credential tools:

• x_auth_upsert_app_credentials
• x_auth_upsert_principal_credentials
• x_auth_get_scope_credentials
• x_auth_delete_profile

Config tools:

• x_config_list
• x_config_get
• x_config_set
• x_config_delete

Generated X API tools:

• one x_api_* tool per OpenAPI operationId
• rich tool descriptions include use cases, auth prerequisites, parameter constraints, response shape, common failures, and safety warnings

Generic fallback:

• x_api_request

Auth And Scope Model

App-scoped credentials are stored per tenant:

• Vault path: ${APP_NAME}/tenants/<tenant>/x-api/app-profiles/<profileKey>
• Postgres key: x.auth.app.profile.<profileKey>.meta

Principal-scoped credentials are stored per tenant principal:

• Vault path: ${APP_NAME}/tenants/<tenant>/<users|accounts>/<principal>/x-api/profiles/<profileKey>
• Postgres key: x.auth.principal.profile.<profileKey>.meta

Default selectors are stored in Postgres:

• x.auth.app.defaultProfileKey
• x.auth.principal.defaultProfileKey

Supported auth types:

• bearer token
• OAuth 2 user token
• OAuth 1a user token

If MCP_ADMIN_AUTH_KEY is configured, every mutating tool requires authorizationKey, including generated mutating endpoint tools and mutating x_api_request calls.

Environment

See .env.example for the full set. The most important groups are:

• POSTGRES_*
• VAULT_*
• MCP_*
• X_API_*

The default local scope is controlled by:

• MCP_CONFIG_DEFAULT_TENANT_ID
• MCP_CONFIG_DEFAULT_USER_ID
• MCP_CONFIG_DEFAULT_ACCOUNT_ID
• MCP_CONFIG_DEFAULT_PRINCIPAL_TYPE

Local Development

Install dependencies and generate the inventory:

npm ci
npm run inventory:generate

Run stdio:

npm run start:stdio

Run HTTP:

npm run start:http

Run both:

npm run start:both

MCP Client Registration

VS Code example:

{
  "command": "npm",
  "args": ["run", "start:stdio"],
  "cwd": "/Users/lesterjohn/Documents/GitHub/X-mcp"
}

Claude Desktop example:

{
  "mcpServers": {
    "x-mcp": {
      "command": "npm",
      "args": ["run", "start:stdio"],
      "cwd": "/Users/lesterjohn/Documents/GitHub/X-mcp"
    }
  }
}

If you need HTTP transport, point the client at http://127.0.0.1:3000/mcp after starting npm run start:http.

Infrastructure

docker-compose.yml runs local Postgres, Vault, and the HTTP MCP service. It preserves Vault Raft persistence and runs vault-unseal-key-init before Vault starts.

External Services Mode

docker-compose.external.yml is the supported External Services Mode for existing Vault and Postgres infrastructure. It requires POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, VAULT_ADDR, and VAULT_TOKEN to be provided by the deployment environment.

initdb/001_config.sh creates ${APP_NAME}_config with tenant/principal primary keys.

Production Vault

vault-production/README.md covers migration from the local development Vault to the Raft-backed production layout used by x-mcp.

CI And Push Enforcement

GitHub Actions in .github/workflows/inventory-and-tests.yml regenerates the X API inventory, fails if artifacts are stale, uploads the generated inventory artifacts, and runs npm run verify.

The local pre-push hook in .githooks/pre-push also runs:

npm run verify

This repository is configured to use .githooks as core.hooksPath.

Verification

Run the full verification path with:

npm run verify

The test suite covers:

• HTTP auth and transport behavior
• generated X tool registration and mutation auth enforcement
• discovery and query-suggestion behavior
• Vault token indexing and fallback semantics
• Vault production migration scaffolding
• X inventory artifact presence and push/test enforcement

License

MIT. See LICENSE.