{
  "markdown": "# Thalovant MCP Server\n\nPublic-ready MCP server for Thalovant control-plane and hub runtime APIs.\n\nIt 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.\n\n## What It Includes\n\n- stdio transport for local agents.\n- Streamable HTTP transport at `/mcp` for remote agents.\n- OAuth-style protected resource metadata at `/.well-known/oauth-protected-resource`.\n- Static bearer tokens for simple/private deployments.\n- JWT/JWKS and OAuth token introspection for production remote deployments.\n- Per-principal Thalovant credentials and tool policy.\n- Host/origin validation, CORS, rate limiting, body limits, secure headers, and session binding.\n- Optional resumability event storage and JSONL audit logs.\n- Docker, Compose, Kubernetes, CI, npm package metadata, and MCP registry `server.json`.\n\n## Why TypeScript\n\nThalovant 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.\n\n## Install\n\n```bash\nnpm install\nnpm run build\n```\n\nNode.js 20 or newer is required.\n\n## Control-Plane Auth\n\nPublic 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.\n\nThe server selects control-plane auth in this order:\n\n1. `THALOVANT_API_TOKEN` — a scoped Thalovant API token. Recommended.\n2. `THALOVANT_ACCESS_TOKEN` — a pre-issued session access token.\n3. `THALOVANT_EMAIL` + `THALOVANT_PASSWORD` — interactive-account login fallback.\n\nWhen a token is set, the server never calls the login endpoint. `thalovant_config_status` reports the active mode as `controlPlaneAuthMode` without revealing token values.\n\n### API Tokens (Recommended For AI Agents And CI)\n\nScoped 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_`.\n\n```bash\nexport THALOVANT_API_TOKEN=\"tvpat_...\"\nexport THALOVANT_API_URL=\"https://api.thalovant.com\"\n\nnpm start\n```\n\nMinimum scopes for the full control-plane tool surface:\n\n| Scope | Used by |\n|-------|---------|\n| `hubs:read` | `thalovant_list_hubs`, `thalovant_get_hub`, `thalovant_get_analytics_overview`, `thalovant_list_marketplace_skills`, `thalovant_list_runtime_groups`, `thalovant_get_runtime_group`, `thalovant_get_runtime_group_config`, and the hub lookup inside `thalovant_create_client_identity` |\n| `hubs:inspect` | `thalovant_get_hub_runtime_capabilities`, `thalovant_list_runtime_group_marketplace`, `thalovant_list_runtime_group_inventory` |\n| `hubs:write` | All hub and runtime-group provisioning: `thalovant_create_hub`, `thalovant_update_hub`, `thalovant_release_hub`, `thalovant_create_runtime_group`, `thalovant_update_runtime_group`, `thalovant_update_runtime_group_config`, `thalovant_release_runtime_group`, `thalovant_install_runtime_group_skill`, `thalovant_uninstall_runtime_group_skill`, the hub rating tools, and the opt-in delete tools |\n| `clients:write` | `thalovant_create_client_identity` (`POST /v1/clients`) |\n| `memory:read` | `thalovant_list_memory_items`, `thalovant_get_memory_summary`, `thalovant_get_memory_item` |\n| `memory:write` | `thalovant_create_memory_item`, `thalovant_update_memory_item`, `thalovant_delete_memory_item` |\n\nThe hub scopes imply one another: `hubs:write` grants `hubs:read`, which grants `hubs:inspect` and `hubs:preview`. Minting a token with `hubs:read` is therefore enough for every discovery tool in the table above.\n\nScope is not the whole story for provisioning. Every hub and runtime-group write also requires a **paid plan**, and the API checks scope *before* the plan, so the two failure modes are ordered:\n\n- A token missing the scope fails `403 Insufficient scopes`. Free-plan API tokens are capped at `hubs:read`, `clients:read`, and `clients:write`, so on the free tier provisioning fails with this 403 and never reaches the 402.\n- A correctly scoped token on a free plan fails `402 API access requires a paid plan.`\n- `thalovant_install_runtime_group_skill` can fail with a **second, distinct** 402, `This skill requires paid marketplace access for the tenant plan.`, when the plan is paid but does not include `access_tier: paid` catalog entries.\n\nDiscovery is deliberately not paid-gated: **a free-tier token can browse the marketplace catalog and set hub ratings, but cannot install skills or provision hubs.** Use `thalovant_list_runtime_group_marketplace` before installing — it reports `installable`, `purchase_required`, and `access_message` per skill, which turns an opaque 402 into a decision you can make up front.\n\nGrant fewer scopes for narrower deployments: a read-only assistant needs only `hubs:read` and `memory:read`, and a discovery-only agent that browses skills but never provisions needs `hubs:read` alone. `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.\n\n### Hub Etags\n\n`thalovant_update_hub` and `thalovant_delete_hub` use optimistic locking and require the hub's current etag, sent as `If-Match`. The etag is only available in the **body** of the hub resource — the API sends no `ETag` response header — so an agent must call `thalovant_get_hub` first and pass the `etag` field from that response. A missing or stale value fails `412 ETag mismatch` and changes nothing; re-fetch and retry. `name`, `namespace`, and `domain` are immutable after creation, so `thalovant_update_hub` does not accept them at all; send only the fields you are changing rather than round-tripping a whole hub resource. Runtime-group writes do not use etags.\n\n### Login Fallback\n\n```bash\nexport THALOVANT_EMAIL=\"you@example.com\"\nexport THALOVANT_PASSWORD=\"...\"\n\nexport THALOVANT_PROFILE=\"prod\"\nexport THALOVANT_API_URL=\"https://api.thalovant.com\"\n\nnpm start\n```\n\nIf neither a token nor email/password is configured, authenticated control-plane tools fail with a clear error naming the supported options.\n\n## Local Stdio\n\nThe server speaks MCP over stdio and does not write logs to stdout.\n\nRuntime hub tools load local identities in this order:\n\n1. `identityFile` tool argument.\n2. `configPath` or `profile` tool argument.\n3. Thalovant SDK environment identity variables.\n4. The default Thalovant SDK config profile.\n\nKeep Thalovant identity files secret. The SDK expects protected config files such as `~/.config/thalovant/config.yaml` with mode `0600`.\n\n## Streamable HTTP\n\nRemote mode uses MCP Streamable HTTP at `/mcp` and requires bearer authentication by default.\n\n```bash\nexport MCP_TRANSPORT=\"http\"\nexport MCP_HTTP_HOST=\"127.0.0.1\"\nexport MCP_HTTP_PORT=\"3000\"\nexport MCP_HTTP_AUTH_TOKEN=\"$(openssl rand -hex 32)\"\nexport MCP_HTTP_ALLOWED_HOSTS=\"127.0.0.1:3000,localhost:3000\"\n\nnpm run start:http\n```\n\nClients connect to:\n\n```text\nhttp://127.0.0.1:3000/mcp\nAuthorization: Bearer <token>\n```\n\nHealth checks are available at `/healthz` and `/readyz`.\n\nFor public deployments, set the public URL and exact host/origin allowlists:\n\n```bash\nexport MCP_HTTP_HOST=\"0.0.0.0\"\nexport MCP_HTTP_PORT=\"3000\"\nexport MCP_PUBLIC_URL=\"https://mcp.example.com\"\nexport MCP_HTTP_ALLOWED_HOSTS=\"mcp.example.com\"\nexport MCP_HTTP_ALLOWED_ORIGINS=\"https://agent.example.com\"\n```\n\n## Remote Auth\n\nUse static bearer tokens only for local, private, or single-tenant deployments:\n\n```bash\nexport MCP_HTTP_AUTH_TOKEN=\"$(openssl rand -hex 32)\"\n# or\nexport MCP_HTTP_AUTH_TOKENS=\"token-a,token-b\"\n```\n\nUse JWT/JWKS for production resource-server validation:\n\n```bash\nexport MCP_HTTP_AUTH_MODE=\"jwt\"\nexport MCP_OAUTH_ISSUER=\"https://auth.example.com/\"\nexport MCP_OAUTH_JWKS_URL=\"https://auth.example.com/.well-known/jwks.json\"\nexport MCP_OAUTH_AUDIENCE=\"https://mcp.example.com/mcp\"\nexport MCP_OAUTH_AUTHORIZATION_SERVERS=\"https://auth.example.com/\"\nexport MCP_OAUTH_REQUIRED_SCOPES=\"mcp:thalovant\"\n```\n\nUse introspection when your authorization server issues opaque tokens:\n\n```bash\nexport MCP_HTTP_AUTH_MODE=\"introspection\"\nexport MCP_OAUTH_INTROSPECTION_URL=\"https://auth.example.com/oauth2/introspect\"\nexport MCP_OAUTH_CLIENT_ID=\"mcp-server-client\"\nexport MCP_OAUTH_CLIENT_SECRET=\"...\"\nexport MCP_OAUTH_AUDIENCE=\"https://mcp.example.com/mcp\"\nexport MCP_OAUTH_AUTHORIZATION_SERVERS=\"https://auth.example.com/\"\nexport MCP_OAUTH_REQUIRED_SCOPES=\"mcp:thalovant\"\n```\n\nThe server publishes protected resource metadata at:\n\n```text\nhttps://mcp.example.com/.well-known/oauth-protected-resource\n```\n\n401 responses include `WWW-Authenticate` with a `resource_metadata` pointer for MCP clients that support OAuth discovery.\n\n## Principal Credentials\n\nFor multi-user remote deployments, do not share one Thalovant access token across all MCP users. Map each authenticated MCP principal to its own Thalovant control-plane token, runtime identity, and tool policy.\n\nSingle file:\n\n```bash\nexport THALOVANT_PRINCIPAL_CREDENTIALS_FILE=\"/run/secrets/thalovant-principals.json\"\n```\n\nDirectory mode:\n\n```bash\nexport THALOVANT_PRINCIPAL_CREDENTIALS_DIR=\"/run/secrets/thalovant-principals\"\n```\n\nDirectory files are named `<sha256(principal-id)>.json`. The server checks the OAuth subject, principal id, and client id. See [examples/principal-credentials.sample.json](examples/principal-credentials.sample.json).\n\nKeep this disabled for multi-user deployments unless you intentionally want every remote principal to use the server environment's Thalovant credentials:\n\n```bash\nexport THALOVANT_ALLOW_SHARED_CREDENTIALS=\"false\"\n```\n\nRuntime `identityFile`, `configPath`, `profile`, and `fromEnv` tool arguments are disabled for remote principals by default. Set `MCP_HTTP_ALLOW_CLIENT_CREDENTIAL_PATHS=true` only for trusted private deployments.\n\n## Policy, Audit, And Resumability\n\nGlobal tool policy:\n\n```bash\nexport MCP_TOOL_ALLOWLIST=\"thalovant_*\"\nexport MCP_TOOL_DENYLIST=\"thalovant_delete_memory_item\"\n```\n\nPer-principal credential files may also include `allowedTools` and `deniedTools`.\n\nBoth are call-time filters, and an empty allowlist means \"allow everything\". They cannot make a tool default-off or hide it from `tools/list`, which is why the two destructive control-plane tools are gated separately by `THALOVANT_ENABLE_DESTRUCTIVE_TOOLS`. See [Destructive Tools](#destructive-tools).\n\nAudit logs:\n\n```bash\nexport MCP_AUDIT_LOG=\"stderr\" # off, stderr, file, or both\nexport MCP_AUDIT_LOG_FILE=\"/var/log/thalovant-mcp/audit.jsonl\"\nexport MCP_AUDIT_INCLUDE_ARGS=\"false\"\n```\n\nAudit entries are JSONL and credential-shaped fields are redacted.\n\nStreamable HTTP resumability defaults to an in-memory event store. Use a file-backed store for single-instance restarts:\n\n```bash\nexport MCP_EVENT_STORE_FILE=\"/var/lib/thalovant-mcp/events.jsonl\"\n```\n\n## HTTP Hardening\n\n- Bearer auth is required unless `MCP_HTTP_ALLOW_UNAUTHENTICATED=true` is explicitly set.\n- Host headers are allowlisted to reduce DNS rebinding risk.\n- Browser `Origin` headers are rejected unless they exactly match `MCP_HTTP_ALLOWED_ORIGINS`.\n- CORS exposes only MCP session/protocol headers.\n- Sessions use cryptographically random ids and are bound to the authenticated principal.\n- Request bodies are capped by `MCP_HTTP_MAX_BODY_BYTES`, defaulting to 1 MiB.\n- Fixed-window rate limiting defaults to 120 MCP requests per minute per client address.\n- Security headers include `nosniff`, `DENY` framing, no referrer, and a restrictive CSP.\n\nUseful HTTP environment variables:\n\n```bash\nMCP_HTTP_PATH=/mcp\nMCP_HTTP_RATE_LIMIT_MAX=120\nMCP_HTTP_RATE_LIMIT_WINDOW_MS=60000\nMCP_HTTP_SESSION_TTL_MS=3600000\nMCP_HTTP_MAX_BODY_BYTES=1048576\nMCP_HTTP_ENABLE_JSON_RESPONSE=false\nMCP_HTTP_TRUST_PROXY=false\n```\n\n## Claude Desktop\n\nRecommended: authenticate with a scoped API token so the MCP config never contains your account password.\n\n```json\n{\n  \"mcpServers\": {\n    \"thalovant\": {\n      \"command\": \"node\",\n      \"args\": [\"/home/goldyfruit/Development/Thalovant/mcp/dist/index.js\"],\n      \"env\": {\n        \"THALOVANT_API_TOKEN\": \"tvpat_...\",\n        \"THALOVANT_PROFILE\": \"prod\"\n      }\n    }\n  }\n}\n```\n\n## Codex\n\nUse the same stdio command in your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"thalovant\": {\n      \"command\": \"node\",\n      \"args\": [\"/home/goldyfruit/Development/Thalovant/mcp/dist/index.js\"],\n      \"env\": {\n        \"THALOVANT_API_TOKEN\": \"tvpat_...\",\n        \"THALOVANT_PROFILE\": \"prod\"\n      }\n    }\n  }\n}\n```\n\n## Tools\n\nRead-only:\n\n- `thalovant_config_status`\n- `thalovant_list_public_hubs`\n- `thalovant_get_public_hub`\n- `thalovant_list_hubs`\n- `thalovant_get_hub`\n- `thalovant_identity_status`\n- `thalovant_healthcheck`\n- `thalovant_wait_for_event`\n- `thalovant_get_analytics_overview`\n- `thalovant_list_memory_items`\n- `thalovant_get_memory_summary`\n- `thalovant_get_memory_item`\n\nSkill and runtime-group discovery (read-only):\n\n- `thalovant_list_marketplace_skills`\n- `thalovant_list_runtime_group_marketplace`\n- `thalovant_list_runtime_group_inventory`\n- `thalovant_list_runtime_groups`\n- `thalovant_get_runtime_group`\n- `thalovant_get_runtime_group_config`\n- `thalovant_get_hub_runtime_capabilities`\n\nWrites or hub events:\n\n- `thalovant_create_client_identity`\n- `thalovant_ask`\n- `thalovant_send_action`\n- `thalovant_send_code`\n- `thalovant_emit_event`\n- `thalovant_create_memory_item`\n- `thalovant_update_memory_item`\n- `thalovant_delete_memory_item`\n\nHub and runtime-group provisioning:\n\n- `thalovant_create_hub`\n- `thalovant_update_hub`\n- `thalovant_release_hub`\n- `thalovant_set_hub_rating`\n- `thalovant_clear_hub_rating`\n- `thalovant_create_runtime_group`\n- `thalovant_update_runtime_group`\n- `thalovant_update_runtime_group_config`\n- `thalovant_release_runtime_group`\n- `thalovant_install_runtime_group_skill`\n- `thalovant_uninstall_runtime_group_skill`\n\nDestructive, **not registered unless explicitly enabled** (see [Destructive Tools](#destructive-tools)):\n\n- `thalovant_delete_hub`\n- `thalovant_delete_runtime_group`\n\nTool outputs redact credential-shaped fields. `thalovant_create_client_identity` does not return secret identity material; pass `savePath` when you want the full identity written to a local file with mode `0600`. `savePath` is confined to the server's identity directory (`THALOVANT_MCP_IDENTITY_DIR`, default `<config-dir>/thalovant/identities`): pass a plain filename, since absolute paths outside that directory and `..` traversal are rejected, so a model cannot drop a credential file into a git working tree or synced folder. `thalovant_config_status` reports the active `identityDir`.\n\n## Destructive Tools\n\n`thalovant_delete_hub` and `thalovant_delete_runtime_group` are **disabled by default**. They are not merely blocked when called — they are never registered, so they do not appear in `tools/list` and a model cannot see or attempt them.\n\nA long-lived control-plane token combined with an always-available delete tool is a categorically different risk from a read or update tool: deleting a hub also deletes its dependent clients and ACLs, and none of it is reversible. So these two are opt-in:\n\n```bash\nexport THALOVANT_ENABLE_DESTRUCTIVE_TOOLS=\"true\"\n```\n\nAccepted true values are `1`, `true`, `yes`, and `on`; anything else, including unset, leaves the tools off. The flag is read when a server instance is created, so restart the server (or, in Streamable HTTP mode, start a new session) after changing it. `thalovant_config_status` reports the current state as `destructiveToolsEnabled` and lists the tools the flag controls.\n\nThis is a separate mechanism from the existing tool policy, deliberately. `MCP_TOOL_ALLOWLIST` / `MCP_TOOL_DENYLIST` and the per-principal `allowedTools` / `deniedTools` are call-time filters where an empty allowlist means \"allow everything\"; they cannot express a tool that is off until an operator turns it on, and they cannot hide a tool from `tools/list`. Once `THALOVANT_ENABLE_DESTRUCTIVE_TOOLS` is set the delete tools are ordinary tools again and remain subject to that policy, so the two layers compose:\n\n```bash\n# Enable deletes server-wide, but deny them to everyone except trusted principals.\nexport THALOVANT_ENABLE_DESTRUCTIVE_TOOLS=\"true\"\nexport MCP_TOOL_DENYLIST=\"thalovant_delete_hub,thalovant_delete_runtime_group\"\n```\n\nwith the trusted principal's credential file granting them back via `allowedTools`.\n\nDeleting a hub still requires a current etag (`412` otherwise), and deleting a runtime group fails with `409` while it is the workspace default or still has hubs attached.\n\n## Non-Catalog Skill Sources\n\n`thalovant_install_runtime_group_skill` installs from the vetted marketplace catalog by default. Any other source — notably `sourceType: \"git\"` with an arbitrary `sourceRef` repository URL — pulls code the marketplace never reviewed straight into a production runtime, and the control-plane validator is format-only with no host allowlist. Because the tools are driven by a model holding a long-lived token, non-catalog sources are refused unless an operator opts in:\n\n```bash\nexport THALOVANT_ENABLE_GIT_SKILL_SOURCES=\"true\"\n```\n\nWith the flag unset, a call with any `sourceType` other than `catalog` fails before any control-plane request is made. Accepted true values are `1`, `true`, `yes`, and `on`. `thalovant_config_status` reports the state as `gitSkillSourcesEnabled`. The tool is annotated `destructiveHint: true`.\n\n## Read-Only Mode\n\nSet `THALOVANT_MCP_READONLY=1` to register only tools annotated `readOnlyHint: true`. Write and destructive tools are then never registered and never appear in `tools/list`, so an operator can run an observe-only agent without hand-writing a denylist. Like the other registration-time gates it is read when a server instance is created; `thalovant_config_status` reports the state as `readOnly`.\n\n## Development\n\n```bash\nnpm run typecheck\nnpm test\nnpm run build\nnpm run test:smoke\nnpm run test:http\nnpm run bench\nnpm run bench:http\nnpm pack --dry-run\n```\n\n## License\n\nMIT. This is the right default for a public integration server: it is permissive, compatible with the MIT Thalovant Node SDK and MCP TypeScript SDK, and does not force downstream agent or enterprise users into a reciprocal licensing model.\n",
  "bytes": 18821,
  "sha": "e066ddc34f33773801886b5a65c6ed0857d62964348634f31fd1ae37b51b3237",
  "repo_slug": "thalovant/thalovant-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thalovant_thalovant_mcp_3ff44820/readme"
}