# Groundbreak MCP server
Groundbreak's development database and CRM, for any AI client that speaks MCP. Search permits, deeds, loans and liens in 7 markets, read a project or a company, look up who owns a property and who is behind the LLC, and work your deals.
- Server: `https://crm.groundbreak.city/api/mcp` (Streamable HTTP)
- Auth: sign in with OAuth (the Claude app, ChatGPT and most clients do it for you), or send `Authorization: Bearer <your key>`, or put the key as the last part of the URL
- Make a key: https://crm.groundbreak.city/connect
- These docs: https://crm.groundbreak.city/docs/mcp (this file: https://crm.groundbreak.city/docs/mcp.md)

## Connect

### Claude Code
Run this in a terminal. Every Claude Code session gets Groundbreak. Or leave out the header and run /mcp in Claude Code to sign in instead.
```
claude mcp add --transport http groundbreak https://crm.groundbreak.city/api/mcp \
  --header "Authorization: Bearer <your key>"
```

### Claude app
In Claude on the web or desktop, open Settings, then Connectors, then Add custom connector. Name it Groundbreak and paste this URL.
Claude sends you to Groundbreak to sign in and pick what it can do. Phone and tablet pick it up from your account.
```
https://crm.groundbreak.city/api/mcp
```

### ChatGPT
In ChatGPT, turn on developer mode in Settings, then add a connector with this URL and OAuth. Which plans have developer mode is up to OpenAI.
ChatGPT sends you to Groundbreak to sign in and pick what it can do.
```
https://crm.groundbreak.city/api/mcp
```

### Cursor
Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project.
```
{
  "mcpServers": {
    "groundbreak": {
      "url": "https://crm.groundbreak.city/api/mcp",
      "headers": {
        "Authorization": "Bearer <your key>"
      }
    }
  }
}
```

### VS Code
Add this to .vscode/mcp.json, or run MCP: Open User Configuration to use it in every project. VS Code asks for the key once and keeps it out of the file.
```
{
  "inputs": [
    {
      "type": "promptString",
      "id": "groundbreak-key",
      "description": "Groundbreak key",
      "password": true
    }
  ],
  "servers": {
    "groundbreak": {
      "type": "http",
      "url": "https://crm.groundbreak.city/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:groundbreak-key}"
      }
    }
  }
}
```

### Codex
Put the key in your shell profile, then add the server to ~/.codex/config.toml.
```
# ~/.zshrc or ~/.bashrc
export GROUNDBREAK_KEY="<your key>"

# ~/.codex/config.toml
[mcp_servers.groundbreak]
url = "https://crm.groundbreak.city/api/mcp"
bearer_token_env_var = "GROUNDBREAK_KEY"
```

### Other
Streamable HTTP at this address. A client that signs in with OAuth needs only the URL. Otherwise send the key as a Bearer token, or, for a client that takes only a URL and cannot sign in, put the key at the end of it.
```
URL     https://crm.groundbreak.city/api/mcp
Header  Authorization: Bearer <your key>
Or      https://crm.groundbreak.city/api/mcp/<your key>
```

A key in a URL lives in that client's settings. Treat the URL like a password.

## Tools
Each tool takes JSON arguments as listed. Every result carries app links: show them to the person.

### The database
Permits, deeds, loans, notices of commencement, zoning cases and liens in every market, the projects they belong to and the companies on them. Parties on anything filed in the last 90 days come back with Pro; older records come back whole on any account.

#### `search_records` (Reads)
Search Groundbreak's public-record filings in one market: building permits, deeds, loans, notices of commencement (starts), zoning and site plan cases, liens. Returns up to 25 rows, newest or biggest first, with the true count, the source record and an app link. Parties and phones on filings from the last 90 days come back on Pro; older filings come back whole for everyone.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `market` | austin \| atlanta \| miami \| nashville \| tampa \| charlotte \| dfw | yes | Market: austin (Austin), atlanta (Atlanta), miami (Miami), nashville (Nashville), tampa (Tampa Bay), charlotte (Charlotte), dfw (Dallas-Fort Worth) |
| `q` | string | no | Address, project or scope text |
| `kind` | all \| permits \| instruments \| deeds \| loans \| starts \| cases \| distress | no | instruments is deeds and loans; distress is liens and lis pendens |
| `days` | integer, 1 to 365 | no | Window back from today, default 30; ignored when from is set |
| `from` | date (YYYY-MM-DD) | no | Start date YYYY-MM-DD |
| `to` | date (YYYY-MM-DD) | no | End date YYYY-MM-DD, inclusive |
| `min` | number, 0 or more | no | Minimum dollar value |
| `sort` | date \| value | no | date (default) for the newest, value for the biggest |

