MCP Server

Use the Thalovant MCP server when an MCP client should discover hubs, provision hubs and runtime groups, create client identities, ask a hub, read analytics, or work with memory through Thalovant.

MCP means Model Context Protocol. It gives local agents and remote agent gateways a standard way to call Thalovant tools.

At A Glance

Item	Value
MCP registry name	io.github.thalovant/thalovant-mcp
npm package	@thalovant/mcp-server
current version	0.1.10
container image	ghcr.io/thalovant/thalovant-mcp:0.1.10
transports	stdio and Streamable HTTP
local path	best for Claude Desktop, Codex, Cursor, and desktop agents
remote path	best for hosted agent gateways and shared agent platforms
license	MIT

GitHubSource, examples, security notes, and release metadata.

Node SDKThe MCP server uses the Thalovant Node SDK under the hood.

Hub EndpointsUnderstand WSS, HTTPS, and MQTT hub traffic used by runtime tools.

Identity FilesStore hub credentials for runtime tools.

Choose A Transport

Transport	Use it when	Start command
stdio	The MCP client runs on the same machine as the server process.	npx --yes @thalovant/mcp-server --stdio
Streamable HTTP	Remote MCP clients connect over HTTP to /mcp.	docker run ghcr.io/thalovant/thalovant-mcp:0.1.10

Start with stdio for a personal agent. Use Streamable HTTP when the server is deployed behind your own auth, logs, and network controls.

Local Agent Setup

Public hub discovery works without Thalovant credentials. Private workspace tools and runtime tools need server-side Thalovant credentials.

Since version 0.1.9, a scoped API token in THALOVANT_API_TOKEN is the recommended way to authenticate the server, so the config never contains your account password. Create the token on the dashboard’s API Tokens page with these scopes for the full tool surface:

Scope	Tools that need it
hubs:read	Hub discovery, hub detail, the marketplace catalog, and runtime group reads.
hubs:inspect	Runtime group inventory, the group marketplace view, and hub runtime capabilities. Granted automatically by hubs:read.
hubs:write	Hub and runtime group provisioning tools. Paid plans.
clients:write	thalovant_create_client_identity.
memory:read	Memory list, summary, and item reads. Paid plans.
memory:write	Memory create, update, and delete. Paid plans.

A read-only assistant needs only hubs:read and memory:read. Tokens are scoped, revocable, and show their last use on the API Tokens page.

The hub scopes imply one another. hubs:write grants hubs:read, which grants hubs:inspect, so a token minted with hubs:read already covers every discovery tool.

Your plan decides which of these scopes you can grant. The Free plan covers the hub read and client scopes, so an agent on it can run the Discovery tools, browse the marketplace catalog, and call thalovant_create_client_identity. The memory scopes need a paid plan, so the Memory tools stay unavailable on the Free plan and fail with a scope error if the agent calls them. The Free plan also allows one active token at a time.

A Free-plan API token cannot carry hubs:write at all, so the Provisioning tools fail with a scope error rather than a plan error on that plan. See Provision Hubs.

The server’s Thalovant API calls count against your plan’s token rate limit and call quotas, so a busy agent can reach them. Over the limit, calls return HTTP 429 with a Retry-After header. The API Tokens page has the per-plan table and the matching error codes.

Use this shape in Claude Desktop, Codex, Cursor, or another stdio MCP host:

{
  "mcpServers": {
    "thalovant": {
      "command": "npx",
      "args": ["--yes", "@thalovant/mcp-server", "--stdio"],
      "env": {
        "THALOVANT_API_TOKEN": "tvpat_...",
        "THALOVANT_PROFILE": "prod",
        "THALOVANT_API_URL": "https://api.thalovant.com"
      }
    }
  }
}

The server tries THALOVANT_API_TOKEN first, then THALOVANT_ACCESS_TOKEN, then a THALOVANT_EMAIL and THALOVANT_PASSWORD login. With a token set, the server never calls the login endpoint. Per-principal credential files, when configured, win over every environment variable.

The thalovant_config_status tool reports which mode the environment declares in its controlPlaneAuthMode field: api-token, access-token, email-password, or none. Token values never appear in its output.

Caution

Do not paste Thalovant tokens, passwords, identity files, or setup links into chat. Configure them in the MCP server environment or in protected files.

Remote HTTP Setup

The container runs Streamable HTTP on port 3000 and serves MCP at /mcp.

docker run --rm \
  -p 127.0.0.1:3000:3000 \
  -e MCP_HTTP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  -e MCP_HTTP_ALLOWED_HOSTS="127.0.0.1:3000,localhost:3000" \
  ghcr.io/thalovant/thalovant-mcp:0.1.10

