@thalovant/mcp-server 0.1.8 → 0.1.9

package/.env.example

@@ -3,6 +3,9 @@ THALOVANT_PROFILE=prod
 THALOVANT_API_URL=https://api.thalovant.com
 
 # Use one control-plane auth option for private/admin tools.
+# Recommended: a scoped, revocable API token (dashboard or device flow).
+# Minimum scopes for the full tool surface: hubs:read, clients:write, memory:read, memory:write.
+# THALOVANT_API_TOKEN=
 # THALOVANT_ACCESS_TOKEN=
 # THALOVANT_EMAIL=
 # THALOVANT_PASSWORD=

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.9
+
+- Added first-class scoped API token auth for the control plane: set `THALOVANT_API_TOKEN` and the server authenticates with the token directly and never calls the login endpoint. Precedence is `THALOVANT_API_TOKEN`, then `THALOVANT_ACCESS_TOKEN`, then the `THALOVANT_EMAIL`/`THALOVANT_PASSWORD` login fallback.
+- `thalovant_config_status` now reports the active control-plane auth mode (`controlPlaneAuthMode`: `api-token`, `access-token`, `email-password`, or `none`) and `hasApiToken`, without revealing token values.
+- Documented API tokens as the recommended auth mode for AI and CI use, including the minimum token scopes for the full control-plane tool surface: `hubs:read`, `clients:write`, `memory:read`, `memory:write`.
+- Clarified the unauthenticated-tool error to name `THALOVANT_API_TOKEN` as the recommended option.
+
 ## 0.1.8
 
 - Tightened memory tool input validation to match the control-plane API exactly: `title` max 160, `content` max 4096, `source` max 64, `consentScope` max 128, `consentVersion` max 64, `retentionPolicy` max 64 on create/update, and list `query` max 240, so invalid values fail with a clear client-side error instead of an opaque API 422.

package/README.md

@@ -29,13 +29,43 @@ npm run build
 
 Node.js 20 or newer is required.
 
-## Local Stdio
+## 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. `THALOVANT_API_TOKEN` — a scoped Thalovant API token. Recommended.
+2. `THALOVANT_ACCESS_TOKEN` — a pre-issued session access token.
+3. `THALOVANT_EMAIL` + `THALOVANT_PASSWORD` — interactive-account login fallback.
+
+When a token is set, the server never calls the login endpoint. `thalovant_config_status` 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_`.
+
+```bash
+export THALOVANT_API_TOKEN="tvpat_..."
+export THALOVANT_API_URL="https://api.thalovant.com"
+
+npm start
+```
+
+Minimum scopes for the full control-plane tool surface:
+
+| Scope | Used by |
+|-------|---------|
+| `hubs:read` | `thalovant_list_hubs`, `thalovant_get_hub`, `thalovant_get_analytics_overview`, and the hub lookup inside `thalovant_create_client_identity` |
+| `clients:write` | `thalovant_create_client_identity` (`POST /v1/clients`) |
+| `memory:read` | `thalovant_list_memory_items`, `thalovant_get_memory_summary`, `thalovant_get_memory_item` |
+| `memory:write` | `thalovant_create_memory_item`, `thalovant_update_memory_item`, `thalovant_delete_memory_item` |
+
+Grant fewer scopes for narrower deployments: a read-only assistant needs only `hubs:read` and `memory:read`. `thalovant_get_analytics_overview` with `admin: true` additionally requires an admin account with `admin:analytics`, which API tokens for regular use should not carry. Runtime hub tools (`thalovant_ask`, `thalovant_send_action`, and friends) use Thalovant client identities, not control-plane tokens.
+
+### Login Fallback
+
 ```bash
-export THALOVANT_ACCESS_TOKEN="..."
-# or
 export THALOVANT_EMAIL="you@example.com"
 export THALOVANT_PASSWORD="..."
 
@@ -45,6 +75,10 @@ export THALOVANT_API_URL="https://api.thalovant.com"
 npm start
 ```
 
+If neither a token nor email/password is configured, authenticated control-plane tools fail with a clear error naming the supported options.
+
+## Local Stdio
+
 The server speaks MCP over stdio and does not write logs to stdout.
 
 Runtime hub tools load local identities in this order:
@@ -208,6 +242,8 @@ MCP_HTTP_TRUST_PROXY=false
 
 ## Claude Desktop
 
+Recommended: authenticate with a scoped API token so the MCP config never contains your account password.
+
 ```json
 {
   "mcpServers": {
@@ -215,6 +251,7 @@ MCP_HTTP_TRUST_PROXY=false
       "command": "node",
       "args": ["/home/goldyfruit/Development/Thalovant/mcp/dist/index.js"],
       "env": {
+        "THALOVANT_API_TOKEN": "tvpat_...",
         "THALOVANT_PROFILE": "prod"
       }
     }
@@ -233,6 +270,7 @@ Use the same stdio command in your MCP client config:
       "command": "node",
       "args": ["/home/goldyfruit/Development/Thalovant/mcp/dist/index.js"],
       "env": {
+        "THALOVANT_API_TOKEN": "tvpat_...",
         "THALOVANT_PROFILE": "prod"
       }
     }

