Settings

Connect ChatData to Claude Code, Cursor, or Codex

Use the client-specific setup path. Claude Code requires remote MCP plus the ChatData Claude plugin. Cursor and Codex use remote MCP only. No shell script or local build is required for hosted MCP.

MCP lifecycle

What runs in a healthy ChatData session

read-write MCP

Session start

chatdata_doctorchatdata_pull_context

Checks auth, workspace, domain, and write tools, then loads the approved context the session should trust.

Context read

chatdata_search_contextchatdata_read_context_file

Finds the metric, source route, proof receipt, or saved answer path needed for the current question.

Writeback

chatdata_record_session_contextchatdata_create_metric_cardchatdata_save_answer_path

Submits reusable session context, metric cards, proof receipts, answer paths, or patches back to ChatData for review.

After write

chatdata_run_context_stewardchatdata_list_review_queue

Surfaces duplicates, drift, and pending review so new context does not silently become approved truth.

Remote MCP is not read-only. It can pull approved context and submit review-gated writeback from any supported MCP client.
If only five tools appear, restart or reconnect the MCP client. It is reading a stale tool cache or old local package.
Pending context is review work, not approved truth. Human review still controls what becomes trusted workspace context.
Claude plugin hooks are required for Claude Code. Cursor, Codex, and other MCP clients use the same MCP tools through normal prompts.

Open command guide

Claude Code bundle

Claude Code needs both pieces: hosted MCP at https://getchatdata.com/api/mcp for the shared trust layer, plus the Claude plugin for /chatdata: commands and prompt/source-read hooks.

Cursor and Codex

Cursor and Codex are MCP-only. Use the remote HTTP snippet when the client supports HTTP MCP servers; otherwise use the local MCP fallback below. Do not install the Claude plugin outside Claude Code.

Create a new API key

Use a label you will recognize later, such as Cursor on work laptop. ChatData shows the key once and stores only a hash.

Create a key to fill the snippets below.

Loading existing API keys.

Claude Code MCP JSON

Loading Claude Code MCP snippet.

Add this under your Claude Code MCP config. Then install the ChatData plugin below, reload plugins, and run /chatdata:status.

Cursor MCP JSON

Loading Cursor MCP snippet.

Add this to Cursor MCP settings. Then ask Cursor to run the ChatData doctor and pull approved context.

Codex MCP JSON

Loading Codex MCP snippet.

Use this when your Codex build supports remote HTTP MCP servers. Codex stays MCP-only and does not run /chatdata: commands.

Claude Code plugin install

claude plugin marketplace add https://github.com/getchatdatacom/chatdata-claude-marketplace.git
claude plugin marketplace update chatdata
claude plugin install chatdata@chatdata

Required for Claude Code customers. It adds /chatdata: commands and Claude-only hooks so metric questions use ChatData before direct source tools. After install, run /reload-plugins or restart Claude Code; plugin startup and /chatdata:status install or repair the default ChatData status line.

Generic HTTP MCP snippet

Loading generic MCP snippet.

Use this for any MCP-capable editor that supports remote HTTP servers with bearer headers.

Why ChatData may not appear in the Codex Plugins list: Codex separates curated plugins, local marketplace plugins, MCP servers, apps, and skills. ChatData can be enabled through MCP even when it does not appear as a Codex plugin.

What ChatData can do after setup

Typical workflow

chatdata_doctor confirms the workspace, MCP auth, and writeback tools.
chatdata_pull_context loads the approved catalog and saved answer paths.
chatdata_prepare_metric_answer resolves the approved route and blocks source mismatch, stale context, unresolved corrections, or unsafe data before a source read.
chatdata_search_context and chatdata_read_context_file inspect only the context selected by that route.
chatdata_record_session_context or a focused write tool saves reusable context for review.

Claude Code uses the slash commands below. Cursor, Codex, and other MCP clients use the MCP tools and normal-language prompts. The active ChatData harness applies context, frame, validation, proof, and sync checks to analytics questions without requiring users to pick a special command first.

Claude Code commands

Start and setup

