# CRM MCP e REST API — how to use (mcp.ai)

Your own CRM, fully customizable and agent-driven. Start with contacts, companies and a sales pipeline, then create your own objects and fields and get an API instantly. You own all the data, isolated in a database of your own. Pay only for what you store and use.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_crm?ms=1781685060000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `crm_add_field`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/crm`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/crm/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/crm/add/field` — Adiciona um CAMPO custom a um objeto (sem migração; registros antigos ficam sem a key). Tipos: string text integer float boolean date datetime singleselect multiselect email phone url currency relatio
  - body: { object: string, key: string, label?: string, type: string, required?: boolean, unique?: boolean, indexed?: boolean, options?: string, relation?: string, account?: string }
- `POST https://api.mcp.ai/api/crm/confirm/upload` — Confirma o upload depois do PUT na upload_url (o storage valida o tamanho real). Marca o arquivo como pronto e contabiliza no uso.
  - body: { file_id: string, account?: string, file_ids?: string[] }
- `POST https://api.mcp.ai/api/crm/create/records` — Cria um registro (ou vários) de um objeto. Passe `object` (ex.: 'contact', 'deal') e `data` (objeto JSON com os campos por key). Para vários, use `records` (array JSON de {data}).
  - body: { object: string, data?: string, metadata?: string, records?: string, account?: string }
- `POST https://api.mcp.ai/api/crm/define/object` — Cria um OBJETO custom no CRM (além de contact/company/deal) e ganha CRUD/API automático. Passe `key` (api name, a-z/0-9/_), `label` e opcionalmente `fields` (array JSON de definições de campo).
  - body: { key: string, label?: string, module?: string, display_field?: string, fields?: string, account?: string }
- `POST https://api.mcp.ai/api/crm/delete/file` — Remove um ou mais arquivos (apaga do storage e libera o espaço contabilizado).
  - body: { ids?: string[], file_id?: string, account?: string }
- `POST https://api.mcp.ai/api/crm/delete/object` — Remove um objeto CUSTOM (objetos de sistema não podem ser removidos). Se houver registros, passe delete_records:true para apagar tudo junto.
  - body: { object: string, delete_records?: boolean, account?: string }
- `POST https://api.mcp.ai/api/crm/delete/records` — Remove um ou mais registros de um objeto por id.
  - body: { object: string, ids: string[], account?: string }
- `POST https://api.mcp.ai/api/crm/describe` — Descreve o schema do CRM: todos os objetos (contact, company, deal e quaisquer custom) com seus campos (key, tipo, obrigatório, opções, relações) e o kanban. CHAME ISTO PRIMEIRO para saber quais objet
  - body: { account?: string }
- `POST https://api.mcp.ai/api/crm/download/file` — Gera uma URL presigned de download (GET) pra um arquivo. A URL expira em alguns minutos.
  - body: { file_id: string, account?: string, file_ids?: string[] }
- `POST https://api.mcp.ai/api/crm/get/file` — Metadados de um arquivo (nome, tamanho, content_type, status, anexo).
  - body: { file_id: string, account?: string, file_ids?: string[] }
- `POST https://api.mcp.ai/api/crm/get/object` — Detalha UM objeto: seu rótulo, kanban e todos os campos (key, tipo, obrigatório, opções, relação). Versão focada do crm_describe.
  - body: { object: string, account?: string }
- `POST https://api.mcp.ai/api/crm/get/records` — Busca um ou mais registros de um objeto por id.
  - body: { object: string, ids: string[], account?: string }
- `POST https://api.mcp.ai/api/crm/link/record` — Liga um registro a outro por um campo de relação (ex.: vincular um contato a uma empresa). Para relação 'many' adiciona ao conjunto; para 'single' define o alvo.
  - body: { object: string, id: string, field: string, target_id: string, account?: string, ids?: string[], target_ids?: string[] }
- `POST https://api.mcp.ai/api/crm/list/accounts` — Lista os CRMs conectados neste install. Retorna cada um com id, rótulo e is_default (true quando só há um, não precisa passar `account` nas outras tools).
- `POST https://api.mcp.ai/api/crm/list/files` — Lista os arquivos do CRM (id, nome, tamanho, status). Opcionalmente filtra os anexados a um objeto/registro.
  - body: { object?: string, record_id?: string, account?: string, record_ids?: string[] }
- `POST https://api.mcp.ai/api/crm/list/objects` — Lista os objetos do CRM (key, rótulo, módulo, kanban). Versão enxuta do crm_describe, sem os campos.
  - body: { account?: string }
