thorbit-icp-mcp

MCP server for the Thorbit ICP (Ideal Customer Profile) generation pipeline. Hosted Thorbit runs the durable ICP workflow; this package is a thin stdio client that forwards every tool call to the hosted Thorbit route and is authenticated + metered against your Thorbit MCP API key.

Install / run

npx thorbit-icp-mcp

Or add it to an MCP client config:

{
  "mcpServers": {
    "thorbit-icp": {
      "command": "npx",
      "args": ["thorbit-icp-mcp"],
      "env": {
        "THORBIT_ICP_API_KEY": "thbt_mcp_..."
      }
    }
  }
}

Generate the same JSON from the CLI:

npx -y -p thorbit-icp-mcp@latest thorbit-icp-mcp-install --json --api-key thbt_mcp_...

Prefer a key file on shared machines and servers:

mkdir -p ~/.config/thorbit
printf '%s\n' 'thbt_mcp_...' > ~/.config/thorbit/icp-mcp-key
chmod 600 ~/.config/thorbit/icp-mcp-key
npx -y -p thorbit-icp-mcp@latest thorbit-icp-mcp-install --key-path ~/.config/thorbit/icp-mcp-key

Run npx -y -p thorbit-icp-mcp@latest thorbit-icp-mcp-install --help for all options.

Environment

• THORBIT_ICP_API_KEY — your Thorbit MCP API key (required). Fallbacks: THORBIT_API_KEY, THORBIT_MCP_API_KEY, or a key file at ~/.thorbit-icp-mcp-key (override path with THORBIT_ICP_MCP_KEY_PATH).
• THORBIT_ICP_BASE_URL — optional, defaults to https://thorbit.ai. Fallback: THORBIT_BASE_URL.

The key is never logged.

Tools

1. thorbit_icp_start — start a durable ICP run for a Thorbit project. Returns { runPublicId, poll }.
2. thorbit_icp_get — poll an ICP run for lean status, phase/progress, research verdict, and the artifact manifest.
3. thorbit_icp_get_result — read the composed ICP document (markdown or json) once the run is complete.
4. thorbit_icp_artifact_read — read one artifact by id (e.g. final_icp, eos_framework, research_notes, reddit_insights).
5. thorbit_icp_list — list past ICP runs, filterable by project, search, and status.
6. thorbit_icp_search — full-text search across past ICP runs and their composed content.

It also exposes a resource template thorbit-icp://runs/{runPublicId} (run status as JSON) and a thorbit_icp_intake prompt.

Async poll flow

1. Call thorbit_icp_start with projectPublicId (and optionally input / skipResearch). It returns quickly with a runPublicId and a poll target. Do not block.
2. Poll thorbit_icp_get with that runPublicId until status is completed or failed.
3. When complete, call thorbit_icp_get_result for the final ICP document, and thorbit_icp_artifact_read for any intermediate evidence.

Develop

npm install
npm run typecheck
npm run test
npm run build