/chatdata:start Show the full feature catalog and the best first command.

/chatdata:commands Show every major ChatData command and when to use it, including the default active harness.

/chatdata:help Show setup status, the command map, and the next useful command.

/chatdata:login Legacy repair path for local auth/config issues; primary setup uses remote MCP API keys.

/chatdata:status Check MCP, workspace, context sync, and review-queue status.

/chatdata:update Update the Claude plugin and MCP package from the marketplace.

/chatdata:onboarding Run shared onboarding and save setup learnings into MCP context.

/chatdata:settings Open ChatData Settings for MCP API keys, consent, and install repair.

/chatdata:catalog Use the agent-ready data catalog that powers trusted metric answers.

/chatdata:trial-and-privacy Explain trial status, privacy boundaries, tokens, and local state.

/chatdata:license Check trial, license, plan, and account status.

/chatdata:activate-session Activate a Claude session by checking MCP and choosing the next workflow.

Analysis

/chatdata:question-framing Start with the user decision, grounded anchors, and candidate frames before querying.

/chatdata:warehouse-query Manually inspect warehouse, KPI, dashboard, SQL, and recurring analytics source routing.

/chatdata:prepare-metric-answer Prepare a fail-closed metric route before any direct source read.

/chatdata:investigate Investigate a KPI or business question with anchors, alternate frames, evidence, caveats, and proof.

/chatdata:investigate-metric Diagnose a KPI movement by constructing, stress-testing, and committing to a sourced frame.

/chatdata:impact Translate a metric movement into business impact, risk, and owner action.

/chatdata:prepare-wbr Prepare a weekly business review from approved metrics and evidence.

/chatdata:write-operating-brief Write a concise operating brief from trusted context and evidence.

/chatdata:story-and-action Turn a trusted analysis into a stakeholder-ready story and action plan.

Trust and validation

/chatdata:validate Validate SQL, charts, metric packets, answers, and exploratory frame trails before stakeholders see them.

/chatdata:validation-stack Apply the full validation stack, including frame trail checks, to an answer, WBR, proof, or packet.

/chatdata:benchmark Find, inspect, or create the benchmark behind a metric or answer path.

/chatdata:build-benchmark Build a trusted SQL, dashboard, or artifact benchmark for a metric.

/chatdata:but-for-real Run a skeptical proof pass before calling work ready or trusted.

/chatdata:audit-context Audit context health before trusting a customer workflow.

/chatdata:review-readiness Grade whether packets, answer paths, patches, and proof are ready.

Context, memory, and proof

/chatdata:sync-context Pull approved context and save reviewed metrics, answer paths, proof, or patches.

/chatdata:proof Record a proof receipt for an install, trusted answer, benchmark, or workflow.

/chatdata:proof-receipts Inspect or record proof receipts.

/chatdata:feedback-memory Save corrections, preferred wording, source choices, or caveats into shared context.

/chatdata:drift-check Detect drift after dbt, dashboard, metric, answer-path, or feedback changes.

/chatdata:publish-patch Publish one reviewed pending patch through the MCP hub.

Build the trust layer

/chatdata:metrics Inspect, create, or repair metric trust packets.

/chatdata:connect-data Plan and record sources, dashboards, dbt artifacts, and owners.

/chatdata:context-bootstrap Bootstrap shared context from metrics, sources, owners, caveats, and answer paths.

/chatdata:company-repo Compatibility route for legacy company-repo setup; prefer MCP-backed context.

/chatdata:bootstrap-repo Create a customer-owned trust-layer repo from the template.

/chatdata:scan-sources Scan dbt, dashboards, docs, owners, and source metadata.

/chatdata:draft-metric-packet Draft a metric packet with owner, grain, source, caveats, and validation.

/chatdata:generate-evals Generate recurring KPI eval questions from approved context.

/chatdata:create-evals Create recurring KPI evals that catch routing, metric, and caveat drift.

MCP tools

chatdata_status Read ChatData MCP workspace connection state.

chatdata_doctor Check auth, consent, domain match, hub health, and approved context.