#### `search_projects` (Reads)
Find development projects in one market by name or address. Returns status and an id for get_project.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `market` | austin \| atlanta \| miami \| nashville \| tampa \| charlotte \| dfw | yes | Market: austin (Austin), atlanta (Atlanta), miami (Miami), nashville (Nashville), tampa (Tampa Bay), charlotte (Charlotte), dfw (Dallas-Fort Worth) |
| `q` | string | yes | Project name or street address |

#### `get_project` (Reads)
One project's file: status, specs, the team (developer, architect, GC), its filings with values, the owner of record and what changed. Parties and the owner are Pro unless nothing has filed on the project in 90 days, when the file is open to any account.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `market` | austin \| atlanta \| miami \| nashville \| tampa \| charlotte \| dfw | yes | Market: austin (Austin), atlanta (Atlanta), miami (Miami), nashville (Nashville), tampa (Tampa Bay), charlotte (Charlotte), dfw (Dallas-Fort Worth) |
| `id` | id | yes | Project id from search_projects or search_records |

#### `search_companies` (Reads)
Find companies in one market by name: developers, GCs, trade subs, architects and engineers, lenders, owners. Returns their roles, live projects, filings in the last 90 days and 12 months, permit value, deeds and loans, and an app link.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `market` | austin \| atlanta \| miami \| nashville \| tampa \| charlotte \| dfw | yes | Market: austin (Austin), atlanta (Atlanta), miami (Miami), nashville (Nashville), tampa (Tampa Bay), charlotte (Charlotte), dfw (Dallas-Fort Worth) |
| `q` | string | yes | Company name, or part of it |

### Properties and owners
Any Florida property, and the county rolls Groundbreak reads outside Florida. Find the owner, the people behind an LLC (Florida, from Sunbiz), their phones, and the public record on the parcel.

#### `lookup_property` (Reads)
Look up a property by street address, parcel id or folio, or every parcel an owner name holds: any Florida property on the statewide tax roll, and outside Florida any parcel in Travis, Dallas, Tarrant, Fulton, DeKalb, Davidson and Mecklenburg counties on the county rolls Groundbreak reads. Returns the owner, mailing address, use, size, value and last sale. Writes nothing; add_property saves one to the workspace.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `q` | string | yes | A street address with city (and state outside Florida), a parcel id or Miami-Dade folio, or an owner name such as an LLC |

#### `groundbreak_records` (Reads)
The public record for an address or parcel without adding it: appraiser sales, plus what Groundbreak reads in its markets (Miami: permits, trade subs, deeds, construction loans and notices of commencement; Atlanta: permits, planning cases and DeKalb deeds & loans; Nashville: permits, Planning Commission cases and sales; Austin: permits, site plan and zoning cases and TDLR registrations; Tampa Bay: permits, deeds, mortgages and notices of commencement; Charlotte: permits, rezoning petitions and owners of record; Dallas-Fort Worth: permits, deeds of trust, deeds and zoning cases); City of Orlando permits in Orlando. Elsewhere only the appraiser roll.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `q` | string | yes | Street address with city (and state outside Florida), or a parcel id or folio |

#### `add_property` (Changes your CRM)
Add a parcel to the workspace. Pulls the county record and makes the owner an owner record; for a Florida property it reads the owner's Sunbiz filing for the people behind it (free). Returns the property with links. Use the county and parcel_id from lookup_property.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `county` | string | yes | County name as lookup_property returned it, e.g. Miami-Dade, Orange, Travis, Dallas, Fulton |
| `parcel_id` | string | yes | Parcel id exactly as lookup_property returned it |

#### `get_property` (Reads)
A property in the workspace: facts, owner, the people behind the owner, deals, and the public record (sales, deeds, mortgages, liens, lis pendens, permits) with title flags.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `id` | id | yes | Property id |

#### `refresh_property_research` (Changes your CRM)
Re-read the public record for a property in the workspace (appraiser sales, clerk filings, permits). Free.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `id` | id | yes | Property id |

#### `get_owner` (Reads)
An owner (LLC, corporation, trust or person) in the workspace by id or name: its Sunbiz filing, the people behind it with phones and emails, its properties and deals.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `id` | id | no | Owner id |
| `name` | string | no | Owner name, when there is no id |

