Thalovant MCP

Send one text request to a Thalovant hub using a saved identity and return the normalized reply.

Start a device sign-in (RFC 8628) when no API token is configured: a person approves it in a browser. Show the person verificationUri and userCode (or verificationUriComplete, which carries the code), then call thalovant_poll_device_login with loginId every `interval` seconds. The device code stays on this server. Once approved, control-plane tools for this principal use the token it minted. A Home Assistant link asks for hubs:read, clients:read and clients:write, which is also all a Free plan can approve, and signs in as the registered app thalovant-home-assistant (clientId).

Remove the caller's own rating from a public Thalovant hub and return the hub. This clears only the caller's rating, not the hub. Requires the hubs:write scope; no paid plan is needed.

Inspect local Thalovant MCP configuration without revealing secret values.

Create a Thalovant client identity (a hub connection) for a hub. The identity is secret; output is redacted unless savePath is used. Pass connectionType (for example home_assistant) for a connection of that kind: the API must answer with the same kind, or the connection it made instead is deleted and the call fails. A new connection is admitted by its hub in about ninety seconds; follow operationId with thalovant_wait_for_admission before connecting.

Create a Thalovant hub. Requires the hubs:write scope AND a paid plan: a token without the scope fails 403, and because the scope is checked before the plan, granting the scope can then surface a 402 'API access requires a paid plan'. The create is idempotent — the SDK sends an Idempotency-Key, so a retried create returns the first hub rather than making a second one; reusing a key with a DIFFERENT body fails 409.

Create an explicit Thalovant memory item.

Create a Thalovant runtime group — the unit that hosts hubs and holds installed skills. Requires the hubs:write scope and a paid plan. Unlike the hub write routes this one takes no etag.

Delete one Thalovant memory item.

Emit a raw Thalovant event to a hub. Use only when a more specific runtime tool is not enough.

Read authenticated Thalovant analytics overview data.

Fetch one chat app bridge (GET /v1/bridges/{id}) with the same fields as thalovant_list_bridges: status.reason, phase, ready, applied and summary (the status in plain words), hold, the chats it answers in, and the etag the write tools accept. The platform's own diagnostic message is never included. Requires the hubs:read scope. Reads only.

Show which chat networks are offered and the plan's chat-app allowance (GET /v1/bridges/networks): networks (network, name, status offered or beta, offered) and allowance (plan, paid_plan, limit, used: bridges set up or running, remaining, can_create: whether a new bridge would pass the plan checks, saying nothing about a token). Free plans get 0. With hubId the allowance is the hub owner's, since bridges count against the owner; otherwise the caller's. summary says it in words. Read it before suggesting a new chat app or resuming one the plan paused. Requires the hubs:read scope. Reads only.

Fetch one authenticated Thalovant hub by UUID.

Read the live skill and intent inventory a hub runtime exposes. Requires the hubs:inspect scope. The API answers HTTP 409 when the hub has no connected client that can report inventory — for a group-level view that returns an empty list instead of failing, use thalovant_list_runtime_group_inventory.

Read one authenticated Thalovant memory item.

Read authenticated Thalovant memory summary data.

Read the status of an asynchronous control-plane operation returned by provisioning.

Fetch one public Thalovant hub by id or slug.

Fetch one Thalovant runtime group. Requires the hubs:read scope.

Read a Thalovant runtime group's runtime configuration and personas. Requires the hubs:read scope. The revision returned by this call is used by safe configuration merges.

Connect to a Thalovant hub with a saved identity and return runtime transport health.

Load a Thalovant identity and return redacted protocol and endpoint status.