chatdata_agent_context Fetch compact surface-specific agent instructions and the writeback loop.

chatdata_list_guidance List fetchable templates, rules, skills, and runbooks.

chatdata_read_guidance Read one non-secret guidance document by id.

chatdata_pull_context Pull approved workspace context from the ChatData hub.

chatdata_search_context Search approved context files in the ChatData hub.

chatdata_read_context_file Read one approved context file by relative Markdown path.

chatdata_prepare_metric_answer Plan context, source, correction, validation, cost, and refusal gates before a source read.

chatdata_import_source_context Submit a bounded 10-20 table metadata-only pilot manifest for review.

chatdata_submit_answer_feedback Attach answer feedback and turn negative outcomes into review proposals.

chatdata_get_trust_scorecard Read the release eval and honest seven-day production trust signals.

chatdata_record_session_context Submit reusable session or query context as a proof receipt for review.

chatdata_create_metric_card Submit a metric definition card for human review.

chatdata_save_answer_path Submit a reusable answer path for human review.

chatdata_create_proof_receipt Submit proof, validation, benchmark, or install evidence for review.

chatdata_propose_patch Propose a guarded context-file patch for review.

chatdata_list_review_queue List pending files and conflicts that need human review.

chatdata_run_context_steward Detect duplicate reusable context and create reviewed merge proposals.

chatdata_publish_patch Publish one reviewed pending patch by patch id.

MCP prompt pattern

Say what you want done, then name the tool only when useful: Use ChatData to pull context, then search approved context for churn metrics.

Claude plugin install and local MCP fallback

Claude Code customers should install the plugin after remote MCP. Use the local MCP fallback only when your client cannot use remote HTTP MCP yet.

Copy one repair prompt: Paste it into Claude Code, Cursor, or Codex if remote MCP is blocked and you need the older local package path. Do not share screenshots of the prompt because it can contain local auth config.

Reference guide: getchatdata.com/agents.md. Use the remote MCP snippets above first.

Surface-aware setup prompt

Loading surface-aware setup prompt.

Expected local fallback outcome for Claude Code: MCP connected, plugin installed, then /chatdata:onboarding after reload if needed. Expected Codex fallback outcome: codex mcp get chatdata points at the built MCP package, then the next Codex session can run ChatData MCP tools directly.

Already installed in Claude Code? Run /chatdata:update inside Claude Code. It updates the ChatData plugin, refreshes the MCP package, then tells you to run /reload-plugins or restart before verifying with /chatdata:status.

Manual commands by surface

Use these only when the copied setup prompt cannot run shell commands or you need to debug one step at a time.

If Terminal says zsh: command not found: token: You pasted the raw Client config JSON into Terminal. Come back here, click Copy terminal setup command, and paste the command that starts with mkdir -p "$HOME/.chatdata".

Pick the surface first.
Use the Claude Code commands only inside Claude Code. Use the Codex commands only inside Codex. Having both CLIs installed on the same machine is not enough to choose the surface.
Save your ChatData config.
This writes local ChatData auth config to ~/.chatdata/config.json. Settings refreshes the config before generating this command. Run it once per workspace, and rerun it only after switching workspaces or logging in again. Do not copy individual JSON lines like token:, workspace_id:, or domain:.
Terminal command
```
Loading saved setup command.
```
Expected final line in Terminal: Saved ChatData config to $HOME/.chatdata/config.json. The JSON button is only for support or manual file editing.

Build the local MCP package once.

This downloads or updates the ChatData-owned distribution repo under ~/.chatdata, installs dependencies, and builds the MCP server file. Do not continue to a surface command if this step ends with an error.

Terminal command