#### `trace_owner_people` (Changes your CRM)
Read the owner's Sunbiz filing and add the managers, members and officers as contacts, following a managing LLC up to two levels. Free. Run before find_phones when an owner has no people yet.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `owner_id` | id | yes | Owner id |

#### `find_phones` (Spends credits)
Skip trace people for phones and emails, with DNC and TCPA litigator flags. Spends one workspace credit per person found; misses are free; anyone traced in the last 30 days is not charged again. Pass owner_id to trace everyone behind an owner, or contact_ids.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `owner_id` | id | no | · |
| `contact_ids` | list of id | no | · |

#### `sunbiz_lookup` (Reads)
The Florida Division of Corporations filing for an entity by exact name or document number: status, type, filing date, addresses, registered agent and officers. Or, with partial=true, entity names that start with the text.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `name` | string | no | · |
| `doc_number` | string | no | · |
| `partial` | boolean | no | · |

#### `entities_managed_by` (Reads)
Every Florida entity a person or company is listed on as a manager, member or officer: the portfolio behind a name. Names as Sunbiz writes them, e.g. "PINTO, MIGUEL A" or "PINTO MIGUEL A".

| Argument | Type | Required | What it is |
|---|---|---|---|
| `name` | string | yes | · |

### Your CRM
The deals, people, notes and tasks in your workspace. Writes land on the timeline marked as made over MCP.

#### `search_crm` (Reads)
Search this workspace: deals, owners, properties and people by name or address.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `q` | string | yes | · |

