Documentation

Everything you can do on the website, you can do from Microsoft Copilot, Claude, ChatGPT, Gemini, Grok, 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

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

1. Open Groundbook in the Claude directory and click Connect to Claude. Or, inside Claude, open Customize → Connectors, click Discover, search for Groundbook, and click Connect.
2. A Groundbook page opens. Sign in if asked, then click Allow.
3. Upload your drawings and start a check in Groundbook.
4. Paste this prompt into a new Claude chat to go through the results:
   PromptCopy

   Show me the issues Groundbook found on my latest project, most severe first, each with its link, and help me go through them. If its check is still running, tell me how far along it is. If I have no project yet, give me the link to upload my drawings and start a check in Groundbook.

5. Claude asks before every Groundbook action. To skip the prompts, open Customize → Connectors → Groundbook and set both tool groups to Always allow.

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

ChatGPT

1. Open Groundbook in ChatGPT and click Install plugin.
2. Create a Groundbook account, or sign in to your existing account, then click Allow.
3. Start a new ChatGPT chat, select @Groundbook, and paste this prompt to find the right tool and start your first project:
   First project promptCopy

   Use Groundbook. In a few lines, tell me what it can do for me, with a link to each: plan review, shop drawing and submittal review, quantity takeoff, Recheck, Smart Overlay, and site plans. Then give me the link to start my first project.

Upload new drawings on the project page ChatGPT links to, then start the check there. Return to ChatGPT to go through the findings.

Already have a project? Connect the same account you use here, then ask:

Show me the issues Groundbook found on my latest project, most severe first, each with its link, and help me go through them. If its check is still running, tell me how far along it is. If I have no project yet, give me the link to upload my drawings and start a check in Groundbook.

Gemini

Gemini uses Groundbook in Spark, its agent mode. You need a personal Google account in the US with Google AI Pro or Ultra; Google does not let work or school accounts add apps yet.

1. Open Connected Apps in Gemini. Under Custom apps for Spark, paste the address above and click Next twice.
2. Tick the box to accept Google’s notice, click Connect, then Agree and continue.
3. A Groundbook page opens. Sign in if asked, then click Allow. Back in Gemini, click Connect.
4. Switch to Spark, type @Groundbook, and ask your question. Gemini asks before each change.

Gemini Enterprise uses Groundbook through an agent. The main chat does not call custom MCP servers yet. First create a client ID and secret. The reply holds client_id and client_secret.

curl -X POST https://app.groundbook.ai/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Gemini Enterprise", "token_endpoint_auth_method": "client_secret_post",
       "redirect_uris": ["https://vertexaisearch.cloud.google.com/oauth-redirect"]}'

1. An admin opens Connected apps in Gemini Enterprise settings and adds an MCP server: the address above, OAuth, the client ID and secret, https://app.groundbook.ai/oauth/authorize as the authorization URL, https://app.groundbook.ai/api/oauth/token as the token URL, and read write as the scopes.
2. Click New agent, then Build manually. Name it Groundbook, tell it to use Groundbook for questions about your projects and issues, turn on Groundbook under Connectors, and click Create. You can upload our logo as its icon.
3. Open the agent and ask your question. The first time, connect Groundbook and click Allow.

Grok

1. Open grok.com/connectors, click New Connector, then Custom.
2. Name it Groundbook, paste the address above as the server URL, and click Add Connector.
3. A Groundbook window opens. Sign in if asked, then click Allow. Ask your question in any chat.

Grok runs tools without asking first, including ones that change or delete things. To keep it read-only, click Groundbook on the connectors page and turn off the write tools.

On Grok Business or Enterprise, an admin adds it for the team first: in console.x.ai, open Grok Business → Connectors → Add Connector → Other and paste the address.

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?"
gb list_project_overlays --project-id PROJECT_ID
gb create_smart_overlay --document-ids DOC_ID_1,DOC_ID_2

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