MCP: Contatos
Buscar, criar e editar contatos (e contatos brutos) pelo MCP. 10 ferramentas.
Ferramentas desta área, geradas do código do servidor. As descrições vêm desse código, em português. Para conectar, veja o MCP da XBASE.
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).
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
workspaceId | sim | ID do workspace |
createdAtFrom | não | Data/hora mínima de criação (ISO 8601, ex: 2026-06-22T03:00:00.000Z) |
createdAtTo | não | 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.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
name | sim | Nome completo do contato (obrigatório) |
email | não | Email do contato (deve ter formato válido: usuario@dominio.com) |
phone | não | Telefone do contato (qualquer formato: +55 11 99999-9999) |
company | não | Nome da empresa do contato |
position | não | Cargo/Posição do contato na empresa |
industry | não | Setor/Indústria da empresa |
source | não | Origem do contato (ex: Google Ads, Indicação, LinkedIn) |
status | não | Status do lead (ex: cold, warm, hot). Padrão: cold |
notes | não | 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 | não | Pontuação do lead (0-100). Padrão: 0 |
lastContact | não | Data do último contato (formato ISO: 2025-01-15) |
nextFollowUp | não | Data do próximo follow-up (formato ISO: 2025-01-20) |
linkedinUrl | não | URL do perfil LinkedIn do contato |
website | não | Website da empresa do contato |
location | não | Localização do contato (ex: São Paulo, SP) |
size | não | Tamanho da empresa (ex: 1-10, 11-50, 51-200) |
budget | não | Orçamento disponível (ex: R$ 10.000 - R$ 50.000) |
timeline | não | Timeline do projeto (ex: Q1 2025, Imediato) |
niche | não | Nicho de mercado (ex: SaaS B2B, E-commerce) |
placeId | não | ID único do Google Places (para localização) |
organizationId | não | ID da organização (empresa) do mesmo workspace — search-organizations / create-organization |
metadata | não | Metadados adicionais em formato JSON |
photoUrl | não | URL da foto do contato (deve ser uma URL válida: https://exemplo.com/foto.jpg) |
workspaceId | sim | ID único do workspace onde o contato será armazenado |
threadId | não | 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)
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
workspaceId | sim | ID único do workspace onde os contatos estão armazenados |
name | não | Nome do contato para filtrar (busca parcial - encontra "João" em "João Silva") |
email | não | Email exato do contato para filtrar (busca exata) |
phone | não | Telefone do contato para filtrar (busca parcial - encontra "9999" em "11999999999") |
search | não | Termo de busca geral que procura simultaneamente em nome, email e telefone |
limit | não | 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.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
contactId | sim | ID único do contato a ser atualizado |
name | não | Novo nome do contato (máximo 255 caracteres) |
email | não | Novo email do contato (deve ter formato válido: usuario@dominio.com) |
phone | não | Novo telefone do contato (máximo 20 caracteres) |
company | não | Nova empresa do contato |
position | não | Novo cargo/posição do contato |
industry | não | Novo setor/indústria |
source | não | Nova origem do contato |
status | não | Novo status do lead (ex: cold, warm, hot) |
notes | não | 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 | não | Nova pontuação do lead (0-100) |
lastContact | não | Nova data do último contato (formato ISO: 2025-01-15) |
nextFollowUp | não | Nova data do próximo follow-up (formato ISO: 2025-01-20) |
linkedinUrl | não | Nova URL do perfil LinkedIn |
website | não | Novo website da empresa |
location | não | Nova localização do contato |
size | não | Novo tamanho da empresa |
budget | não | Novo orçamento disponível |
timeline | não | Nova timeline do projeto |
niche | não | Novo nicho de mercado |
placeId | não | Novo ID do Google Places |
organizationId | não | ID da organização (empresa) do mesmo workspace; null desliga |
metadata | não | Novos metadados em formato JSON |
photoUrl | não | Nova URL da foto do contato (deve ser uma URL válida: https://exemplo.com/foto.jpg) |
workspaceId | não | Novo ID do workspace do contato (para migrar entre workspaces) |
threadId | não | 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.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
contacts | sim | 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.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
rawContactId | sim | ID do raw-contact a ser convertido (UUID obrigatório) |
threadId | não | ID da thread existente para vincular ao novo contact (opcional) |
photoUrl | não | URL da foto do contato (opcional, não existe em raw-contact) |
deleteRawOnSuccess | não | Se true, deleta o raw-contact após criar o contact com sucesso |
agent | sim | — |
create-raw-contact
Cria lead com dados completos (empresa, cargo, indústria, score). Valida email e URLs. Use para prospecção e CRM.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
name | sim | Nome do raw contact (obrigatório) |
email | não | Email do raw contact (formato válido) |
phone | não | Telefone do raw contact |
company | não | Empresa do raw contact |
position | não | Cargo/posição do raw contact |
industry | não | Indústria do raw contact |
source | não | Fonte do raw contact |
status | não | Status do raw contact (padrão: "cold") |
notes | não | Notas sobre o raw contact |
score | não | Score do raw contact (padrão: 0) |
lastContact | não | Data do último contato (formato ISO) |
nextFollowUp | não | Data do próximo follow-up (formato ISO) |
linkedinUrl | não | URL do LinkedIn (formato válido) |
website | não | Website (formato válido) |
location | não | Localização do raw contact |
size | não | Tamanho da empresa |
budget | não | Orçamento disponível |
timeline | não | Timeline do projeto |
niche | não | Nicho de mercado |
placeId | sim | Place ID do Google Maps (ID único do estabelecimento) - obrigatório |
workspaceId | sim | ID do workspace (UUID válido) |
metadata | não | 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.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
rawContactId | sim | ID do raw contact a ser deletado |
hardDelete | não | 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.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
workspaceId | sim | ID único do workspace onde os raw-contacts estão armazenados (obrigatório) |
limit | não | Número máximo de contatos a retornar (padrão: 10) |
search | não | Termo de busca por nome, email ou empresa |
sort | não | 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.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
id | sim | ID do raw contact a ser atualizado |
name | não | Nome do raw contact |
email | não | Email do raw contact (formato válido) |
phone | não | Telefone do raw contact |
company | não | Empresa do raw contact |
position | não | Cargo/posição do raw contact |
industry | não | Indústria do raw contact |
source | não | Fonte do raw contact |
status | não | Status do raw contact |
notes | não | Notas sobre o raw contact |
score | não | Score do raw contact |
lastContact | não | Data do último contato (formato ISO) |
nextFollowUp | não | Data do próximo follow-up (formato ISO) |
linkedinUrl | não | URL do LinkedIn (formato válido) |
website | não | Website (formato válido) |
location | não | Localização do raw contact |
size | não | Tamanho da empresa |
budget | não | Orçamento disponível |
timeline | não | Timeline do projeto |
placeId | não | Place ID do Google Maps (ID único do estabelecimento) |
workspaceId | não | ID do workspace (UUID válido) |
metadata | não | 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. |