Thalovant MCP server

Thalovant MCP Server

Public-ready MCP server for Thalovant control-plane and hub runtime APIs.

It uses the official Thalovant Node.js SDK and the production MCP TypeScript SDK over stdio and Streamable HTTP, so it works with local MCP hosts such as Claude Desktop, Codex, Cursor, and remote MCP clients.

What It Includes

• stdio transport for local agents.
• Streamable HTTP transport at /mcp for remote agents.
• OAuth-style protected resource metadata at /.well-known/oauth-protected-resource.
• Static bearer tokens for simple/private deployments.
• JWT/JWKS and OAuth token introspection for production remote deployments.
• Per-principal Thalovant credentials and tool policy.
• Host/origin validation, CORS, rate limiting, body limits, secure headers, and session binding.
• Optional resumability event storage and JSONL audit logs.
• Docker, Compose, Kubernetes, CI, npm package metadata, and MCP registry server.json.

Why TypeScript

Thalovant publishes SDKs for Python, Node.js, Go, and Rust. This server uses Node.js because @thalovant/sdk directly exposes the Thalovant control plane, identity loading, WSS/HTTPS/MQTT runtime clients, memory, analytics, and context helpers, while @modelcontextprotocol/sdk is the best-supported path for cross-agent stdio and Streamable HTTP servers.

Install

npm install
npm run build

Node.js 20 or newer is required.

Control-Plane Auth

Public hub discovery does not need Thalovant credentials. Private control-plane tools and runtime hub tools read credentials only from the MCP server environment or server-side principal credential files. Do not pass API tokens or passwords through chat or tool arguments.

The server selects control-plane auth in this order:

1. THALOVANTAPITOKEN — a scoped Thalovant API token. Recommended.
2. THALOVANTACCESSTOKEN — a pre-issued session access token.
3. THALOVANTEMAIL + THALOVANTPASSWORD — interactive-account login fallback.

When a token is set, the server never calls the login endpoint. thalovantconfigstatus reports the active mode as controlPlaneAuthMode without revealing token values.

API Tokens (Recommended For AI Agents And CI)

Scoped API tokens are the right credential for AI and automation use: they are minted from the Thalovant dashboard (or through the device flow), carry only the scopes you grant, can be revoked individually, and never involve your account password or MFA. Tokens start with tvpat_.

export THALOVANT_API_TOKEN="tvpat_..."
export THALOVANT_API_URL="https://api.thalovant.com"

npm start

Minimum scopes for the full control-plane tool surface:

Shortened. The full README is on GitHub.