#### `list_deals` (Reads)
Deals in the pipeline, optionally one stage or a name search. Stages: prospect, contacted, meeting, proposal, signed, contract, closed, lost (or the workspace's own).

| Argument | Type | Required | What it is |
|---|---|---|---|
| `stage` | string | no | · |
| `q` | string | no | · |

#### `get_deal` (Reads)
One deal: stage, value, property, owner, the people on it with phones, the last 20 timeline entries, open tasks and the title snapshot.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `id` | id | yes | · |

#### `create_deal` (Changes your CRM)
Create a deal in the pipeline, optionally tied to a property, owner and contacts. Stage defaults to the first stage.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `name` | string | yes | · |
| `stage` | string | no | · |
| `side` | listing \| acquisition \| lease \| financing \| other | no | · |
| `value` | number, 0 or more | no | Expected price or deal size in dollars |
| `property_id` | id | no | · |
| `owner_id` | id | no | · |
| `contact_ids` | list of id | no | · |

#### `move_deal` (Changes your CRM)
Move a deal to another stage. Entering Signed or Under contract takes a title snapshot from the county record.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `id` | id | yes | · |
| `stage` | string | yes | Stage key or label |
| `lost_reason` | string | no | · |

#### `add_note` (Changes your CRM)
Log a note, call, email or meeting on a deal, contact, owner or property timeline. Calls, emails and meetings update the contact's last touch.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `body` | string | yes | · |
| `kind` | note \| call \| email \| meeting | no | · |
| `deal_id` | id | no | · |
| `contact_id` | id | no | · |
| `owner_id` | id | no | · |
| `property_id` | id | no | · |

#### `create_task` (Changes your CRM)
Create a task (a call back, a follow-up), optionally due on a date and tied to a deal or contact. Assigned to the caller unless assignee_email names a teammate.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `title` | string | yes | · |
| `due` | string | no | YYYY-MM-DD or an ISO time |
| `deal_id` | id | no | · |
| `contact_id` | id | no | · |
| `assignee_email` | string | no | · |

#### `list_tasks` (Reads)
Tasks in the workspace: open ones by default, the caller's own when mine=true.

| Argument | Type | Required | What it is |
|---|---|---|---|
| `open` | boolean | no | · |
| `mine` | boolean | no | · |

## Markets
| Market | Records | Not in the record | Properties |
|---|---|---|---|
| Austin, TX (`austin`) | permits, site plan and zoning cases and TDLR registrations | sales name buyer and seller with no price; no loans; no notices of commencement; no liens or lis pendens | Properties in Travis County, TX. Naming the people behind an LLC is Florida only. |
| Atlanta, GA (`atlanta`) | permits, planning cases and DeKalb deeds & loans | sales name buyer and seller with no price; no notices of commencement | Properties in Fulton and DeKalb counties, GA. Naming the people behind an LLC is Florida only. |
| Miami, FL (`miami`) | permits, trade subs, deeds, construction loans and notices of commencement | · | Any Florida property, from the statewide roll. The people behind an LLC come from Sunbiz. |
| Nashville, TN (`nashville`) | permits, Planning Commission cases and sales | no loans; no notices of commencement; no liens or lis pendens; no phones on permits | Properties in Davidson County, TN. Naming the people behind an LLC is Florida only. |
| Tampa Bay, FL (`tampa`) | permits, deeds, mortgages and notices of commencement | · | Any Florida property, from the statewide roll. The people behind an LLC come from Sunbiz. |
| Charlotte, NC (`charlotte`) | permits, rezoning petitions and owners of record | no sales; no loans; no notices of commencement; no liens or lis pendens | Properties in Mecklenburg County, NC. Naming the people behind an LLC is Florida only. |
| Dallas-Fort Worth, TX (`dfw`) | permits, deeds of trust, deeds and zoning cases | sales name buyer and seller with no price; no notices of commencement | Properties in Dallas and Tarrant counties, TX. Naming the people behind an LLC is Florida only. |

## Plans, limits and credits
Pro returns the parties on filings from the last 90 days. Without Pro those come back withheld, and older filings come back whole.
| Plan | Tool calls a minute | Tool calls a day |
|---|---|---|
| Pro | 60 | 2,000 |
| Without Pro | 20 | 100 |

Limits count tool calls, per person, across all of that person's keys. Connecting and listing tools are free. Daily limits reset at midnight UTC.
- find_phones spends 1 credit for each person it finds a phone or email for. Misses are free, and anyone traced in the last 30 days is free again.
- Pro ($27 a month) adds 50 credits to your workspace each month. A pack adds 200 for $27 and they keep.
- Every other tool is free. Sunbiz people, phones on permits and owners of record never cost a credit.

## Errors
| What | What it looks like | What to do |
|---|---|---|
| Not signed in, or a wrong, revoked or expired key | HTTP 401 with JSON-RPC error -32001 and a WWW-Authenticate header | A client that signs in starts the sign-in from that header; an expired sign-in refreshes on its own. Otherwise make a key at https://crm.groundbreak.city/connect and check the client sends it. |
| Past the limit | A tool result with isError and "past the fair-use limit of ..." | Wait for the window to reset: a minute, or midnight UTC. For more, email max@groundbreak.city. |
| A read key asked to write | A tool result with isError and "This key reads only" | Use a key with full access for that client. |
| Arguments the tool does not take | A tool result with isError and "Invalid arguments: ..." | The message names the field. The tool list carries each input schema. |
| A refusal meant for you | A result with an error field: an id from another workspace, no credits left | Read it to the person: it says what to do. |
| A failure on our side | A tool result with isError and "That tool failed on our side" | We are told when this happens. Try again in a moment. |

## Keys and safety
- A key, or an app you signed in to, acts as you in the workspace you picked. It reads everything you can.
- With full access it also logs notes, makes and moves deals and spends credits in your name. Read only sees only the tools that read.
- Make one key per client, so you can revoke one without the others. Revoking a key or disconnecting an app stops it at once.
- Your keys, your connected apps and your calls, by day and by tool, are at https://crm.groundbreak.city/connect.

## Protocol
- JSON-RPC 2.0 over HTTP POST. Methods: initialize, ping, tools/list, tools/call. Batches work.
- Answers are plain JSON, never an event stream. No sessions: every request stands alone. GET answers 405.
- Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Server version 1.1.0.
- A result longer than 60,000 characters comes back with its longest lists cut and a `trimmed` note.
- Tools carry readOnlyHint. Tools that change the CRM or spend credits say so in their description: confirm with the person first.
- OAuth 2.1: an unauthenticated request gets a 401 whose WWW-Authenticate names the protected resource metadata (https://crm.groundbreak.city/.well-known/oauth-protected-resource). Authorization server metadata: https://crm.groundbreak.city/.well-known/oauth-authorization-server. Dynamic client registration, the authorization code flow with PKCE (S256 only), scopes mcp:full and mcp:read. Access tokens last 60 minutes; refresh tokens 90 days, replaced on every use.

## Try asking
- The 10 biggest permits filed in Miami in the last 30 days, with the contractor on each
- Mortgages recorded in Tampa in the last 60 days: lender, borrower and amount
- Find the project at an address I give you and list its developer, architect and GC
- What has a company I name filed in Atlanta in the last year?
- Look up an address I give you: who owns it, and who is behind the LLC?
- Which deals in my pipeline have no phone for the owner yet?
- Log a call with the owner on my newest deal and set a follow-up for Friday