Thorbit Deposition MCP

Specialist MCP server for Thorbit's durable Depositioning strategy pipeline. It exposes six focused tools for positioning research, run status, playbooks, artifacts, history, and search.

This package is a thin stdio client. Hosted Thorbit owns authentication, organization isolation, metering, persistence, competitor and customer research, and the durable Phoenix/Mastra workflow. Use the unified thorbit-mcp package when one 82-tool Thorbit server is preferable.

Install and run

Generate a Thorbit MCP API key with deposition:read and deposition:run scopes in Thorbit Settings -> MCPs, then run:

npx -y thorbit-deposition-mcp@latest

Node.js 20 or newer is required.

MCP client configuration with a key file:

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

Prefer a key file to putting a raw key in a committed client configuration. The package also reads ~/.thorbit-deposition-mcp-key when no explicit key-file path is set.

The unified installer can configure this package together with the other seven specialists:

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

OAuth

For a remote specialist connector, use:

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

The unified OAuth transport is recommended when the client should have the complete Thorbit tool surface.

Authentication and environment

The stdio server accepts these key sources, in order:

• THORBIT_API_KEY
• THORBIT_MCP_API_KEY
• THORBIT_DEPOSITION_MCP_API_KEY
• THORBIT_DEPOSITION_MCP_KEY_PATH, or the default ~/.thorbit-deposition-mcp-key

Optional URL overrides:

• THORBIT_BASE_URL
• THORBIT_DEPOSITION_MCP_BASE_URL

The hosted URL defaults to https://thorbit.ai. Keys are sent only to the hosted Thorbit API and are never written to MCP output.

Tools

| Tool | Use it for | | --- | --- | | thorbit_deposition_start | Start a metered durable strategy run for a challenger product and category | | thorbit_deposition_get | Poll status, phase, progress, strategy state, and artifact inventory | | thorbit_deposition_get_playbook | Read the completed positioning strategy playbook | | thorbit_deposition_artifact_read | Read one known research or playbook artifact with a bounded inline preview | | thorbit_deposition_list | Browse recent or status-filtered runs for a project or organization | | thorbit_deposition_search | Search company, category, vulnerability, and playbook content across prior runs |

Every tool advertises an input schema, structured output schema, required scopes, usage guidance, cost behavior, side effects, and the appropriate next tool.

Start input

thorbit_deposition_start requires:

• companyName
• productUrl
• categoryName

Useful optional inputs include up to five competitorUrls, a reviewsUrl, known customer pains, a Thorbit projectPublicId, and up to 8,000 characters of authoritative context. When fewer than two competitor URLs are supplied, hosted Thorbit discovers candidates through SERP research.

Async workflow

1. Call thorbit_deposition_start. It returns immediately with a runPublicId and a thorbit_deposition_get poll target.
2. Poll thorbit_deposition_get until the run is complete or failed. Leave includePhaseData off unless raw intermediate data is necessary.
3. After completion, call thorbit_deposition_get_playbook for the composed strategy.
4. Use artifact IDs returned by thorbit_deposition_get with thorbit_deposition_artifact_read when one specific evidence file is needed.

Do not start another run merely to check progress. Start calls consume caller-organization credits; list, status, playbook, artifact, and search calls are read-only.

Structured results and errors

Successful calls return a structured result with the canonical tool name, request ID, summary or result data, next-tool guidance, warnings, and usage information when available. Failures return a safe error code, message, details when appropriate, and request ID. Preserve the request ID when reporting an issue.

Development

npm install
npm run typecheck
npm test
npm run build
npm pack --dry-run