package/dist/index.js

@@ -14,7 +14,7 @@ import { mkdir } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRemoteJWKSet, jwtVerify } from "jose";
 import { z } from "zod";
-const VERSION = "0.1.8";
+const VERSION = "0.1.9";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 300_000;
 const MAX_LIMIT = 100;
@@ -423,7 +423,8 @@ async function createControlPlane(options) {
     const credential = await credentialForPrincipal(principal);
     const canUseShared = allowSharedThalovantCredentials(principal);
     const apiUrl = options.apiUrl ?? credential?.control?.apiUrl ?? (canUseShared ? process.env.THALOVANT_API_URL : undefined) ?? DEFAULT_CONTROL_API_URL;
-    const accessToken = credential?.control?.accessToken ?? (canUseShared ? process.env.THALOVANT_ACCESS_TOKEN : undefined);
+    const accessToken = credential?.control?.accessToken ??
+        (canUseShared ? process.env.THALOVANT_API_TOKEN ?? process.env.THALOVANT_ACCESS_TOKEN : undefined);
     const api = new ThalovantControlPlane(apiUrl, {
         accessToken,
         userAgent: `thalovant-mcp/${VERSION}`,
@@ -439,9 +440,18 @@ async function createControlPlane(options) {
 }
 function ensureAuthenticated(api) {
     if (!api.accessToken) {
-        throw new Error("This tool requires Thalovant API auth. Configure THALOVANT_ACCESS_TOKEN, THALOVANT_EMAIL/THALOVANT_PASSWORD, or per-principal Thalovant credentials for this MCP principal.");
+        throw new Error("This tool requires Thalovant API auth. Configure THALOVANT_API_TOKEN (recommended: a scoped, revocable API token), THALOVANT_ACCESS_TOKEN, THALOVANT_EMAIL/THALOVANT_PASSWORD, or per-principal Thalovant credentials for this MCP principal.");
     }
 }
+function controlPlaneAuthModeFromEnv() {
+    if (process.env.THALOVANT_API_TOKEN)
+        return "api-token";
+    if (process.env.THALOVANT_ACCESS_TOKEN)
+        return "access-token";
+    if (process.env.THALOVANT_EMAIL && process.env.THALOVANT_PASSWORD)
+        return "email-password";
+    return "none";
+}
 async function createRuntimeClient(options) {
     const protocol = options.protocol ?? "wss";
     const principal = currentPrincipal();
@@ -896,6 +906,8 @@ export function createServer() {
         },
     }, async () => jsonContent({
         apiUrl: process.env.THALOVANT_API_URL ?? DEFAULT_CONTROL_API_URL,
+        controlPlaneAuthMode: controlPlaneAuthModeFromEnv(),
+        hasApiToken: Boolean(process.env.THALOVANT_API_TOKEN),
         hasAccessToken: Boolean(process.env.THALOVANT_ACCESS_TOKEN),
         hasEmailPassword: Boolean(process.env.THALOVANT_EMAIL && process.env.THALOVANT_PASSWORD),
         profile: process.env.THALOVANT_PROFILE,

package/examples/claude_desktop_config.json

@@ -4,6 +4,7 @@
       "command": "node",
       "args": ["/absolute/path/to/thalovant-mcp/dist/index.js"],
       "env": {
+        "THALOVANT_API_TOKEN": "tvpat_...",
         "THALOVANT_PROFILE": "prod"
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thalovant/mcp-server",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Stdio and Streamable HTTP MCP server for Thalovant control-plane and hub runtime APIs.",
   "license": "MIT",
   "type": "module",

package/server.json

@@ -7,19 +7,19 @@
     "url": "https://github.com/thalovant/thalovant-mcp",
     "source": "github"
   },
-  "version": "0.1.8",
+  "version": "0.1.9",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@thalovant/mcp-server",
-      "version": "0.1.8",
+      "version": "0.1.9",
       "transport": {
         "type": "stdio"
       }
     },
     {
       "registryType": "oci",
-      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.1.8",
+      "identifier": "ghcr.io/thalovant/thalovant-mcp:0.1.9",
       "transport": {
         "type": "streamable-http",
         "url": "http://127.0.0.1:3000/mcp"