Thorbit MCP

The canonical Thorbit MCP install surface: one local stdio server exposing the exact customer-safe union of all registered specialist product families, including Foundation.

| Family | Tools | What it covers | | --- | ---: | --- | | Account | 18 | Credits, private Library writes and versions, files, chats, projects, billing, and organization members | | Content and On-page | 22 | Research, writing and optimization pipelines, analysis, briefs, strategies, and reviewed edits | | Deposition | 6 | Positioning research, vulnerabilities, category strategy, playbooks, and artifacts | | Google Analytics | 9 | Native GA4 property discovery, persisted reports, acquisition, landing pages, conversions, and realtime reads | | ICP | 6 | Ideal-customer-profile runs, results, search, and artifacts | | Knowledge Base | 9 | Libraries, ingestion, source status, retrieval, and grounded answers | | Knowledge Graph | 10 | Entity libraries, entity resolution, approval, and schema.org output | | Money Keyword Research and Pages | 8 | Durable commercial-keyword research, priority targets, and Neon-backed page drafts | | Search Console | 7 | Native database-backed properties, performance, opportunities, declines, indexation, linkage, and sync | | Topic Map and Expansion | 8 | Topical architecture runs plus independently callable expansion, maps, search, and artifacts |

The package is a thin authenticated client over hosted Thorbit. Phoenix and Mastra continue to own workflows, persistence, metering, and provider calls; this package does not duplicate that business logic locally.

Quick start with NPX

Generate a unified API key in Thorbit Settings -> MCPs, then run the installer for your client:

npx -y thorbit-mcp@latest install --client codex

The installer prompts for the key without echoing it, stores it at ~/.config/thorbit/mcp-key with 0600 permissions, and configures one server named thorbit. Restart the MCP client after installation.

Supported installer targets:

npx -y thorbit-mcp@latest install --client codex
npx -y thorbit-mcp@latest install --client claude-desktop
npx -y thorbit-mcp@latest install --client cursor
npx -y thorbit-mcp@latest install --client json
npx -y thorbit-mcp@latest install --client json --copy

Use --dry-run to inspect the generated configuration without writing a key or client file:

npx -y thorbit-mcp@latest install --client json --dry-run --no-color

Install with NPM

npm install --global thorbit-mcp
thorbit-mcp install --client codex

The installed thorbit-mcp command is also the unified stdio runtime. With no subcommand, it starts the complete registered tool inventory:

THORBIT_MCP_KEY_PATH="$HOME/.config/thorbit/mcp-key" thorbit-mcp

Node.js 20 or newer is required.

Manual MCP configuration

For clients that accept MCP JSON, configure the unified package directly:

{
  "mcpServers": {
    "thorbit": {
      "command": "npx",
      "args": ["-y", "thorbit-mcp@latest"],
      "env": {
        "THORBIT_MCP_KEY_PATH": "/absolute/path/to/.config/thorbit/mcp-key",
        "THORBIT_BASE_URL": "https://thorbit.ai"
      }
    }
  }
}

Use an absolute key-file path in client configuration. Avoid putting a raw API key in a committed file or command history.

Unified by default; specialists remain available

The default installer creates one thorbit server. This is the recommended surface and avoids duplicate tool names.

For an intentionally smaller or independently managed setup, install every specialist server instead:

npx -y thorbit-mcp@latest install --client codex --specialists

Specialist mode configures:

• thorbit-account-mcp
• thorbit-content-mcp
• thorbit-deposition-mcp
• thorbit-google-analytics-mcp
• thorbit-icp-mcp
• thorbit-kb-mcp
• thorbit-knowledge-graph-mcp
• thorbit-money-kw-mcp
• thorbit-search-console-mcp
• thorbit-topic-map-mcp

Do not enable unified and specialist servers in the same client context unless duplicate canonical tool names are intentional.

OAuth

The canonical hosted OAuth transport is:

https://thorbit.ai/api/v1/mcp-oauth/thorbit/transport

Add that URL as a remote MCP connector and complete browser authorization. The unified connector exposes the same accepted tool inventory without running a local package. Specialist OAuth transports remain available for deliberately narrower grants.

OAuth authorization, tool discovery, and tool execution are separate checks. After connecting, open a fresh client conversation, confirm the Thorbit tools are visible, and run a harmless authenticated read.

API-key runtime environment

The stdio runtime accepts exactly one key source:

• THORBIT_API_KEY or THORBIT_MCP_API_KEY for an inline key.
• THORBIT_MCP_KEY_PATH for a file containing the key.

Optional runtime settings:

• THORBIT_BASE_URL: hosted Thorbit URL; defaults to https://thorbit.ai.
• THORBIT_MCP_TIMEOUT_MS: request timeout from 1,000 to 300,000 milliseconds; defaults to 120,000.

If both an inline key and THORBIT_MCP_KEY_PATH are present, the runtime stops with a configuration error rather than guessing.

Installer behavior and paths

The installer preserves unrelated client configuration and replaces only Thorbit-managed entries.

| Client | Default configuration path | | --- | --- | | Codex | ~/.codex/config.toml | | Claude Desktop on macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Cursor | ~/.cursor/mcp.json | | JSON | Printed to stdout; no client file is written |

Use --config-path for a nonstandard location. Existing key files are reused; pass --force only when intentionally replacing one.

Installer options

--client <target>               codex, claude-desktop, claude, cursor, or json
--api-key <key>                 API key; omitted keys are prompted for securely
--key-path <path>               default: ~/.config/thorbit/mcp-key
--base-url <url>                default: https://thorbit.ai
--config-path <path>            override the client configuration path
--specialists                   install every specialist server instead of unified Thorbit
--server-name <name>            unified server name; default: thorbit
--account-server-name <name>    default: thorbit-account
--content-server-name <name>    default: thorbit-content
--deposition-server-name <name> default: thorbit-deposition
--google-analytics-server-name <name> default: thorbit-google-analytics
--icp-server-name <name>        default: thorbit-icp
--kb-server-name <name>         default: thorbit-kb
--knowledge-graph-server-name <name> default: thorbit-knowledge-graph
--money-kw-server-name <name>   default: thorbit-money-kw
--search-console-server-name <name> default: thorbit-search-console
--topic-map-server-name <name>  default: thorbit-topic-map
--copy                          copy JSON output with --client json
--dry-run                       print the intended change without writing it
--force                         replace an existing key file
--no-color                      disable ANSI color
--help                          show current help

For authoritative current flags:

npx -y thorbit-mcp@latest help --no-color

MCPB and SDK surfaces

• Desktop bundle: https://thorbit.ai/downloads/thorbit-mcp/thorbit-mcp-latest.mcpb
• Public Node SDK, Python SDK, CLI, cURL examples, and generated contract: VilovietaSEO/thorbit-sdk

All surfaces are generated or verified against the same accepted canonical tool contract.

Verification

After installing or connecting:

1. Restart or reconnect the MCP client.
2. Confirm there is one intended provider for canonical Thorbit tool names.
3. Confirm tools from multiple families are visible, such as thorbit_account_credits_get_balance, thorbit_kb_list, kg_get, and thorbit_topic_map_list.
4. Run a harmless list/read tool and confirm a structured result with a request ID.

Durable start tools return a poll target. Follow the returned next tool rather than starting a duplicate run.