Install a skill on the runtime group attached to a Thalovant hub. All hubs sharing that runtime group are affected. The change applies live on the hub in about 15 seconds, with no hub restart; a hub may start with no skills and gain them one at a time. Discover the skill name with thalovant_list_marketplace_skills. The API answers 202 with an operation_id and state "installing": pass wait: true to poll the operation until it converges (state "installed", or an error carrying the operation's failure message), with a 120 s default timeout; otherwise follow it with thalovant_get_operation. The 202 body also carries hub_id, runtime_group_id and previous_version. Installing a skill that is already installed at ANOTHER version performs an update; the SAME version fails 409 with code skill_version_already_installed. Fails 404 with code hub_without_runtime_group when the hub has no runtime group attached yet, and 422 when "latest" cannot be resolved or the version string is invalid. hubId must be the hub UUID — the authenticated hub routes reject slugs. Requires the hubs:write scope and a paid plan; scope is checked before plan, so a free-plan token sees 403, never 402. A hub-restricted token must cover every hub sharing the affected runtime group.

Install (or re-install) a skill in a Thalovant runtime group from the marketplace catalog. Installing a skill that is already present updates the existing entry rather than failing. Discover skillId with thalovant_list_marketplace_skills, then confirm installable/purchase_required with thalovant_list_runtime_group_marketplace before calling this. Requires the hubs:write scope and a paid plan (402 'API access requires a paid plan'); a paid marketplace skill ALSO needs marketplace access on the tenant plan, which fails with a second, distinct 402 about paid marketplace access. Only catalog sources are allowed by default: installing from a non-catalog source such as sourceType "git" runs code the marketplace never vetted and is refused unless the operator sets THALOVANT_ENABLE_GIT_SKILL_SOURCES.

Discover a hub's registered intents, language examples and fallback skills using its runtime identity. listed_in names, per requested language, the hub language the sentences were listed in: a hub lists nothing under a language it did not load, so a language with no sentences is listed in its usual form or the closest language the hub loaded. When listed_in differs from the language asked, tell the user which language the sentences are in. Fallback skills come from ovos.skills.list in skill id order; the hub does not say in which order they are tried, so priority is null. Unknown fallback support remains distinct from a known empty list; answerability is a conservative hint.

List the chats, channels or rooms a bridge's bot can see (GET /v1/bridges/{id}/chats), to choose from for allowed in thalovant_update_bridge. Each row has id, title, kind, the Discord server (guild_id, guild_name), allowed (it already answers there), and selectable (false for an encrypted room it cannot read). manual_entry true means this chat app cannot list its chats: type the ids instead, matching targets.pattern from thalovant_list_chat_app_connectors. Telegram lists only chats that wrote to the bot in the last 24 hours, and only while the bridge is paused (409 bridge_running otherwise): pause it with thalovant_pause_bridge, send /start@<bot username> in the new group, list, choose with thalovant_update_bridge, then resume. Listing is rate-limited per bridge. It changes nothing, but because it asks the chat network on the bot's behalf it needs the hubs:write scope, a paid plan, and the hub's owner or a workspace manager (403 for a hubs:read token, 402 on a plan without chat apps); THALOVANT_MCP_READONLY leaves it out.

List chat app bridges (GET /v1/bridges): one hub's with hubId, otherwise every bridge the token may see (its own, and those of workspaces where it is a member above basic); ownerId narrows that to one owner. Each bridge has its network and connector, state (setup or active), the chats it answers in (allowed), require_mention, session_scope, paused, hold (why the platform paused it: plan_limit or account_suspended; null for the owner's own pause), the bot, its invite links, secrets_set (which secrets are stored, by name), its etag, and status: reason (Setup, Starting, Connected, Paused, Unavailable, TokenMissing, TokenRejected), phase, ready, applied (whether the latest change has reached the bridge) and summary, the status in plain words. The platform's own diagnostic message is never included. Requires the hubs:read scope. Reads only.

