# Tonic Desk MCP server — setup instructions for AI agents

You are setting up the Tonic Desk CRM MCP server on the user's machine, for
the AI tool you are running in. Follow these steps exactly. Everything is
read-only: the server exposes 19 read tools and no write tools.

## What you need from the user

- Their Tonic Desk API key (starts with `crm_`). They create it at
  https://app.tonicdesk.com/settings/api-keys — Read-only preset. If they
  haven't given you one, ask for it before proceeding. NEVER echo the full
  key back in your replies; refer to it as "your API key".

## Requirements

- Node.js 18 or newer (`node --version`). If missing, install it first
  (https://nodejs.org) or tell the user to.
- No npm install is needed. The server is one self-contained file.

## Step 1 — download the server

Download https://tonicdesk.com/docs/mcp/tonicdesk-mcp.js to a stable local
path, e.g. `~/.tonicdesk/tonicdesk-mcp.js`:

```bash
mkdir -p ~/.tonicdesk && curl -fsSL -o ~/.tonicdesk/tonicdesk-mcp.js https://tonicdesk.com/docs/mcp/tonicdesk-mcp.js
```

## Step 2 — register it with the MCP client you are running in

Identify which client you are, then apply the matching config. In every
case: command `node`, args `[<absolute path to tonicdesk-mcp.js>]`, and an
environment variable `TONICDESK_API_KEY` set to the user's key.

### Claude Desktop

Edit the config file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Merge into the `mcpServers` object (create the file/object if absent —
preserve any existing servers):

```json
{
  "mcpServers": {
    "tonicdesk": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/tonicdesk-mcp.js"],
      "env": { "TONICDESK_API_KEY": "crm_..." }
    }
  }
}
```

Tell the user to restart Claude Desktop after saving.

### Claude Code

```bash
claude mcp add tonicdesk -e TONICDESK_API_KEY=crm_... -- node /ABSOLUTE/PATH/TO/tonicdesk-mcp.js
```

### Cursor

Merge the same server block into `~/.cursor/mcp.json` (global) or
`.cursor/mcp.json` in the project, under `mcpServers`, in the identical
format as Claude Desktop above.

### Any other MCP client

Use its standard stdio-server registration with:
- command: `node`
- args: `["/ABSOLUTE/PATH/TO/tonicdesk-mcp.js"]`
- env: `TONICDESK_API_KEY` = the user's key

Optional env var: `TONICDESK_BASE_URL` — only for self-hosted instances
(default `https://app.tonicdesk.com/api/v1`; leave unset normally).

## Scope — what this connection does and does not cover

The tools reach the organisation's CRM RECORDS only: contacts, companies,
deals, tasks, notes, pipelines, tags, users, custom fields, segments.

Two rules to carry into your answers:
- CRM companies are the accounts the team tracks — not a complete market
  directory. "Not found in the CRM" never means "does not exist".
- Some Tonic Desk workspaces include separate market-data modules. The
  server probes the org's entitlements at startup: when the dealer-data
  module is enabled you will see five extra tools (list_dealers,
  get_dealer, get_dealer_listings, link_dealer_to_company,
  list_nissan_dealers) and the server instructions explain how the two
  universes bridge. When those tools are absent, market/stock/listings
  data is NOT available through this connection — say so rather than
  approximating an answer from CRM records.

## Step 3 — verify

After the client reloads, call the `list_pipelines` tool. A successful
response returns the org's pipelines with their stages. Then tell the user
what you can now see (tools available, e.g. "I can search your CRM, read
contacts, companies, deals, tasks, notes and timelines — read-only").

## Troubleshooting

- **401 invalid_api_key** — key mistyped, revoked, or the account that
  created it was deactivated. Ask the user for a fresh key.
- **403 insufficient_scope** — the key predates some newer read scopes.
  Ask the user to create a fresh Read-only key.
- **429 rate_limited** — wait the number of seconds in the `Retry-After`
  header. Limit is 60 requests/minute per key; prefer `search_crm` over
  paging through whole lists.
- **Server won't start** — check `node --version` is ≥ 18 and the file
  path in the config is absolute.

## No MCP support? Use the REST API directly

If you cannot register MCP servers but can make HTTP requests or write
scripts, use the REST API with the same key:

```bash
curl -H "Authorization: Bearer crm_..." "https://app.tonicdesk.com/api/v1/search?q=NAME"
```

Full contract: https://app.tonicdesk.com/api/v1/openapi.json (OpenAPI 3.1).
Human docs: https://tonicdesk.com/docs/api-reference/

## Rules

- Never write the API key into a file other than the MCP client's own
  config, never commit it to a repository, never print it in full.
- This connection is read-only. If the user asks you to modify CRM data
  through it, explain that writes need a Full-access key and the REST API,
  and that the MCP connection deliberately cannot write.