MCP: Contacts
Search, create and edit contacts (and raw contacts) through the MCP. 10 tools.
Tools in this area, generated from the server code. The descriptions come from that code, in Portuguese. To connect, see the XBASE MCP.
count-contacts
Conta contatos de um workspace com filtro opcional por data de criação. Ideal para medir novos clientes em um período (ex: contatos criados ontem = clientes distintos do dia).
| Parameter | Required | Description |
|---|---|---|
workspaceId | yes | ID do workspace |
createdAtFrom | no | Data/hora mínima de criação (ISO 8601, ex: 2026-06-22T03:00:00.000Z) |
createdAtTo | no | Data/hora máxima de criação (ISO 8601, ex: 2026-06-23T03:00:00.000Z) |
create-contact
Cria novo contato com informações detalhadas e, opcionalmente, vincula a uma thread existente via threadId. Retorna os dados do contato e do vínculo realizado.
| Parameter | Required | Description |
|---|---|---|
name | yes | Nome completo do contato (obrigatório) |
email | no | Email do contato (deve ter formato válido: usuario@dominio.com) |
phone | no | Telefone do contato (qualquer formato: +55 11 99999-9999) |
company | no | Nome da empresa do contato |
position | no | Cargo/Posição do contato na empresa |
industry | no | Setor/Indústria da empresa |
source | no | Origem do contato (ex: Google Ads, Indicação, LinkedIn) |
status | no | Status do lead (ex: cold, warm, hot). Padrão: cold |
notes | no | Anotações sobre a pessoa (o que disse, combinados). Pesquisa e dados da empresa não vão aqui: use create-organization/update-organization |
score | no | Pontuação do lead (0-100). Padrão: 0 |
lastContact | no | Data do último contato (formato ISO: 2025-01-15) |
nextFollowUp | no | Data do próximo follow-up (formato ISO: 2025-01-20) |
linkedinUrl | no | URL do perfil LinkedIn do contato |
website | no | Website da empresa do contato |
location | no | Localização do contato (ex: São Paulo, SP) |
size | no | Tamanho da empresa (ex: 1-10, 11-50, 51-200) |
budget | no | Orçamento disponível (ex: R$ 10.000 - R$ 50.000) |
timeline | no | Timeline do projeto (ex: Q1 2025, Imediato) |
niche | no | Nicho de mercado (ex: SaaS B2B, E-commerce) |
placeId | no | ID único do Google Places (para localização) |
organizationId | no | ID da organização (empresa) do mesmo workspace — search-organizations / create-organization |
metadata | no | Metadados adicionais em formato JSON |
photoUrl | no | URL da foto do contato (deve ser uma URL válida: https://exemplo.com/foto.jpg) |
workspaceId | yes | ID único do workspace onde o contato será armazenado |
threadId | no | ID da thread existente para atrelar ao contato (opcional) |
get-contact
Busca contatos por nome, email, telefone ou termo geral. Retorna ID, nome, email, telefone e foto. Use para localizar contatos específicos ou listar todos os contatos do workspace (basta fornecer apenas o workspaceId sem outros filtros). (Contatos é diferente de raw-contacts)
| Parameter | Required | Description |
|---|---|---|
workspaceId | yes | ID único do workspace onde os contatos estão armazenados |
name | no | Nome do contato para filtrar (busca parcial - encontra "João" em "João Silva") |
email | no | Email exato do contato para filtrar (busca exata) |
phone | no | Telefone do contato para filtrar (busca parcial - encontra "9999" em "11999999999") |
search | no | Termo de busca geral que procura simultaneamente em nome, email e telefone |
limit | no | Número máximo de contatos a retornar (padrão: 20, máximo: 100) |
update-contact
Atualiza contato existente com relatório detalhado de mudanças. Valida email, URLs e datas. Use para corrigir dados, atualizar qualificação ou migrar entre workspaces.
| Parameter | Required | Description |
|---|---|---|
contactId | yes | ID único do contato a ser atualizado |
name | no | Novo nome do contato (máximo 255 caracteres) |
email | no | Novo email do contato (deve ter formato válido: usuario@dominio.com) |
phone | no | Novo telefone do contato (máximo 20 caracteres) |
company | no | Nova empresa do contato |
position | no | Novo cargo/posição do contato |
industry | no | Novo setor/indústria |
source | no | Nova origem do contato |
status | no | Novo status do lead (ex: cold, warm, hot) |
notes | no | Novas anotações sobre a pessoa (o que disse, combinados). Pesquisa e dados da empresa não vão aqui: use update-organization na organização do contato |
score | no | Nova pontuação do lead (0-100) |
lastContact | no | Nova data do último contato (formato ISO: 2025-01-15) |
nextFollowUp | no | Nova data do próximo follow-up (formato ISO: 2025-01-20) |
linkedinUrl | no | Nova URL do perfil LinkedIn |
website | no | Novo website da empresa |
location | no | Nova localização do contato |
size | no | Novo tamanho da empresa |
budget | no | Novo orçamento disponível |
timeline | no | Nova timeline do projeto |
niche | no | Novo nicho de mercado |
placeId | no | Novo ID do Google Places |
organizationId | no | ID da organização (empresa) do mesmo workspace; null desliga |
metadata | no | Novos metadados em formato JSON |
photoUrl | no | Nova URL da foto do contato (deve ser uma URL válida: https://exemplo.com/foto.jpg) |
workspaceId | no | Novo ID do workspace do contato (para migrar entre workspaces) |
threadId | no | ID da thread para associar ao contato |
bulk-create-raw-contacts
Cria múltiplos raw contacts em lote (até 100). Valida cada item e retorna relatório de sucessos/erros. Use para criar múltiplos raw contacts.
| Parameter | Required | Description |
|---|---|---|
contacts | yes | Array de contatos para criar (máximo 100 por vez) |
convert-raw-contact-to-contact
Converte um raw-contact (lead de prospecção) em contact (cliente ativo). Busca o raw-contact pelo ID, cria um novo contact com todos os dados e opcionalmente vincula a uma thread. Retorna o novo contact criado.
| Parameter | Required | Description |
|---|---|---|
rawContactId | yes | ID do raw-contact a ser convertido (UUID obrigatório) |
threadId | no | ID da thread existente para vincular ao novo contact (opcional) |
photoUrl | no | URL da foto do contato (opcional, não existe em raw-contact) |
deleteRawOnSuccess | no | Se true, deleta o raw-contact após criar o contact com sucesso |
agent | yes | — |
create-raw-contact
Cria lead com dados completos (empresa, cargo, indústria, score). Valida email e URLs. Use para prospecção e CRM.
| Parameter | Required | Description |
|---|---|---|
name | yes | Nome do raw contact (obrigatório) |
email | no | Email do raw contact (formato válido) |
phone | no | Telefone do raw contact |
company | no | Empresa do raw contact |
position | no | Cargo/posição do raw contact |
industry | no | Indústria do raw contact |
source | no | Fonte do raw contact |
status | no | Status do raw contact (padrão: "cold") |
notes | no | Notas sobre o raw contact |
score | no | Score do raw contact (padrão: 0) |
lastContact | no | Data do último contato (formato ISO) |
nextFollowUp | no | Data do próximo follow-up (formato ISO) |
linkedinUrl | no | URL do LinkedIn (formato válido) |
website | no | Website (formato válido) |
location | no | Localização do raw contact |
size | no | Tamanho da empresa |
budget | no | Orçamento disponível |
timeline | no | Timeline do projeto |
niche | no | Nicho de mercado |
placeId | yes | Place ID do Google Maps (ID único do estabelecimento) - obrigatório |
workspaceId | yes | ID do workspace (UUID válido) |
metadata | no | CRÍTICO: Salve aqui o objeto JSON BRUTO e COMPLETO que veio da fonte original (Google Maps, API, scraping, etc) SEM EDITAR. Inclua TODOS os campos originais: ratings, reviews, opening_hours, photos, types, geometry, formatted_address, etc. NÃO filtre, NÃO remova campos, salve o objeto EXATAMENTE como recebeu. |
delete-raw-contact
Remove lead do sistema (soft delete por padrão, hard delete opcional). Use para limpeza de dados duplicados.
| Parameter | Required | Description |
|---|---|---|
rawContactId | yes | ID do raw contact a ser deletado |
hardDelete | no | Se true, faz hard delete (remoção permanente). Padrão: false (soft delete) |
list-raw-contacts
Lista leads/raw-contacts com filtros opcionais por nicho e busca textual. Retorna ID, nome, email, empresa, nicho e data. Use para monitorar base de leads do workspace. Pode listar todos os raw-contacts do workspace (apenas workspaceId + limit) ou filtrar por nicho ou busca. Raw-contacts são diferentes de contacts regulares.
| Parameter | Required | Description |
|---|---|---|
workspaceId | yes | ID único do workspace onde os raw-contacts estão armazenados (obrigatório) |
limit | no | Número máximo de contatos a retornar (padrão: 10) |
search | no | Termo de busca por nome, email ou empresa |
sort | no | Ordenação por createdAt: "newest" (padrão) ou "oldest" |
update-raw-contact
Atualiza dados de um raw contact existente. Valida campos e mantém integridade dos dados.
| Parameter | Required | Description |
|---|---|---|
id | yes | ID do raw contact a ser atualizado |
name | no | Nome do raw contact |
email | no | Email do raw contact (formato válido) |
phone | no | Telefone do raw contact |
company | no | Empresa do raw contact |
position | no | Cargo/posição do raw contact |
industry | no | Indústria do raw contact |
source | no | Fonte do raw contact |
status | no | Status do raw contact |
notes | no | Notas sobre o raw contact |
score | no | Score do raw contact |
lastContact | no | Data do último contato (formato ISO) |
nextFollowUp | no | Data do próximo follow-up (formato ISO) |
linkedinUrl | no | URL do LinkedIn (formato válido) |
website | no | Website (formato válido) |
location | no | Localização do raw contact |
size | no | Tamanho da empresa |
budget | no | Orçamento disponível |
timeline | no | Timeline do projeto |
placeId | no | Place ID do Google Maps (ID único do estabelecimento) |
workspaceId | no | ID do workspace (UUID válido) |
metadata | no | CRÍTICO: Salve o objeto JSON BRUTO e COMPLETO da fonte original SEM EDITAR. Inclua TODOS os campos originais sem modificações. É para armazenar os dados CRU (raw data) exatamente como vieram da pesquisa. |