Docs

Connect your agents

Groundtruth speaks MCP (Streamable HTTP) and plain REST. Every tool an agent can call is also an endpoint, and everything a human can do in the app, an agent can do too.

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, go to Customize → Connectors, search for Groundtruth in the directory and click Connect. (You can also add a custom connector with the URL below.)
  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?”
url
https://groundtruthhq.tech/api/mcp

Claude Code

shell
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 conversations with Claude, ChatGPT or Gemini, only the tool calls they make. 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 disconnect it in Groundtruth under Settings → AI assistants, where every connection is listed with when it was last used. 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; issuer identification (RFC 9207); rotating refresh tokens. The same server handles Claude, ChatGPT and Gemini. Discovery at /.well-known/oauth-protected-resource.

ChatGPT

ChatGPT connects the same way Claude does: one URL, sign in with OAuth, pick a workspace. It gets the same tools, and asks you before it changes anything.

  1. In ChatGPT on the web, open Settings → Apps → Advanced settings and turn on Developer mode (paid plans; on Business and Enterprise an admin may need to allow it).
  2. Choose Create app, name it Groundtruth, paste the URL below as the MCP server URL and choose OAuth.
  3. Sign in to Groundtruth, pick the workspace and click Allow. In a chat, select Groundtruth from the tools menu.
url
https://groundtruthhq.tech/api/mcp

We've applied to ChatGPT's app directory; once listed, it's one click. The connection shows up as “ChatGPT” under Settings → AI assistants, where you can disconnect it.

Gemini

Gemini app

  1. On gemini.google.com, open Settings → Connected apps → Add a custom app.
  2. Paste the URL above, click Next, sign in to Groundtruth and pick the workspace.
  3. In a chat, type @ and choose Groundtruth. Gemini asks you to confirm every write.

Google currently offers custom apps to adults in the US with a personal Google account, in English, set up on the web (then usable on mobile too).

Gemini Enterprise

An admin adds Groundtruth once for the team under Manage team → Connected apps → Add MCP server. Choose OAuth 2.0 with PKCE on. A Groundtruth workspace owner creates the client ID in Settings → AI assistants → Gemini by pasting Gemini Enterprise's callback URL, and gets every value the form asks for: authorization URL https://groundtruthhq.tech/oauth/authorize, token URL https://groundtruthhq.tech/oauth/token, scope workspace. There's no client secret; enter a placeholder if the form requires one. Each person then signs in with their own Groundtruth account.

Cursor and other MCP clients