Clients connect to:

http://127.0.0.1:3000/mcp
Authorization: Bearer <token>

Health checks are available at /healthz and /readyz.

For a public endpoint, set exact public URL, host, and origin values:

export MCP_PUBLIC_URL="https://mcp.example.com"
export MCP_HTTP_ALLOWED_HOSTS="mcp.example.com"
export MCP_HTTP_ALLOWED_ORIGINS="https://agent.example.com"

Auth And Credentials

1. Keep bearer auth on. HTTP mode requires MCP_HTTP_AUTH_TOKEN or MCP_HTTP_AUTH_TOKENS by default.
2. Use OAuth validation for shared remote servers. Set MCP_HTTP_AUTH_MODE=jwt with JWKS, or use MCP_HTTP_AUTH_MODE=introspection for opaque tokens.
3. Map users to Thalovant credentials. Use THALOVANT_PRINCIPAL_CREDENTIALS_FILE or THALOVANT_PRINCIPAL_CREDENTIALS_DIR.
4. Disable shared credentials for multi-user servers. Keep THALOVANT_ALLOW_SHARED_CREDENTIALS=false.
5. Set tool policy. Use MCP_TOOL_ALLOWLIST and MCP_TOOL_DENYLIST for server-wide controls.
6. Send audit logs somewhere durable. Use MCP_AUDIT_LOG=stderr, MCP_AUDIT_LOG_FILE, or both.

The server publishes OAuth protected resource metadata at:

https://mcp.example.com/.well-known/oauth-protected-resource

Tool Groups

Discovery

thalovant_config_status, thalovant_list_public_hubs, thalovant_get_public_hub, thalovant_list_hubs, and thalovant_get_hub.

Runtime

thalovant_identity_status, thalovant_healthcheck, thalovant_ask, thalovant_send_action, thalovant_send_code, thalovant_emit_event, and thalovant_wait_for_event.

Memory

thalovant_list_memory_items, thalovant_get_memory_summary, thalovant_get_memory_item, thalovant_create_memory_item, thalovant_update_memory_item, and thalovant_delete_memory_item.

Workspace

thalovant_create_client_identity and thalovant_get_analytics_overview.

Skill discovery

thalovant_list_marketplace_skills, thalovant_list_runtime_group_marketplace, thalovant_list_runtime_group_inventory, thalovant_list_runtime_groups, thalovant_get_runtime_group, thalovant_get_runtime_group_config, and thalovant_get_hub_runtime_capabilities.

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, and thalovant_uninstall_runtime_group_skill.

Ratings

thalovant_set_hub_rating and thalovant_clear_hub_rating. These need hubs:write but no paid plan.

thalovant_create_client_identity does not return secret identity material in chat output. Use savePath when you want the full identity written to a local file with mode 0600. The path is resolved inside THALOVANT_MCP_IDENTITY_DIR (a safe config directory by default); a savePath that is absolute outside that base, or uses .. to escape it, is rejected before any credential is created.

Version 0.1.10 added the Skill discovery and Provisioning groups, plus the two opt-in delete tools below. Discovery is read-only and works on any plan. Provisioning needs hubs:write and a paid plan. For the full flow, the etag rule, and the error table, see Provision Hubs.

thalovant_update_hub requires the hub’s current etag as an input and does not accept name, namespace, or domain, because those are fixed at creation. Call thalovant_get_hub first and pass the etag field from its response body.

Destructive Tools

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 never appear in the tool list and a model cannot see or attempt them.

Deleting a hub also deletes its dependent clients and ACLs, and none of it is reversible. A long-lived control-plane token paired with an always-visible delete tool is a different class of risk from a read or update tool, so these two are opt-in.

To turn them on, set the environment variable before the server starts:

export THALOVANT_ENABLE_DESTRUCTIVE_TOOLS="true"

Rule	Value
Accepted true values	1, true, yes, and on, in any letter case.
Anything else	Leaves the tools off, including unset, empty, 0, and false.
When it is read	At server start. Restart the server, or start a new session in Streamable HTTP mode, after changing it.
How to confirm	thalovant_config_status reports destructiveToolsEnabled and lists the tools the flag controls.

This is deliberately separate from MCP_TOOL_ALLOWLIST and MCP_TOOL_DENYLIST. Those are call-time filters where an empty allowlist means “allow everything”, so they cannot express a tool that stays off until someone turns it on, and they cannot hide a tool from the tool list. Once the flag is set, the delete tools become ordinary tools again and the policy still applies, so the two layers compose:

# Enable deletes server-wide, then deny them to everyone except trusted principals.
export THALOVANT_ENABLE_DESTRUCTIVE_TOOLS="true"
export MCP_TOOL_DENYLIST="thalovant_delete_hub,thalovant_delete_runtime_group"