CHATDATA_INSTALL_REPO_DIR="${CHATDATA_INSTALL_REPO_DIR:-$HOME/.chatdata/chatdata-claude-marketplace}"; CHATDATA_INSTALL_REPO_URL="${CHATDATA_INSTALL_REPO_URL:-https://github.com/getchatdatacom/chatdata-claude-marketplace.git}"; if [ -d "$CHATDATA_INSTALL_REPO_DIR/.git" ]; then git -C "$CHATDATA_INSTALL_REPO_DIR" pull --ff-only; elif [ -e "$CHATDATA_INSTALL_REPO_DIR" ]; then echo "Move $CHATDATA_INSTALL_REPO_DIR or set CHATDATA_INSTALL_REPO_DIR to an empty path, then rerun."; exit 1; else mkdir -p "$(dirname "$CHATDATA_INSTALL_REPO_DIR")" && git clone "$CHATDATA_INSTALL_REPO_URL" "$CHATDATA_INSTALL_REPO_DIR"; fi; CHATDATA_MCP_DIR="${CHATDATA_MCP_DIR:-$CHATDATA_INSTALL_REPO_DIR/packages/mcp}"; cd "$CHATDATA_MCP_DIR" && npm install && npm run build && test -f "$CHATDATA_MCP_DIR/dist/index.js" && echo "Built ChatData MCP at $CHATDATA_MCP_DIR/dist/index.js"

Codex path.

Codex uses MCP only. It does not install the Claude plugin and does not run /chatdata: slash commands.

Codex command

CHATDATA_INSTALL_REPO_DIR="${CHATDATA_INSTALL_REPO_DIR:-$HOME/.chatdata/chatdata-claude-marketplace}"; CHATDATA_MCP_DIR="${CHATDATA_MCP_DIR:-$CHATDATA_INSTALL_REPO_DIR/packages/mcp}"; test -f "$CHATDATA_MCP_DIR/dist/index.js" || { echo "ChatData MCP is not built yet. Run the build command above first."; exit 1; }; codex mcp add chatdata -- node "$CHATDATA_MCP_DIR/dist/index.js" --client=codex

Reset wrong Codex entry

CHATDATA_INSTALL_REPO_DIR="${CHATDATA_INSTALL_REPO_DIR:-$HOME/.chatdata/chatdata-claude-marketplace}"; CHATDATA_MCP_DIR="${CHATDATA_MCP_DIR:-$CHATDATA_INSTALL_REPO_DIR/packages/mcp}"; test -f "$CHATDATA_MCP_DIR/dist/index.js" || { echo "ChatData MCP is not built yet. Run the build command above first."; exit 1; }; codex mcp remove chatdata 2>/dev/null || true; codex mcp add chatdata -- node "$CHATDATA_MCP_DIR/dist/index.js" --client=codex

Codex connected check

codex mcp get chatdata

Codex list command

codex mcp list

Reconnect the Codex session after adding the server. Then ask Codex to use the ChatData MCP server and run chatdata_doctor.

Claude Code path.

Install or update the Claude plugin and register MCP. Claude Code customers need both: the plugin adds /chatdata: commands and hooks; MCP is the shared trust/writeback layer.

Product update command

/chatdata:update

Add marketplace

claude plugin marketplace add https://github.com/getchatdatacom/chatdata-claude-marketplace.git

Refresh marketplace

claude plugin marketplace update chatdata

Install plugin

claude plugin install chatdata@chatdata

Already installed update

claude plugin update chatdata@chatdata

Manual fallback for old installs

claude plugin marketplace add https://github.com/getchatdatacom/chatdata-claude-marketplace.git; claude plugin marketplace update chatdata; claude plugin update chatdata@chatdata; CHATDATA_INSTALL_REPO_DIR="${CHATDATA_INSTALL_REPO_DIR:-$HOME/.chatdata/chatdata-claude-marketplace}"; CHATDATA_INSTALL_REPO_URL="${CHATDATA_INSTALL_REPO_URL:-https://github.com/getchatdatacom/chatdata-claude-marketplace.git}"; if [ -d "$CHATDATA_INSTALL_REPO_DIR/.git" ]; then git -C "$CHATDATA_INSTALL_REPO_DIR" pull --ff-only; elif [ -e "$CHATDATA_INSTALL_REPO_DIR" ]; then echo "Move $CHATDATA_INSTALL_REPO_DIR or set CHATDATA_INSTALL_REPO_DIR to an empty path, then rerun."; exit 1; else mkdir -p "$(dirname "$CHATDATA_INSTALL_REPO_DIR")" && git clone "$CHATDATA_INSTALL_REPO_URL" "$CHATDATA_INSTALL_REPO_DIR"; fi; CHATDATA_MCP_DIR="${CHATDATA_MCP_DIR:-$CHATDATA_INSTALL_REPO_DIR/packages/mcp}"; cd "$CHATDATA_MCP_DIR" && npm install && npm run build && test -f "$CHATDATA_MCP_DIR/dist/index.js"
python3 - <<'PY'
import json, pathlib, subprocess, sys
home = pathlib.Path.home()
installed_path = home / ".claude" / "plugins" / "installed_plugins.json"
try:
    installed = json.loads(installed_path.read_text())
