Atualizado em Aug 4, 2026

Usando Tipos Personalizados com MCP e IA

O que você vai aprender

• Como os Tipos Personalizados são expostos a agentes de IA e clientes MCP
• Como os agentes descobrem seus tipos e escrevem registros
• Quando adicionar Dicas para MCP para orientar o comportamento do agente

O servidor MCP do AutoTalk permite que qualquer cliente LLM — Claude Desktop, Cursor, ChatGPT, agente customizado — leia e escreva dados da sua empresa por uma interface de ferramentas uniforme. Os Tipos Personalizados são expostos por essa mesma interface.

O que os agentes ganham de graça

Quando você cria um Tipo Personalizado, o servidor MCP expõe automaticamente. Um agente conectado ao seu workspace com uma chave de API válida pode:

• Descobrir seus tipos com list_custom_types
• Ler a forma de um tipo com get_custom_type_definition
• Consultar, criar, atualizar e excluir registros usando as ferramentas genéricas query_documents, get_document, create_document, update_document, delete_document com o identificador ct:<slug>
• Criar novos Tipos Personalizados com create_custom_type (além de update_custom_type e delete_custom_type para evoluí-los ou aposentá-los)

Você não precisa configurar nada extra — assim que o tipo existe na sua empresa, ele fica disponível para qualquer cliente MCP autenticado.

Como um agente usa seu tipo

Imagine que você criou um tipo com slug helpdesk_tickets. Um agente pedindo para "abrir um ticket para o contato Alice" faria:

1. Chama list_custom_types e encontra helpdesk_tickets.
2. Chama get_custom_type_definition para ver os campos e valores obrigatórios.
3. Chama create_document com type: "ct:helpdesk_tickets" e os campos preenchidos.

observação

Slugs que coincidem com nomes de coleções nativas (contacts, messages, support_tickets, …) são reservados — create_custom_type os rejeita com reserved_slug. Slugs também são imutáveis após a criação, então escolha com cuidado.

Perguntas de follow-up ("mostre todos os tickets abertos de alta prioridade") viram chamadas a query_documents.

Escrevendo boas Dicas para MCP

Ao criar ou editar um Tipo Personalizado, o campo Dicas para MCP é onde você diz ao agente como usar o seu tipo. Os agentes veem essas dicas junto com a definição.

Boas dicas são assim:

• "Sempre preencha status ao criar um lead."
• "Vincule ao contato via contactId quando o lead veio de uma conversa conhecida."
• "Quando mudar status para resolved, também preencha resolvedAt com o horário atual."
• "A prioridade padrão é 3. Só aumente se o usuário disser explicitamente que o problema é urgente."

Mantenha-as curtas e imperativas. Pense nelas como regras para um system prompt.

Escrevendo um bom purpose

O campo Propósito na definição do tipo é igualmente importante. Ele diz ao agente quando escolher o seu tipo logo de cara. Trate como um handoff:

"Rastrear leads comerciais do primeiro contato até a qualificação. Quando o usuário mencionar geração de leads, oportunidades, prospects ou pipeline comercial, busque ou crie um registro aqui em vez de usar a entidade Contatos nativa."

Um propósito claro com algumas dicas objetivas melhora a forma como os agentes roteiam as solicitações para o seu Tipo Personalizado.

Criando um Tipo Personalizado a partir de um agente

Você não precisa definir Tipos Personalizados pela interface. Um agente com uma chave de API válida pode chamar create_custom_type direto, por exemplo depois de uma conversa do tipo:

"Precisamos acompanhar os cursos de treinamento da empresa — nome do curso, data de início, instrutor, capacidade, número de inscritos. Cria isso."

O agente traduz isso em uma chamada create_custom_type com a lista de campos certa. O novo tipo aparece no seu menu depois disso, pronto para uso.

Limites e segurança

• Pelo MCP, create_custom_type, update_custom_type e delete_custom_type são protegidos apenas por uma chave de API válida da empresa, que concede acesso total ao tenant — a restrição a donos (requireOwner) vale para a interface no app e as rotas /data, não para o MCP. Considere que qualquer chave de API capaz de alcançar o endpoint MCP pode criar e excluir Tipos Personalizados.
• Agentes não podem definir novas funções / ações em Tipos Personalizados — essa versão é focada em dados.
• Todo CRUD é isolado por tenant — um cliente MCP só alcança os registros da sua própria empresa. Porém, clientes MCP operam em nível de dono: as listas de acesso por papel configuradas no Tipo Personalizado (acesso do tipo) restringem seus funcionários no app, não clientes MCP/chave de API.
• Automações reagem aos registros do seu tipo: workflows e webhooks de saída com gatilho de hook no modelo ct:<slug> disparam em criação/atualização/exclusão de registros. (O gerenciamento de webhooks continua apenas no app — não é exposto pelo MCP.)

Exemplo: ligando com entidades nativas

Campos de referência permitem que seu Tipo Personalizado se conecte ao resto do AutoTalk. Por exemplo, um tipo helpdesk_tickets com estes campos:

Campo	Aponta para	Efeito
contactId	contacts (nativo)	Liga o ticket ao contato
assignedTo	employees (nativo)	Mostra o responsável
relatedLeadId	ct:leads (outro Tipo Personalizado)	Volta ao lead de origem

Os agentes (e a interface) navegam essas referências — clicar no contactId abre a página do contato, por exemplo.

Próximos passos

• Tokens de API — crie a chave que o cliente MCP vai usar
• Servidores MCP — referência completa do endpoint MCP