# ghl-context-mcp

A deliberately small GoHighLevel MCP server. Six tools, scoped to one job:
knowing who you're about to talk to.

## Why this exists

The common failure mode when you put an agent on top of a CRM is a wide, generic
tool surface that dumps raw API JSON: the model picks the wrong tool, burns its
context window on fields no one would ever say out loud, and occasionally
invents or overwrites a record. This server takes the opposite bet. It ships six
tools, each scoped to the moment an agent is about to talk to a contact. Every
field it returns is something a person would say or something the agent passes
back on the next call. It does the date math itself, and it keeps writes off until
you switch them on. The claim that a narrow surface beats a wide one is measurable,
and the companion benchmark (`mcp-tool-surface-bench`) is being built to measure
it.

## The tools

| Tool                    | What it does                                                                        | Kind  | Ceiling |
| ----------------------- | ----------------------------------------------------------------------------------- | ----- | ------- |
| `find_contact`          | Resolve a name, phone, or email to exactly one contact, or return candidates        | read  | 400     |
| `get_contact_timeline`  | Recent calls, SMS, notes, appointments, and stage changes as prose, with a headline | read  | 1200    |
| `get_pipeline_position` | Where each deal sits, days in stage, value, and whether it stalled                  | read  | 500     |
| `get_appointments`      | Upcoming appointments for a contact or calendar, with relative times                | read  | 900     |
| `log_note`              | Write a note, with retry-safe idempotency and an echo of what stored                | write | 200     |
| `move_stage`            | Move a deal to another stage, guarded by a stale-context check                      | write | 250     |

Ceilings are per-response token budgets, enforced by a test that fails the build
when a response grows past them. See [DESIGN.md](DESIGN.md) for what "token" means
here.

## Using it

This is an MCP server, and the intended user is an AI agent, not a person at a
terminal. You connect the server to your agent (Claude Code, Claude Desktop, or any
MCP-capable runtime), then talk to the agent in plain language. The agent is the
one that decides to resolve a contact and pull their context.

### Team quickstart with Claude Code

1. Clone the repo, then install and build:

   ```bash
   npm install && npm run build
   ```

2. Add your credentials:

   ```bash
   cp .env.example .env
   # then edit .env and fill in GHL_PIT and GHL_LOCATION_ID
   ```

3. Open the folder in Claude Code. It reads the checked-in `.mcp.json`, offers the
   `ghl-context` server, and you approve it once. The server loads `.env` on
   startup, so no token ever lives in a config file.

4. Talk to your agent the way a rep would at the start of the day:

   > I'm calling Marcus Halloway and Priya Nair today. Give me a pre-call brief
   > before each one.

   The agent resolves each contact, pulls the timeline, pipeline position, and
   upcoming appointments, and hands back the briefing.

### Other MCP clients

