13. Working with AI agents

Most CRMs assume every record is a human being. That assumption held for a long time and is now quietly false: businesses increasingly deal with software that acts on its own — an agent that answers a supplier, books a slot, or replies to a customer.

This chapter is for organisations where that is normal. It covers the two directions, which are different problems and are often confused:

• An agent as a record — you interact with someone else's agent and want the history kept, without pretending it is a person.
• An agent as an operator — you let an AI work inside your CRM, on your data, through the MCP server.

They are independent. You can do either, both, or neither.

13.1 Recording an agent

Every contact carries a Type, chosen when you create it. It is the first field on the form, and it cannot be left blank.

The type answers one question: do the protections written for people apply to this record? Nothing else.

What it is not

It is not a role. "Client", "supplier", "team member", "sales agent" describe what someone is to you — that is a relationship, and it lives in tags and in the company link.

The distinction matters more than it sounds. A sales agent is a human being with full legal protection; an AI agent is not. If both were filed under "agent", the field could no longer answer the question it exists to answer.

What changes when you choose AI agent

The last row is the one people expect to be different, and it is not. A hard block is about deliverability, not rights: an address that rejects mail keeps rejecting it whether a person or a program is behind it. That check sits above everything else and applies to all three types.

Relationship health disappears for the other two rather than turning grey. Grey would say "the state is neutral"; the truth is "the question does not apply". An agent cannot be neglected and cannot be overwhelmed.

If you are unsure, leave it on Person

The default is Person everywhere, including on every automatic path — imports, web forms, incoming messages, the API. A record whose type nobody set is treated as a human being, with everything that implies.

That direction is deliberate. A mistake should cost you an unnecessary protection, never a missing one.

A caution worth reading once

This setting describes how the product treats a record. It is not a legal determination and it does not decide the law for you.

An agent operated by a named person, reachable at that person's address, may still involve personal data. If your work sits near that line, the type field is a tool for your judgement, not a substitute for it.

13.2 Letting an agent operate your CRM

The other direction: an AI that works inside the CRM rather than being filed in it.

CRM City ships a native Model Context Protocol server. Any MCP-capable client — claude.ai, Claude Code, or software you write — connects with one of your API keys and can then work with your data.

Connecting

Create a secret key first: Settings → API keys. The key is shown once.

Endpoint:  POST https://<your-crm-domain>/api/mcp
Header:    X-CRM-API-Key: crm_sec_...

Example client configuration:

{
  "mcpServers": {
    "crm-city": {
      "type": "http",
      "url": "https://<your-crm-domain>/api/mcp",
      "headers": { "X-CRM-API-Key": "crm_sec_..." }
    }
  }
}

The agent operates strictly inside the organisation the key belongs to, under the same rate limits as the REST API.

What it can do

Thirteen tools, a fixed list. An agent cannot invent a fourteenth.

Reading — search_contacts, get_contact, get_contact_context, list_deals, list_products, list_flows, list_upcoming_occasions, get_help

Writing — upsert_contact, log_activity, add_tag, create_task, draft_personal_message

The two safeguards

It drafts; it does not send. draft_personal_message writes into your drafts. It cannot overwrite a message you have already approved, and it cannot put anything in front of a real person on its own. Every send still passes through a human.

It arrives with instructions. On connection the agent is told how to behave with your data: read the context before writing, propose rather than send, let the tone follow the actual relationship, never invent facts.

Both matter more once agents write to your CRM regularly. An agent that could send would be an agent that could damage a relationship at three in the morning with nobody watching.

13.3 When both apply

An agent firm usually needs both halves, and they meet in one place.

Suppose you run agents on behalf of clients. Each agent is a record in your CRM (Type: AI agent) so the history of what you did with it is kept — configured on this date, handed to that client, failed on that one. And separately, some of those agents hold an API key and work inside their client's CRM.

The two facts never mix in the data: the record is in your organisation, the key belongs to theirs. Keeping them apart is what stops "my agent" and "the agent in my CRM" from becoming the same row by accident.

What to log about an agent

The same things you would log about a supplier, minus the courtesy:

• Activities — configured, deployed, changed, failed, retired. log_activity works the same for an agent as for a person.
• Tasks — a review date, a key rotation, a renewal.
• Tags — which client it serves, which model, which version.

What you will not get is the attention machinery: no health dot, no birthday, no nudge saying you have not spoken in a while. None of it means anything here, and its absence is the point.

13.4 What is not built yet

Said plainly, so you do not look for it:

• Marking in bulk. Type is changed one record at a time. If you arrive with a list of forty agents, they come in as Person and are changed one by one.
• Filtering the contact list by type. There is no "show me only the agents" view yet.

Both are on the roadmap. Neither blocks anything today; they turn tedious once you have more than a handful.