@skyphusion/common-thread-mcp

MIT Model Context Protocol server for Common Thread: drive the full investigation API from an agent (create cases, seeds, Apify ingest, BYOK attribution, evidence packets).

npm	@skyphusion/common-thread-mcp
Repo	https://github.com/skyphusion-labs/common-thread-mcp
Product UI	https://common-thread.skyphusion.org
HTTP contract	common-thread docs/API.md
License	MIT (this package). Product: AGPL implementation + CC-BY paper

Documentation

Doc	Audience
docs/mcp.md	Full guide: install, agent config, auth, every tool, troubleshooting
docs/PARITY.md	Website UI vs MCP tools
docs/SECURITY.md	Tokens, BYOK, hosted vs self-host
CLAUDE.md	Agent working notes for this repo

Quick start

npx -y @skyphusion/common-thread-mcp

Claude Desktop / Claude Code example:

{
  "mcpServers": {
    "common-thread": {
      "command": "npx",
      "args": ["-y", "@skyphusion/common-thread-mcp"],
      "env": {
        "COMMON_THREAD_API_URL": "https://common-thread-backend.skyphusion.org",
        "COMMON_THREAD_AI_GATEWAY_URL": "https://gateway.ai.cloudflare.com/v1/ACCOUNT/GATEWAY/anthropic",
        "COMMON_THREAD_ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

1. Call create_investigation and store access_token once.
2. Set COMMON_THREAD_INVESTIGATION_ID + COMMON_THREAD_ACCESS_TOKEN, or pass them on every tool.
3. Ingest → features → attribute (BYOK on public host) → get_packet.

Environment (summary)

Variable	Purpose
COMMON_THREAD_API_URL	Backend base (default hosted backend)
COMMON_THREAD_ACCESS_TOKEN / COMMON_THREAD_INVESTIGATION_ID	Defaults for tools
COMMON_THREAD_AI_GATEWAY_URL + Anthropic key or COMMON_THREAD_CF_AIG_TOKEN	BYOK for public attribution

Full table: docs/mcp.md#environment.

Tools (23)

Lifecycle: health, create_investigation, get_investigation, update_investigation_metadata, seal_investigation, delete_investigation, investigation_summary

Seeds: list_seeds, add_seed, remove_seed

Data: list_features, ingest_apify_twitter, get_ingest_job

Attribution: attribute, get_attribution_job, list_runs, get_run

Packets / archive: get_packet, list_manifest, list_signatures, verify_manifest

Debug: debug_ingest, debug_manifest

Hosted API note

The hosted backend is for the public UI and approved integrations. Self-host for unrestricted automation, or contact common-thread@skyphusion.org before productizing against hosted.

Develop

npm ci && npm run typecheck && npm test && npm run build
node dist/index.js

License

MIT. Common Thread product licenses are separate (AGPL-3.0 implementation, CC-BY-4.0 paper).