json · .cursor/mcp.json
{
  "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:

python
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.

shell
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 a Claude (Anthropic), OpenAI or Gemini (Google) key in Settings → AI in the app; Claude is the default. Which model to pick. 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.
  • A free credit to start. Until you add a key, people in the app get $0.50 of free AI credit on Claude Haiku 5.5, enough for hundreds of questions.
  • No key, still cited. After that, 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.
  • Librarian Agent checks every morning for [[Page title]] links to pages that don't exist, likely duplicate pages, pages nothing links to (once your team links pages) and questions asked three times or more that nothing answers.
  • Wispr Flow (integration) files Wispr Flow Notetaker meetings as pages. Each person connects their own Wispr account (read-only) and saves meetings one by one, or picks a Wispr folder whose meetings are filed every morning. Pages carry the summary, notes, attendees and a link back to Wispr, are labelled as Wispr's AI summary and wait for review. Transcripts are left out unless the workspace turns them on.
  • Plaud (integration) files Plaud recordings the same way: each person connects their own Plaud account (read-only) and saves recordings one by one, or files automatically the ones with a word like #team in the title, or every new recording. Plaud's summary tab becomes the page's summary; highlights, template tabs and saved Ask Plaud answers go under Notes.
shell · feed the Churn Agent from any agent
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

askread

Ask a natural-language question about the company. Returns the most relevant sources (pages, decisions, records) with numbered citations and a quick draft answer; compose your final answer from `sources` and cite them as [n]. Use this first for any 'what/who/how/why' question about how the company works.

question*

searchread

Keyword search across pages, decisions and records. Returns ranked hits with snippets and ids you can pass to get_page.

query*, types, limit

list_pagesread

List pages (id, title, space, tags, owner, staleness). Optionally filter by space or tag.

space, tag

get_pageread

Read a full page as markdown, with owner, last editor (human or agent), staleness, a one-line summary, the pages it links to ([[Page title]] links, including ones not written yet) and the pages that link to it.

page*

list_my_pagesread

The user's personal knowledge base in this workspace: private pages only they can see (their notes, experience, cases, 1:1s), colleagues' private pages shared with them (read-only), and the ones they shared with the workspace. Only for the user's own sign-in; ask and search already include these pages for them.

tag

create_pagewrite

Create a new markdown page. Search first to avoid duplicates, and follow the workspace's agent handbook (get_handbook). Link related pages with [[Page title]]. The page is attributed to you (an agent) in the activity log.

title*, body*, space, tags, owner, description, private

update_pagewrite

Replace a page's title, body, space, tags or owner. Prefer append_to_page for adding notes. Include a short summary of what changed and why.

page*, title, body, space, tags, owner, description, summary*

append_to_pagewrite

Append markdown to the end of a page (e.g. an incident timeline entry, meeting notes, a new FAQ).

page*, text*, summary

get_indexread

The whole workspace at a glance: every page by space with a one-line summary, owner, review state and its links, plus decisions, record collections, the agent handbook and the number of open knowledge gaps. Read this first to find your way around, instead of many searches.

get_handbookread

The workspace's conventions for people and AI assistants: where things go, how to write, what to check before changing something. Follow it when you write.

list_gapsread

Questions people and assistants asked that this workspace couldn't answer, most asked first. Each says whether the workspace can answer it now. Good work for an agent: help write the missing pages (ask a person for the facts).

limit

save_answerwrite

File a good answer back into the workspace as a page, so the next person (or agent) finds it. Use after you composed an answer from `ask` sources that people will need again. Include the sources you cited (page titles become [[links]]). The page waits for a person to review it. An answer that cites the user's private pages is saved privately, in their personal knowledge base.

question*, answer*, sources, title, space

propose_changeswrite

Propose updates to every page one source affects (a meeting, a document, a URL), as one changeset a person reviews in Groundtruth. Nothing changes until they accept. Use this instead of update_page when a source touches several pages. Read each page with get_page first; give its full new body, changing only what the source supports, and one line on why. To add a page nobody has written, give title instead of page. At most 15 changes.

source*, summary, changes*

list_changesread

Changesets proposed from sources (propose_changes), newest first, with what was accepted, rejected or conflicted. Check this before proposing the same source again.

status, limit

researchread

For questions where a probably-right answer isn't good enough (contracts, money, compliance, commitments to customers). Starts the workspace's Research Agent: several rounds with the strongest model at maximum effort, where every claim must quote its source word for word and survive a sceptical check. Takes minutes. Returns a research id: call get_research with it until status is done, then give the user the verdict (verified, partial or not_verified) and its reasons along with the answer. Needs the Research Agent switched on and the workspace's own AI key.

question*

get_researchread

Progress and, when done, the result of a research question started with research: the verdict and its reasons, the answer built only from verified claims, each claim's exact quotes, the claims that were dropped and why, and the sources with any cautions (unreviewed or outdated pages). Poll every 20-30 seconds while status is running.

id*

list_decisionsread

List the decision log (newest first): what was decided, why, by whom, and status.

status, tag

log_decisionwrite

Record a decision with its context so humans and agents can later ask 'why is it like this?'. Use status 'proposed' if a human still needs to approve it.

title*, decision*, context, status, owner, date, tags

query_recordsread

Query structured records (e.g. customers, metrics, people, vendors). `where` supports exact match {field: value} or operators {field: {gt|gte|lt|lte|contains: value}}. `sort` is a field name, prefix '-' for descending. Call without collection to list collections.

collection, where, sort, limit

upsert_recordwrite

Create a record, or update it if one with the same collection+title (or id) exists. Fields are merged.

collection*, title*, fields, id

get_activityread

Recent changes in the workspace, newest first, with who made them and whether they were a human or an agent.

limit, actor_type

list_alertsread

Open alerts raised by the workspace's agents (contract deadlines, churn risk, stale pages), most urgent first. Check this when asked what needs attention.

status, agent, limit

resolve_alertwrite

Mark an alert resolved (handled) or dismissed (not relevant), with a short note on what was done.

alert_id*, status, note

list_agentsread

The Agent Store: which agents exist, which are installed in this workspace, their settings and last run.

run_agentwrite

Run an installed agent immediately (they also run daily). Returns its summary and any new alerts. New alerts may be posted to the workspace's alert webhook (e.g. Slack) if one is set.

agent*

log_interactionwrite

Record an interaction with a customer (meeting, email, ticket, call, NPS response). Feeds the Churn Agent's risk scores.

customer*, type, date, sentiment, nps, summary*

list_tasksread

Cards on the workspace's kanban board, by priority. Filter by status (todo, doing, blocked, review, done) and assignee (a person's name, an agent's name like 'Claude', 'me', or 'unassigned'). Check your own column with assignee='me'. `stale: true` marks work stuck in progress for 6h+.

status, assignee, assignee_type, limit

create_taskwrite

Add a card to the board. Assign it to a person (their name) when a human must act (e.g. buy a domain, approve spend), or to an agent by name. Put clear, step-by-step instructions in the description.

title*, description, assignee, assignee_type, status, priority, due

update_taskwrite

Move a card (status), reassign it, edit it, or add a comment in the same call. Statuses: todo, doing, blocked, review, done. Agents can move cards up to 'review'; only people can mark them 'done'.

task_id*, status, assignee, assignee_type, title, description, priority, due, comment

comment_taskwrite

Add a progress note, question or result to a card.

task_id*, text*

whoamiread

Which workspace this call acts in, who you are acting as, whether you can write there, and which other workspaces this connection can use.

list_workspacesread

The workspaces this connection can use, with your role in each and which one is the default. Pass a workspace's slug as `workspace` to any tool to act there.

Keeping the knowledge base whole

  • Page links: write [[Page title]] or [[Page title|text]]. Pages show what links to them; links to pages nobody wrote yet open a new page with that title. get_page returns links_to, links_to_missing and linked_from.
  • Index: get_index returns every page by space with a one-line summary (its description, or its first sentence), owner, review state and links, plus decisions, record collections and open gaps.
  • Agent handbook: one page of conventions per workspace. Assistants receive it in the MCP initialize instructions and with get_handbook.
  • Knowledge gaps: when ask finds nothing, the question is recorded (never who asked) and the response says so. list_gaps lists them, most asked first; a gap closes when Ask can answer it or a page with that title is written.
  • Saved answers: save_answer files an answer as a page in Answers, with its sources as links, waiting for review. People use Save as page under an answer.

Ingest a source: /ingest

One source (a meeting, an email, a document, a link) often changes several pages. The ingest prompt has your assistant read it, find every page it affects and propose all the edits at once, for a person to review. MCP clients show prompts as slash commands: in Claude Code, type / and pick ingest from your Groundtruth connection (for example /mcp__groundtruth__ingest Weekly sync 14 Oct); in Claude, add it from your Groundtruth connector in the + menu.

  • Source: paste text, give a URL (the assistant fetches it), or give the title of a page in Groundtruth, such as a meeting filed from Wispr Flow or Plaud; that page is sent along with the prompt.
  • Proposal: the assistant calls propose_changes with the full new body of each page and one line on why, up to 15 changes, including new pages. Nothing changes yet.
  • Review: Proposed changes in the app shows each change as a diff. Accept or reject them one by one or all at once. Accepted edits are applied in the reviewer's name, as checked by a person.
  • Conflicts: if someone edited a page after the proposal, accepting it never overwrites their edit; the change is marked as a conflict instead.
  • Knowledge gaps: the fill_gaps prompt works through questions nobody could answer and proposes the missing pages, asking you for facts it can't find.

Personal knowledge base

Every member has private pages in each workspace (My knowledge in the app). They are stored apart from the workspace, so only their person reaches them: in the app, or through an assistant connected as that person (an OAuth sign-in from Claude, ChatGPT or Gemini). Workspace API keys, agents in the Agent Store and other people's connections never see them.

  • For the person: ask, search, get_page and get_index include their private pages, marked "private": true. Private page ids start with pp_.
  • Writing: create_page with private: true; update_page and append_to_page work on private pages; list_my_pages lists them. save_answer keeps an answer private when it cites a private page.
  • Sharing with colleagues: the person picks members who may read a private page. It stays private: for those colleagues, ask, search and get_page include it, read-only, with shared_by; list_my_pages lists it under shared_with_me. Only the person changes it or who sees it.
  • Sharing with everyone: only the person, in the app. A shared page moves into the workspace with shared_by set; only that person (or their own assistant) can change it, and they can make it private again. Workspace owners can still move it to the trash.
  • Gaps: questions about yourself (I, me, my, ik, mijn) are never recorded as knowledge gaps, and an answer from private pages doesn't close a team gap.
  • Leaving: when someone leaves or is removed, their private pages in that workspace are deleted (including what they shared with colleagues) and they lose what colleagues shared with them; pages they shared with everyone stay as ordinary pages.

Research Agent: checked answers

For questions where probably right isn't enough. Install the Research Agent from the Agent Store (it needs the workspace's own AI key), then use Research thoroughly under Ask, or the research tool and get_research to collect the result. It runs Karpathy's autoresearch loop on a question: plan, read whole sources, draft, check, keep only what passes, search again for what's missing.

  • Model: your supplier's strongest model (or the workspace model, if you choose), always at maximum effort, with long outputs streamed. Up to 5 rounds (default 3); 20 questions per hour per workspace; never on the free credit.
  • Checks in code: every quote must appear word for word in its source (markdown, spacing and quote marks aside), and every number a claim states must be in its quotes.
  • Sceptical review: a second call checks each quote really says what the claim says, looks for contradicting sources and decides what's still missing.
  • Verdict, decided in code: verified only when the direct answer passed, nothing is missing, no sources disagree and nothing rests on an unreviewed or outdated page; otherwise partial with reasons, or not_verified with no answer.
  • Privacy: it can use the asker's private pages, so only the asker (or the API key that started it) can read a job. Each person keeps their latest 20; older ones are deleted.

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

  • Three roles per workspace: readers read, search and ask and see who has access; makers also write; owners also manage settings, keys, members and roles. An AI assistant someone connects can do exactly what that person can, and role changes apply immediately.
  • 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.