Connect your agents

Quickstart

1. Create a workspace (free beta).
2. Open Settings → Agents & API and create a key. It starts with gt_ and is shown once.
3. Point your agent at https://groundtruthhq.tech/api/mcp with Authorization: Bearer gt_….

Claude

Connect Groundtruth to Claude and ask about your company in any chat: Claude searches your pages, decisions and records and answers with citations. It can also write back: log a decision, add to a page, update a record or move a card on your board. You need a Groundtruth account and a workspace.

Claude (web, desktop, mobile)

1. In Claude, open Settings → Connectors, choose Add custom connector, name it Groundtruth and paste the URL below (or add Groundtruth from the connector directory once it's listed).
2. Claude opens a Groundtruth sign-in. Log in, pick the workspace Claude may use and click Allow.
3. Ask something like “What's our refund policy?” or “What's on our board for this week?”

https://groundtruthhq.tech/api/mcp

Claude Code

claude mcp add --transport http groundtruth https://groundtruthhq.tech/api/mcp

Then run /mcp in Claude Code to sign in. An API key header also works for scripts and CI: --header "Authorization: Bearer gt_YOUR_KEY".

What Claude can do

• Read (no confirmation needed): ask, search, list and read pages, decisions, records, activity, alerts, agents and board cards.
• Write (Claude asks you first): create or update pages, log decisions, upsert records, log customer interactions, resolve alerts, run an installed agent, and create, update or comment on board cards.
• Every write is labelled as an AI-agent edit and attributed to the connection in the activity log. Pages an agent writes are marked Needs review for their owner, and every page edit can be restored from the page's history. Agents can't delete pages or cards, verify pages, or mark cards done.

Data and privacy

The connection can reach one workspace: the one you picked. It sees what a member of that workspace sees and nothing else, and Groundtruth doesn't receive your Claude conversations, only the tool calls Claude makes. Answers to agents come back as cited sources, so no AI model runs on our side for them. See the privacy policy and AI transparency.

Disconnect

Remove the connector in Claude, or revoke the connection in Groundtruth under Settings & API → API keys (it's listed as “Claude”). Revoking takes effect immediately. Workspace owners can revoke any connection in their workspace.

Troubleshooting

• The sign-in shows no workspaces: create one first at your workspaces, then connect again.
• “Authorization failed” after it worked before: the connection was revoked or you left the workspace. Remove the connector in Claude and add it again.
• Anything else: email hello@groundtruthhq.tech.

Under the hood: OAuth 2.1 with PKCE (S256), Client ID Metadata Documents and Dynamic Client Registration, per the MCP authorization spec; rotating refresh tokens. Discovery at /.well-known/oauth-protected-resource.

Cursor and other MCP clients

{
  "mcpServers": {
    "groundtruth": {
      "url": "https://groundtruthhq.tech/api/mcp",
      "headers": { "Authorization": "Bearer gt_YOUR_KEY", "X-Agent-Name": "Cursor" }
    }
  }
}

Optional X-Agent-Name sets the name shown in the activity log (defaults to the key's name).

Your own agent

With the Claude API's MCP connector, Claude calls Groundtruth directly:

import anthropic

client = anthropic.Anthropic()
resp = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    mcp_servers=[{
        "type": "url",
        "url": "https://groundtruthhq.tech/api/mcp",
        "name": "groundtruth",
        "authorization_token": "gt_YOUR_KEY",
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "groundtruth"}],
    messages=[{"role": "user", "content": "What's our refund policy? Cite the page."}],
    betas=["mcp-client-2025-11-20"],
)

REST API

Every MCP tool is also POST /api/v1/<tool> with the tool's arguments as the JSON body. Read-only tools accept GET with query parameters. GET /api/v1 lists them.

curl -s https://groundtruthhq.tech/api/v1/ask \
  -H "Authorization: Bearer gt_YOUR_KEY" -H 'content-type: application/json' \
  -d '{"question":"Who approves refunds over $5,000?"}'

# Read-only tools also take GET with query parameters:
curl -s "https://groundtruthhq.tech/api/v1/query_records?collection=customers&sort=-mrr" -H "Authorization: Bearer gt_YOUR_KEY"

Tokens & your AI key

• Agents use their own model. When an agent calls ask, Groundtruth returns the cited sources (plus a quick extractive draft) and makes no model call. Your agent writes the final answer with whatever model it already runs.
• The web app uses your key. Add an Anthropic or OpenAI key in Settings → AI. Keys are encrypted (AES-256-GCM), verified by listing your models (no tokens spent), and never shown again. Usage is billed by your provider with zero markup.
• No key, still cited. Without a key, answers in the app are stitched from the best-matching sentences, with the same citations.

Agent Store

Install agents from Agent Store in your workspace. They run daily at 06:00 UTC (or on demand), write findings back to your records attributed to the agent, and raise alerts. Connect a Slack incoming webhook in Settings → Alert notifications to get them in a channel.

• Contract Agent reads the contracts collection: end_date, notice_days, auto_renew, owner, value_annual. Writes cancel_by, days_until_cancel_by, contract_status.
• Churn Agent reads customers (renewal, health, mrr, usage_change_pct) and interactions (customer, date, type, sentiment, nps, summary). Writes churn_risk, churn_level, churn_reasons.
• Freshness Agent flags pages not verified within 90 days.

curl -s https://groundtruthhq.tech/api/v1/log_interaction -H "Authorization: Bearer gt_YOUR_KEY" \
  -H 'content-type: application/json' \
  -d '{"customer":"Initech","type":"ticket","sentiment":"negative","summary":"Third outage this month; asked about cancellation terms"}'

Tool reference

Markdown & llms.txt

Every page has a plain markdown twin with front-matter at /w/<workspace>/p/<id>.md, and every workspace publishes an index at /w/<workspace>/llms.txt.

Security model

• Keys are scoped to one workspace, stored as SHA-256 hashes, and revocable instantly.
• Agent writes are attributed to the key (and optional agent name) and badged in the UI.
• Ask never answers without a source; unanswerable questions are refused rather than guessed.
• Rendered markdown never executes HTML or javascript: links.