MCP Server

Use the Thalovant MCP server when an MCP client should discover hubs, 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.5
container image	ghcr.io/thalovant/thalovant-mcp:0.1.5
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.5

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.

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_PROFILE": "prod",
        "THALOVANT_API_URL": "https://api.thalovant.com"
      }
    }
  }
}

You can also use an access token in the server environment:

export THALOVANT_ACCESS_TOKEN="replace-with-a-secret"
npx --yes @thalovant/mcp-server --stdio

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.5

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.

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.

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_ACCESS_TOKEN, a protected SDK profile, or per-principal credentials.
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 Identity Files when runtime tools need saved hub credentials.

Last reviewed: July 7, 2026. Review this page when the MCP package name, registry metadata, tool list, auth defaults, transport behavior, or container image changes.