except Exception:
    print(f"ChatData status line install failed: missing or unreadable {installed_path}", file=sys.stderr)
    raise SystemExit(2)
entries = installed.get("plugins", {}).get("chatdata@chatdata", [])
entry = next((item for item in entries if item.get("scope") == "user"), entries[0] if entries else None)
if not entry or not entry.get("installPath"):
    print("ChatData status line install failed: chatdata@chatdata install path not found", file=sys.stderr)
    raise SystemExit(2)
installer = pathlib.Path(entry["installPath"]) / "scripts" / "install-status-line.py"
if not installer.exists():
    print(f"ChatData status line install failed: missing {installer}", file=sys.stderr)
    raise SystemExit(2)
subprocess.run([sys.executable, str(installer)], check=True)
PY

Apply update

/reload-plugins

Verify plugin

claude plugin list

Expected plugin check: chatdata@chatdata is enabled. Restart Claude Code after plugin install or update.

Claude Code MCP command

CHATDATA_INSTALL_REPO_DIR="${CHATDATA_INSTALL_REPO_DIR:-$HOME/.chatdata/chatdata-claude-marketplace}"; CHATDATA_MCP_DIR="${CHATDATA_MCP_DIR:-$CHATDATA_INSTALL_REPO_DIR/packages/mcp}"; test -f "$CHATDATA_MCP_DIR/dist/index.js" || { echo "ChatData MCP is not built yet. Run the build command above first."; exit 1; }; claude mcp add --scope user chatdata -- node "$CHATDATA_MCP_DIR/dist/index.js" --client=claude-code

If Terminal says MCP server chatdata already exists in user config, run the details command and continue if it shows Status: Connected, Command: node, and the ChatData packages/mcp/dist/index.js path.

Claude connected check

claude mcp get chatdata

Only use this reset command if the details command points to an old or wrong path. It removes Claude's MCP pointer and adds the correct one again; it does not delete your ChatData config or workspace data.

Reset wrong Claude entry

CHATDATA_INSTALL_REPO_DIR="${CHATDATA_INSTALL_REPO_DIR:-$HOME/.chatdata/chatdata-claude-marketplace}"; CHATDATA_MCP_DIR="${CHATDATA_MCP_DIR:-$CHATDATA_INSTALL_REPO_DIR/packages/mcp}"; test -f "$CHATDATA_MCP_DIR/dist/index.js" || { echo "ChatData MCP is not built yet. Run the build command above first."; exit 1; }; claude mcp remove chatdata -s user 2>/dev/null || true; claude mcp add --scope user chatdata -- node "$CHATDATA_MCP_DIR/dist/index.js" --client=claude-code

Terminal command

claude mcp list

Run onboarding after status is green. ChatData pulls saved context first, chooses one recurring metric question, saves evidence, and creates a reusable answer path.

Claude command

/chatdata:onboarding

Claude command

/chatdata:start

Claude help command

/chatdata:help

Raw MCP doctor fallback.
If help says MCP is missing or you need raw setup proof, paste this exact sentence. Do not type only chatdata_doctor.
Chat message
```
Use the ChatData MCP server and run the chatdata_doctor tool. Show me the JSON result.
```

Opening your workspace.

Make one metric answer reusable

Make one metric answer reusable

Workspace

Data sync permission

Product ROI estimate

Workspace members