# AGENTS.md - ChatData MCP Setup

This is the public setup guide for ChatData in Claude Code, Cursor, Codex, and other MCP-capable clients.

Canonical URL: https://getchatdata.com/agents.md

## Default Setup

Use the client-specific setup path:

- Claude Code: hosted ChatData MCP plus the ChatData Claude Code plugin. Both are required for the trusted Claude workflow.
- Cursor: hosted ChatData MCP only.
- Codex: hosted ChatData MCP only.
- Generic MCP clients: hosted ChatData MCP when the client supports remote HTTP MCP.

No shell script, clone, or local build is required for hosted MCP. The Claude plugin is required only in Claude Code because it supplies `/chatdata:` commands and Claude-specific prompt/source-read hooks.

1. Log in at https://getchatdata.com/login.
2. Open https://getchatdata.com/app/setup#mcp-api-keys.
3. Create a named MCP API key, such as "Cursor on work laptop".
4. Paste the matching JSON snippet into your editor's MCP settings.
5. Ask the editor to run `chatdata_doctor`.

## Cursor

Open Cursor Settings -> MCP and add:

~~~json
{
  "mcpServers": {
    "chatdata": {
      "type": "http",
      "url": "https://getchatdata.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CHATDATA_KEY",
        "X-ChatData-MCP-Client": "cursor-mcp"
      }
    }
  }
}
~~~

## Codex

Use this when your Codex build supports remote HTTP MCP servers:

~~~json
{
  "mcpServers": {
    "chatdata": {
      "type": "http",
      "url": "https://getchatdata.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CHATDATA_KEY",
        "X-ChatData-MCP-Client": "codex-mcp"
      }
    }
  }
}
~~~

Codex is MCP-only. Do not install the Claude plugin and do not run `/chatdata:` slash commands in Codex.

## Claude Code

Claude Code has two required pieces: remote MCP for the shared trust/writeback API, and the ChatData plugin for the Claude-only command and hook layer.

1. Add this to your Claude Code MCP config:

~~~json
{
  "mcpServers": {
    "chatdata": {
      "type": "http",
      "url": "https://getchatdata.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CHATDATA_KEY",
        "X-ChatData-MCP-Client": "claude-code-mcp"
      }
    }
  }
}
~~~

2. Install the ChatData Claude Code plugin from the ChatData marketplace:

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

Then reload plugins or restart Claude Code, and run `/chatdata:status`. The plugin startup hook and status command install or repair the ChatData Claude Code status line by writing the user-level `~/.claude/settings.json` `statusLine` setting to ChatData and backing up any previous footer under `chatdata.previousStatusLine`. MCP health, context state, and review risk should be visible without another settings step.

## Generic MCP Client

Use the same hosted endpoint with a bearer API key:

~~~json
{
  "mcpServers": {
    "chatdata": {
      "type": "http",
      "url": "https://getchatdata.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CHATDATA_KEY",
        "X-ChatData-MCP-Client": "mcp"
      }
    }
  }
}
~~~

If your client does not support remote HTTP MCP servers yet, use the local fallback from ChatData Settings.

## Verify

After saving the MCP config, ask the editor:

~~~text
Use ChatData and run chatdata_doctor with expected_domain set to my company domain. Show me the JSON result.
~~~

Expected result:

- auth is true
- domain_match is true
- transport is remote_http
- consent is granted
- read_only is false
- required_write_tools_present is true

If the client says ChatData is read-only or only shows five tools, reconnect or restart that MCP client. A stale session is still reading the old tool cache.

Then ask ChatData to pull approved context and choose one recurring metric answer to make reusable. In Claude Code, finish with `/chatdata:status` so the plugin and MCP state are checked together.

## What ChatData Can Do After Setup

Claude Code uses the required `/chatdata:` plugin commands plus the MCP tools below. Cursor, Codex, and other MCP clients use the tools below through normal-language prompts.

- Setup and status: run `chatdata_doctor`, pull approved context, and check the review queue.
- Analysis: run `chatdata_prepare_metric_answer` before a direct metric-source read, then use its bounded approved context route.
- Trust and validation: record proof receipts, save reusable answer paths, and submit guarded patches for human review.
- Context sync: create metric cards, submit feedback as context patches, list pending review items, and publish approved patches.
- Session writeback: record reusable session/query context with `chatdata_record_session_context`, then run `chatdata_run_context_steward` and check the review queue.

## Business Metric Preflight

For KPI, traffic, funnel, revenue, retention, conversion, activation, usage, or other business-metric questions, use ChatData before direct source tools.

1. Run `chatdata_doctor` when connection state is unknown.
2. Call `chatdata_prepare_metric_answer` with the exact question and expected workspace domain.
3. Confirm it returns `plan_only: true` and `source_executed: false`. Inspect why context was selected, discounted, or excluded.
4. Stop on `clarification_needed`, `needs_analyst_review`, `source_mismatch`, or `refused`. Do not query around the block.
5. Query PostHog, warehouse, BI, spreadsheet, or file tools only after an `answered` route allows the source read.
6. Bind proof and any reusable path to the route id, then submit reviewed outcome feedback.

The required Claude Code plugin wraps this flow with commands and hooks, but Cursor, Codex, OpenClaw, and generic MCP clients still inherit the rule through MCP guidance plus review-gated writeback.

Prompt examples:

~~~text
Use ChatData to pull approved context, search for activation metrics, and tell me which approved answer path should handle this question.
~~~

~~~text
Use ChatData first to resolve the official visits/session definition, then use PostHog for the trailing-7-day value, and record a proof receipt if this should become reusable.
~~~

~~~text
Use ChatData to save this recurring answer path for review. Include the metric id, source, validation rule, caveats, uncertainty policy, and reuse rule.
~~~

## Available Tools

- chatdata_status
- chatdata_doctor
- chatdata_agent_context
- chatdata_list_guidance
- chatdata_read_guidance
- chatdata_pull_context
- chatdata_search_context
- chatdata_read_context_file
- chatdata_prepare_metric_answer
- chatdata_import_source_context
- chatdata_submit_answer_feedback
- chatdata_get_trust_scorecard
- chatdata_record_session_context
- chatdata_create_metric_card
- chatdata_save_answer_path
- chatdata_create_proof_receipt
- chatdata_propose_patch
- chatdata_list_review_queue
- chatdata_run_context_steward
- chatdata_publish_patch

## Optional Fallbacks

Only use these when hosted MCP is blocked or the user needs local fallback behavior.

- Local MCP fallback: open ChatData Settings and expand "Claude plugin install and local MCP fallback".
- Claude Code plugin: required for Claude Code customers; do not install it for Cursor, Codex, or generic MCP clients.
- Codex local fallback: use the Settings fallback only when remote HTTP MCP is unavailable in the current Codex build.

Do not ask users to install a shell script for hosted MCP setup.

## Data Boundaries

- Keep API keys private. ChatData shows each key once and stores only a hash.
- Do not print workspace tokens, raw config JSON, or sensitive context contents.
- ChatData stores metadata for metric definitions, proof receipts, review state, and reusable answer paths.
- Support email: support@getchatdata.com.