Deleting a hub still needs a current etag, and fails with HTTP 412 without one. Deleting a runtime group fails with HTTP 409 while it is the workspace default or still has hubs attached.

Caution

Leave these tools off unless an agent has a real reason to delete Thalovant resources. Deleting a hub cannot be undone.

Restricting Sources And Tools

Since version 0.1.11, three more environment variables narrow what the server will do, on top of the destructive-tool gate above. Like that gate, each is read at server start and reported by thalovant_config_status.

Non-catalog skill sources are off by default. thalovant_install_runtime_group_skill installs from the reviewed marketplace catalog. A git or URL source runs code the catalog never reviewed, so those sources are rejected unless you opt in:

export THALOVANT_ENABLE_GIT_SKILL_SOURCES="true"

With the flag unset, a non-catalog sourceType fails with a clear client-side error that names the variable, and no control-plane call is made. thalovant_config_status reports gitSkillSourcesEnabled.

Identity files stay inside one directory. When thalovant_create_client_identity writes to savePath, the path is confined to THALOVANT_MCP_IDENTITY_DIR, so an agent cannot drop a credential file into an arbitrary location such as a synced folder or a git working tree. thalovant_config_status reports identityDir.

Read-only mode hides every write tool. Set THALOVANT_MCP_READONLY="true" to register only the tools marked read-only — Discovery, Memory reads, status, and config — and leave out every create, update, install, release, rating, and client-identity tool. It is a one-switch way to hand an agent a safe surface without hand-writing a denylist. thalovant_config_status reports readOnly.

Tool Input Rules

Since version 0.1.8, the server validates tool inputs against the same bounds the Thalovant API enforces, so bad values fail with a clear client-side error instead of an opaque API 422.

Rule	Value
thalovant_list_public_hubs page size	Capped at 48, matching the public hubs endpoint. Authenticated thalovant_list_hubs keeps its limit of 100.
Hub references on authenticated tools	thalovant_get_hub and thalovant_create_client_identity require the hub UUID. Slugs are only accepted by the public hub tools, such as thalovant_get_public_hub.
Memory title	160 characters or fewer.
Memory content	4096 characters or fewer.
Memory source	64 characters or fewer.
Memory consentScope	128 characters or fewer.
Memory consentVersion	64 characters or fewer.
Memory retentionPolicy	64 characters or fewer.
Memory list query	240 characters or fewer.

Common Issues

Symptom	Check first
Claude or Codex cannot start the server	Confirm Node.js 20 or newer is installed and the command uses npx --yes @thalovant/mcp-server --stdio.
Public hub tools work but private tools fail	Configure THALOVANT_API_TOKEN, a protected SDK profile, or per-principal credentials, then check thalovant_config_status.
A tool fails with a scope error	Recreate the token on the API Tokens page with the scopes the tool group needs.
Memory tools fail on the Free plan	The memory scopes need a paid plan. Upgrade, or run the agent with the Discovery and client tools only.
Provisioning tools fail with HTTP 403 on the Free plan	Free-plan tokens cannot carry hubs:write, so the scope check fails before the plan check. Upgrade, then mint a token with hubs:write.
thalovant_install_runtime_group_skill returns HTTP 402 on a paid plan	The skill is a paid catalog entry the plan does not cover. Call thalovant_list_runtime_group_marketplace first and check installable and purchase_required.
thalovant_update_hub returns HTTP 412	The etag is missing or stale. Call thalovant_get_hub again and pass the etag from its response body.
The delete tools are missing from the tool list	They are opt-in. Set THALOVANT_ENABLE_DESTRUCTIVE_TOOLS and restart the server. See Destructive Tools.
Calls return HTTP 429	The token reached its plan’s rate limit or call quota. Wait for the Retry-After interval, then retry.
HTTP returns 401	Send Authorization: Bearer <token> and confirm the token matches the server config.
HTTP returns 403 for a browser client	Add the exact origin to MCP_HTTP_ALLOWED_ORIGINS.
Remote users see the same Thalovant data	Configure per-principal credentials and keep shared credentials disabled.
A risky tool should not be available	Add it to MCP_TOOL_DENYLIST, or use a per-principal deniedTools policy.

Next

Use SDK Functions when you want the underlying Thalovant SDK method names. Use Provision Hubs when an agent should create hubs and runtime groups. Use Identity Files when runtime tools need saved hub credentials.

Last reviewed: August 15, 2026. Review this page when the MCP package name, registry metadata, tool list, tool input bounds, auth defaults, API token scope guidance, destructive tool gating, transport behavior, or container image changes.