List the chat apps a hub can answer in (GET /v1/bridges/connectors): Telegram and Discord, and Matrix, Mattermost or Twitch when they are listed. Each has status (offered, or beta), offered (whether a bridge can be created for it now), its description and setup steps in the language asked (English where there is no French), the secrets the console asks for (key, label, required: names only, never a value), the settings form, what a chat id looks like (targets: label, pattern, max, lowercase, strip_prefix), require_mention_fixed, the session scopes, and its helpers: with discover, thalovant_list_bridge_chats lists the chats (otherwise ids are typed); with test_message, thalovant_send_bridge_test_message works. Creating a bridge, and pasting or replacing its token or secrets, happen only in the Thalovant console (Connections > Add connection > Chat apps, or the hub's Chat apps tab): no tool takes a token or secret. Requires the hubs:read scope. Reads only.

Read newest-first skill events and operations for the runtime group attached to a hub. This history is shared by all hubs using that runtime. Requires hubs:inspect (hubs:read implies it); restricted tokens must cover all served hubs. Returns event/operation kind, timestamps, versions, actors and outcome fields. No changes are made.

List the skills installed on the runtime group attached to a Thalovant hub. Returns the whole envelope: hub_id, runtime_group_id, observed_at, source, the runtime's phase and message, and data — one row per skill with version, version_pin, installed_version, observed_version, previous_version, latest_version, available_version, update_available, changelog, active, state (pending, installed, failed, removing, drifted, quarantined, unmanaged; a change in progress shows as pending), the runtime's last error and last_transition_at. The hub UUID selects its attached runtime group. Skills and changes are shared by every hub using that group; restricted tokens must cover all served hubs. hubId must be the hub UUID — the authenticated hub routes reject slugs; a hub with no runtime group attached fails 404 with code hub_without_runtime_group. Requires the hubs:inspect scope (hubs:read implies it); hub-restricted tokens only see the hubs in their allowlist.

List authenticated Thalovant hubs visible to the account.

Browse the Thalovant marketplace skill catalog. Start here when discovering what a hub could run: each entry carries the fields an install needs (skill_id, source_type, source_ref, package_name, version compatibility, config_schema, secret_schema) plus category, tags, verified, access_tier, and billing_sku. Requires the hubs:read scope and is NOT paid-gated, so a free-tier token can browse the catalog even though it cannot install from it. The response is not paginated — the whole catalog comes back at once.

List authenticated Thalovant memory items.

List Thalovant public hubs. This read-only discovery call does not require authentication. Page size is capped at 48.

List the skills a runtime group is actually observed running right now. Where thalovant_list_runtime_group_marketplace answers 'what could be installed here', this answers 'what is loaded'. Each entry carries skill_id, version, source, active, adapt_intents, padatious_intents, total_intents, and observed_at; the envelope reports source (ovos-runtime-operator, runtime-group-cache, or ovos-runtime-operator-pending), operator_phase, and operator_message. Unlike thalovant_get_hub_runtime_capabilities this never fails with 409 when nothing is reporting — it returns an empty list with a pending source. Requires the hubs:inspect scope; no paid plan needed.

List the marketplace catalog resolved against one runtime group. This is the view to read immediately before installing: every catalog entry comes back with the group's own state folded in — whether the skill is desired (active, version_pin, source_type), whether it was observed running (observed_source, observed_at, intent counts), operator status, and the plan verdict (purchase_required, installable, access_message). Check installable and purchase_required here to avoid a 402 at install time. Requires the hubs:inspect scope; browsing needs no paid plan. Answers 404 for an unknown group and 403 when the caller does not own it.

List the Thalovant runtime groups visible to the authenticated account. Requires the hubs:read scope. The response is not paginated — every visible group is returned at once.

Pause a chat app bridge (PATCH /v1/bridges/{id} with paused: true): it stops answering in every chat until resumed, and keeps its chats, settings and token. Always allowed, whatever the plan. Returns the bridge; status.reason turns Paused once the bridge has stopped. Requires the hubs:write scope, and the hub's owner or a workspace manager.

Ask once whether the person approved a device sign-in started with thalovant_begin_device_login. outcome is pending (poll again after `interval` seconds, already lengthened if the API asked to slow down), approved (control-plane tools for this principal now use the token; tokenId, scopes and expiresAt describe it), expired or denied (begin a new sign-in). The token itself is never returned.

Send a routed HiveMind query using a saved identity and return the normalized reply. The hub may cascade the query according to its routing policy; a query can trigger actions.

Apply a release policy to a hub and return the updated hub. Every option is optional; omitted fields fall back to the workspace release policy. Passing images switches the hub to custom mode unless mode is also set; non-admins may pass only images the platform releases (see images). Requires the hubs:write scope and a paid plan. No etag is needed.

Apply a runtime image policy to a Thalovant runtime group and return the updated group. Options behave like thalovant_release_hub: everything is optional, omitted fields fall back to the workspace release policy, and passing images switches to custom mode unless mode is also set (non-admins: only images the platform releases, see images). Requires the hubs:write scope and a paid plan.

Remove one skill from the runtime group attached to a Thalovant hub. Every hub sharing the runtime loses this skill; other skill attachments are unchanged, and the change applies live on the hub in about 15 seconds with no hub restart. The API answers 202 with an operation_id, hub_id, runtime_group_id, previous_version (version is null) and state "removing": pass wait: true to poll the operation until it converges (state "removed", or an error carrying the operation's failure message), with a 120 s default timeout; otherwise follow it with thalovant_get_operation. Fails 404 when the skill is not installed on the hub (code hub_without_runtime_group when the hub has no runtime group). hubId must be the hub UUID — the authenticated hub routes reject slugs. Requires the hubs:write scope and a paid plan; scope is checked before plan, so a free-plan token sees 403, never 402. A hub-restricted token must cover every hub sharing the affected runtime group.

Resume a paused chat app bridge (PATCH /v1/bridges/{id} with paused: false). Needs a paid plan with room for one more running bridge: 402 on a plan without chat apps, 403 plan_limit when its running bridges are already at the limit (thalovant_get_bridge_networks shows the allowance). A bridge paused because the account was deactivated (hold account_suspended) resumes when the account is reactivated. A bridge with no chats yet (status Setup) starts only once thalovant_update_bridge sets allowed. Returns the bridge; status.reason turns Connected once it runs. Requires the hubs:write scope, and the hub's owner or a workspace manager.

Sign out: revoke the API token this principal signed in with through thalovant_poll_device_login, and stop using it. A token may always revoke itself, and one already revoked counts as revoked; signing out again answers alreadyRevoked without a request. Tokens configured on the server are never touched.

Send one action to a Thalovant hub using a saved identity, the way a button or a shortcut would. The hub routes payload like a spoken request, so the skill that takes it can change things: switch a light, start a timer, play music. Returns once the action is sent, without waiting for the reply; use thalovant_ask to read the answer. THALOVANT_MCP_READONLY leaves this tool out.

Post a short "Connected to <hub>." message, in the hub's language, in one of a chat app bridge's allowed chats (POST /v1/bridges/{id}/test). Everyone in that chat sees it. chatId must be in the bridge's allowed list (422 bridge_chat_not_allowed otherwise). Only chat apps with the test_message helper have one (Telegram and Discord; 409 bridge_helper_unavailable otherwise: mention the bot in the chat instead). A few test messages an hour per bridge; past that, 429 says how long to wait. Needs a paid plan. Requires the hubs:write scope, and the hub's owner or a workspace manager.

Send one exact value to a Thalovant hub using a saved identity: something typed, scanned, a barcode, a QR code or a serial number. The hub receives it as an utterance whose input is marked exact, and a skill that recognizes the value may act on it. Returns once the value is sent, without waiting for a reply. THALOVANT_MCP_READONLY leaves this tool out.

Rate a public Thalovant hub from 1 to 5 and return the updated hub. Requires the hubs:write scope; no paid plan is needed, so free-tier tokens can rate. Rating a non-public hub fails 400 "Only public hubs can be rated." and rating your own hub fails 400 "Hub owners cannot rate their own public hubs."