Point any MCP client at the server over stdio. The published package needs no
clone and no build. For Claude Desktop, add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ghl-context": {
      "command": "npx",
      "args": ["-y", "ghl-context-mcp"],
      "env": {
        "GHL_PIT": "pit-...",
        "GHL_LOCATION_ID": "your-sub-account-id"
      }
    }
  }
}
```

To run a local checkout instead of the published package, set `command` to `node`
and `args` to your built `dist/index.js`.

### Environment variables

| Variable               | Required | Default | Meaning                                               |
| ---------------------- | -------- | ------- | ----------------------------------------------------- |
| `GHL_PIT`              | yes      |         | Private Integration Token for one sub-account         |
| `GHL_LOCATION_ID`      | yes      |         | The sub-account id the token belongs to               |
| `GHL_ALLOW_WRITES`     | no       | `false` | Writes refuse unless this is exactly `true`           |
| `GHL_STALL_MULTIPLIER` | no       | `2`     | Stall threshold as a multiple of median time-in-stage |
| `GHL_RESOLVE_STRATEGY` | no       | `fuzzy` | `fuzzy` or `exact` contact retrieval                  |

Create the token under Settings, Integrations, Private Integrations, with the
scopes `contacts.readonly`, `contacts.write`, `opportunities.readonly`,
`opportunities.write`, and `calendars.readonly`.

### Seeing it without a client

If you do not have an MCP client handy, the repo ships a terminal demo that runs
the same sequence an agent would and prints the brief:

```bash
npm run brief -- "Marcus Halloway"
```

It is a demonstration of the value, not the product. The product is the agent
connection above.

### From source

```bash
npm install
npm run build
npm test
```

`npm test` runs green with no credentials. The live checks, `npm run live-check`
and `npm run live-write-check`, need a real `.env`.

## Response shapes

A resolved contact:

```json
{
  "resolution": "exact",
  "contact": {
    "contact_id": "NnAyKFnTSAVKg1amAArO",
    "name": "Marcus Halloway",
    "primary_phone": "+15551230010",
    "primary_email": "marcus.halloway@example.com",
    "tags": ["synthetic-seed"],
    "owner": null,
    "last_activity_at": null,
    "last_activity_summary": null
  }
}
```

An ambiguous match returns candidates instead of guessing:

```json
{
  "resolution": "ambiguous",
  "candidates": [
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230012",
      "primary_email": "jordan.wells@example.com",
      "last_activity_at": null
    },
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230013",
      "primary_email": "jordan.wells.cpa@example.com",
      "last_activity_at": null
    }
  ],
  "disambiguate_by": ["email", "primary_phone"],
  "instruction": "Ask the user which one, or call again with the exact email or phone."
}
```

Ambiguity is treated as a success. An agent that hits an error stops, while one
handed a candidate list keeps going and asks the user which contact they meant.

## Errors

Every error is one shape. No raw HTTP status reaches the model.

| Code                    | When                                                      | Retryable          |
| ----------------------- | --------------------------------------------------------- | ------------------ |
| `CONTACT_NOT_FOUND`     | No contact matched the query                              | no                 |
| `OPPORTUNITY_NOT_FOUND` | No opportunity with that id                               | no                 |
| `STAGE_NOT_IN_PIPELINE` | Target stage is not in the pipeline (lists valid stages)  | no                 |
| `STALE_CONTEXT`         | The asserted current stage does not match live state      | yes, after re-read |
| `MISSING_CONFIRMATION`  | `move_stage` called without `confirm`                     | yes                |
| `WRITES_DISABLED`       | A write was attempted with writes off                     | no                 |
| `SCOPE_MISSING`         | The token lacks a required scope                          | no                 |
| `AUTH_INVALID`          | The token was rejected                                    | no                 |
| `RATE_LIMITED`          | GoHighLevel is throttling (carries `retry_after_seconds`) | yes                |
| `UPSTREAM_ERROR`        | GoHighLevel returned an error                             | yes, once          |
| `WINDOW_TOO_LARGE`      | The requested time window exceeds 365 days                | yes                |

## Design notes

The eight rules the server is built on, one line each. The long version, with the
reasoning an interviewer would ask about, is in [DESIGN.md](DESIGN.md).

1. One job per tool. If the description needs an "and", it is two tools.
2. Descriptions are written for the model: when to use, when not, and the sibling it's confused with.
3. No raw API shapes leave the boundary, enforced by a test.
4. Errors are instructions, in imperative voice, with valid options listed.
5. Every response has a token ceiling, enforced by a build-failing test.
6. The server does the arithmetic: ages, durations, relative times, counts.
7. Writes assert the state they depend on and fail loudly on a mismatch.
8. Writes are off unless `GHL_ALLOW_WRITES=true`.

## What this does not do

Each cut is deliberate.

| Not shipped                                         | Why                                                                                                                           |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `create_contact`, `update_contact`                  | Agents inventing or overwriting records is the top real-world failure. Creation belongs in a form or a human flow.            |
| `send_sms`, `send_email`                            | Outbound messaging under agent control is a compliance surface. A context server has no business shipping it.                 |
| `list_contacts`, multi-filter search                | Unbounded result sets burn a context window. The agent needs one resolved match, not a list.                                  |
| `list_pipelines`, `list_calendars`                  | Schema-discovery tools mostly cost a turn. Names resolve to ids inside the tools, and invalid names return the valid options. |
| Workflow / automation triggers                      | Side effects the server cannot describe in advance or undo afterward.                                                         |
| `get_precall_brief` (a composite of the four reads) | Held back on purpose so the benchmark can test it as a separate arm. If it wins, it ships in v2 with the data behind it.      |

## Limitations

Single location, Private Integration Token auth only, no OAuth. Pagination is
bounded to the per-tool maximums. Stall detection needs volume to be meaningful
and currently uses a fixed fallback because GoHighLevel exposes no stage history.
Phone matching is US-centric. Token ceilings are proxy tokens, not exact Claude
tokens. GoHighLevel reads trail writes by about a second. Tested against one
account shape.

## License

MIT