- `POST https://api.mcp.ai/api/crm/list/records` — Lista registros de um objeto, com filtro/ordenação/paginação. `filter` é um objeto JSON: {campo: valor} ou {campo: {op: valor}} (ops: eq ne gt gte lt lte in nin contains exists).
  - body: { object: string, filter?: string, sort?: string, limit?: integer, offset?: integer, account?: string }
- `POST https://api.mcp.ai/api/crm/move/stage` — Move um registro de um objeto kanban (ex.: deal) para outra etapa do funil. Valida a etapa contra as opções do campo de stage.
  - body: { object: string, id: string, stage: string, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/crm/publish/file` — Torna um arquivo PÚBLICO e devolve uma URL estável (`https://api.mcp.ai/f/<token>`) pra embutir num site (ex.: thumbnail). O objeto continua privado no storage, o token é a chave (revogável com crm_un
  - body: { file_id: string, account?: string, file_ids?: string[] }
- `POST https://api.mcp.ai/api/crm/related/records` — Resolve os registros relacionados de um registro: segue os campos de relação e devolve os registros-alvo (todos, ou só de um `field`).
  - body: { object: string, id: string, field?: string, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/crm/remove/field` — Remove um campo CUSTOM (soft-delete: some do schema, mas os valores já gravados ficam preservados). Campos de sistema não podem ser removidos.
  - body: { object: string, key: string, account?: string }
- `POST https://api.mcp.ai/api/crm/search` — Busca textual nos registros (por nome/título/valores). Opcionalmente restrita a um `object`.
  - body: { q: string, object?: string, limit?: integer, account?: string }
- `POST https://api.mcp.ai/api/crm/unlink/record` — Desfaz uma relação. Para relação 'many' remove o target_id do conjunto; para 'single' limpa o campo (target_id opcional).
  - body: { object: string, id: string, field: string, target_id?: string, account?: string, ids?: string[], target_ids?: string[] }
- `POST https://api.mcp.ai/api/crm/unpublish/file` — Revoga o link público de um arquivo (o token para de funcionar na hora).
  - body: { file_id: string, account?: string, file_ids?: string[] }
- `POST https://api.mcp.ai/api/crm/update/field` — Edita um campo: rótulo, obrigatório, visível, posição, opções, indexação. Mudança de TIPO só é permitida se for um alargamento seguro (ex.: integer→float); mudança com perda é bloqueada (crie um campo
  - body: { object: string, key: string, type?: string, label?: string, required?: boolean, visible?: boolean, position?: integer, indexed?: boolean, options?: string, account?: string }
- `POST https://api.mcp.ai/api/crm/update/object` — Edita um objeto: rótulo, campo de exibição, módulo ou config de kanban (a key é imutável). Vale para objetos de sistema e custom.
  - body: { object: string, label?: string, display_field?: string, module?: string, kanban?: string, account?: string }
- `POST https://api.mcp.ai/api/crm/update/records` — Atualiza um registro (merge parcial) por id. Passe `object`, `id` e `data` (só os campos a mudar; null apaga o campo). Para vários, use `updates` (array JSON de {id, data}).
  - body: { object: string, id?: string, data?: string, metadata?: string, updates?: string, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/crm/upload/file` — Inicia o upload de um arquivo (até 200 MB) e devolve uma URL presigned (`upload_url`) pra fazer o PUT direto no storage, mais o `file_id`. Depois do PUT, chame crm_confirm_upload. Opcional: anexe a um
  - body: { filename: string, size: integer, content_type?: string, object?: string, record_id?: string, account?: string, record_ids?: string[] }
- `POST https://api.mcp.ai/api/crm/upload/from/url` — Sobe um arquivo A PARTIR DE UMA URL (a plataforma baixa e armazena, até 200 MB) — o jeito do AGENTE subir via API sem segurar os bytes. Devolve o arquivo já pronto. Opcional: anexe a um registro com o
  - body: { url: string, filename?: string, content_type?: string, object?: string, record_id?: string, account?: string, record_ids?: string[] }
- `POST https://api.mcp.ai/api/crm/usage` — Uso de storage deste CRM: bytes do banco + bytes de arquivos, total em GB, nº de arquivos e egress acumulado. É a base do que é cobrado (storage GB-mês + egress).
  - body: { account?: string }

## Example prompts
- "List my open deals in the pipeline"
- "Create a contact Ada Lovelace with email ada@math.org"
- "Add a custom field 'source' to contacts"

## More
- Page: https://mcp.ai/crm
- Agent spec (llms.txt): https://mcp.ai/crm/llms.txt
- Postman collection: https://mcp.ai/crm/postman.json