Documentation

Everything you can do on the website, you can do from Claude, ChatGPT, Microsoft Copilot, the command line, or your own code. Each connection acts as your account, with exactly your permissions. Connecting an assistant takes about two minutes and needs no technical skills. The command line and API are for developers.

Quickstart

How it works

One MCP server (the standard assistants use to connect to tools) and one REST API sit behind every surface. Most people only need the first row.

Every connection sees only what your account can open on the site. Disconnect an assistant or revoke a key at any time from Connectors.

Connect an assistant

You sign in to Groundbook once and click Allow. After that the assistant can read and update your projects, and only yours, until you disconnect it. Some assistants ask for a server address. It is:

https://app.groundbook.ai/api/mcp

Claude

1. Open Groundbook in the Claude directory and click Connect to Claude. Or, inside Claude, open Settings → Connectors, click Browse connectors, search for Groundbook, and click Connect.
2. A Groundbook page opens. Sign in if asked, then click Allow.
3. Start a new chat and ask, for example, “What are the open high-severity issues on my latest project?” The first time, Claude asks permission to use each tool; click Allow.

If you cannot find the listing, add it by hand: Settings → Connectors → Add custom connector, name it Groundbook, and paste the address above.

ChatGPT

Groundbook is under review for the ChatGPT app directory. Until it is listed, add it by hand. ChatGPT calls this developer mode.

1. In ChatGPT, open Settings → Apps & Connectors → Advanced settings and turn on Developer mode.
2. Back in Apps & Connectors, click Create. Name it Groundbook, paste the address above as the server URL, choose OAuth for authentication, and click Create.
3. Sign in and click Allow. In a new chat, open the tools menu, pick Groundbook, and ask your question.

Microsoft Copilot

This is done in Copilot Studio, where Microsoft 365 agents are built. If you cannot open it, ask your Microsoft 365 admin for access.

1. In Copilot Studio, open your agent, click + next to Tools, choose Add → Model Context Protocol, and paste the address above with a name and description.
2. For authentication choose OAuth 2.0 → Dynamic (with discovery). Copilot registers itself with us; there is nothing to copy.
3. Create the connection: sign in and click Allow. Then click Add to attach the tool and Save the agent. Try a question in the Preview pane and allow the first tool calls.

Claude Code, Cursor, and other local agents

For developers. Install the CLI, sign in with an API key, and run it as a local MCP server over stdio.

npx @groundbook/cli login

Then add it to your agent’s MCP servers:

{
  "mcpServers": {
    "groundbook": {
      "command": "npx",
      "args": [
        "-y",
        "@groundbook/cli",
        "mcp"
      ]
    }
  }
}

Command line

For developers. The gb command runs every tool from a terminal. Create an API key in Connectors → API keys, then sign in once. Output is JSON.

npx @groundbook/cli login            # paste an API key from Connectors → API keys
gb list_projects
gb list_issues --project-id PROJECT_ID --severity High --status open
gb get_issue --issue-id ISSUE_ID
gb create_project --address "12 Main St"
gb upload plans.pdf --project PROJECT_ID
gb start_check --project-id PROJECT_ID
gb ask --project-id PROJECT_ID --question "Which sheets have unresolved conflicts?"

Commands

Every tool in the tool list is also a command with the same name. Commands that delete something ask you to confirm; pass --yes in scripts. A read-only key cannot change anything.

Scripts and automation

Set GROUNDBOOK_API_KEY instead of running gb login, and pass --json for one-line output that pipes into jq.

export GROUNDBOOK_API_KEY=gb_...      # no login step needed

PROJECT_ID=$(gb create_project --address "12 Main St" --json | jq -r .projectId)
gb upload plans.pdf --project "$PROJECT_ID"
gb start_check --project-id "$PROJECT_ID"

gb export_issues --project-id "$PROJECT_ID" --format report --json
gb download-export EXPORT_ID --out issues.pdf
gb delete_project --project-id "$PROJECT_ID" --yes

REST API

Every route the website uses accepts an API key, so your own code can do anything the site can. The base URL is https://app.groundbook.ai. Bodies are JSON, ids are UUIDs, and times are ISO 8601 in UTC. The API reference lists each route with its parameters and examples for curl and gb.

Authentication

Create an API key in Connectors → API keys and send it in the Authorization header as a bearer token. A read-only key can call GET routes only. Keys never carry admin powers, and you can revoke one at any time.

curl "https://app.groundbook.ai/api/auth/me" \
  -H "Authorization: Bearer $GROUNDBOOK_API_KEY"

curl "https://app.groundbook.ai/api/checks/CHECK_ID/issues" \
  -H "Authorization: Bearer $GROUNDBOOK_API_KEY"

Errors are JSON with one plain-English error message. The status codes are in the reference.

OAuth for assistants

Assistants authenticate with OAuth 2.1 instead of a key. An access token works on every route in the same way as a key.

Tools

The same 26 tools back the hosted MCP server, the local MCP server, and the command line. Each one is an action from the website, with the same permissions.

Read tools

Write tools

Assistants ask you before running these. The ones that delete cannot be undone.

Data and privacy

An assistant only receives what it asks for through these tools, for the account that connected it. We never train on your data. Disconnect an assistant at any time from Connectors → AI assistants. See the Privacy Policy and Terms of Service. Questions: support@groundbook.ai.