Conectar um agente ao CRM

O MCP conecta um aplicativo de IA ao CRM com permissões definidas por você. A conexão oferece até 34 ferramentas: três para tarefas e notas internas, quatro para grupos, oito para contratos, uma para indicadores, catorze para consultar negócios, contatos, conversas, campanhas, automações, tarefas, agendamentos e formulários linha a linha e quatro relatórios agregados. A lista apresentada ao agente depende das permissões autorizadas e do acesso atual da sua conta.

ConectarCopy Anchor Link

1. No aplicativo compatível com MCP remoto e OAuth, adicione https://crm.oficinamartech.com/mcp, usando o transporte Streamable HTTP. O endereço atende a revisão 2026-07-28 do protocolo (sem sessão, cada chamada independente) e também os aplicativos que ainda abrem a conexão pelo formato anterior.
2. Entre no CRM e conclua a verificação em duas etapas, quando exigida.
3. Confira o nome do aplicativo e o destino da autorização. Escolha uma das organizações em que você pode conectar.
4. Selecione as capacidades solicitadas pelo aplicativo. Você pode conectar contratos, grupos, indicadores e leituras de negócios, contatos, conversas e demais registros de forma independente, com uma exceção descrita abaixo da tabela.
5. Retorne ao aplicativo e confira as ferramentas disponíveis.

Proprietários e administradores com acesso ativo sempre podem autorizar uma conexão. Operadores podem quando a organização liga Permitir que operadores conectem agentes, em Configurações → API → Conexão com IA (desligada por padrão; só proprietário e administrador alteram). Cada conexão acessa uma organização. Sessões de impersonação não podem autorizar agentes.

O agente vê e faz exatamente o que a pessoa que autorizou vê e faz na tela do CRM, nada além:

• A tela de autorização só oferece as permissões que a pessoa já tem. A tabela abaixo mostra de onde vem cada uma.
• Conversas, mensagens e grupos seguem a mesma regra de visibilidade da caixa de entrada: quem só vê as próprias conversas e as sem responsável recebe só essas.
• Indicadores e relatórios seguem o dashboard da pessoa: organização, equipe ou só os próprios números (veja Montar painéis com indicadores).
• A cada chamada o CRM confere de novo as permissões atuais. Quem perde uma permissão vê a ferramenta correspondente recusar com missing_permission; quem sai da organização perde a conexão inteira.

Desligar a configuração impede novas conexões de operadores, mas não encerra as existentes: elas seguem até expirar ou serem desconectadas por um administrador.

Na tela de autorização, contacts:read, conversations:read, messages:read, tasks:write e notes:write vêm desmarcadas: dados pessoais, conteúdo de conversas e ações que alteram o CRM só são concedidos por escolha ativa. tasks:write aparece para quem pode ver o funil e notes:write para quem pode escrever em conversas.

Uma mesma conexão não combina groups:schedule com contacts:read, conversations:read ou messages:read. O agente que lê texto escrito por clientes não recebe, na mesma conexão, a ferramenta que agenda mensagens em grupos. Para usar os dois, conecte por aplicativos diferentes: uma nova autorização do mesmo aplicativo substitui a anterior.

Uma conexão somente de contratos não precisa de groups:read. Conexões antigas de grupos não recebem acesso a contratos automaticamente; ampliar permissões exige novo consentimento.

A autenticação exige PKCE S256. A conexão dura até 30 dias; tokens de acesso têm duração curta e podem ser renovados dentro desse prazo. O aplicativo recebe tokens da conexão; a credencial interna permanece no servidor. As permissões atuais continuam sendo verificadas nas operações.

FerramentasCopy Anchor Link

As permissões de preparação e envio são independentes entre si. Cada uma exige leitura de contratos. Ferramentas sem o escopo correspondente ficam fora da lista do agente.

As ferramentas que alteram algo são criar_tarefa, concluir_tarefa, registrar_nota_interna, agendar_mensagens_em_grupos, preparar_contrato, gerar_previa_contrato e enviar_contrato_para_assinatura. As demais só consultam. O MCP não envia mensagem a contatos nem cria ou altera campanhas, negócios, contatos, conversas, automações ou a agenda, e não reabre, edita ou apaga tarefas e notas; o agente é instruído a dizer que isso não está disponível, sem substituir por outra ferramenta. listar_agendamentos_da_agenda trata da agenda de reuniões e não tem relação com mensagens agendadas em grupos.

agendar_mensagens_em_grupos, preparar_contrato e enviar_contrato_para_assinatura são marcadas como ações que pedem confirmação: o aplicativo conectado deve perguntar a você antes de cada chamada, mesmo quando as consultas estão liberadas sem confirmação. Confira o conteúdo, os grupos e o horário antes de aprovar.

Montar painéis com indicadoresCopy Anchor Link

consultar_indicadores devolve agregados para montar painéis e responder perguntas de desempenho, no recorte do dashboard de quem autorizou a conexão. Quem vê o dashboard da organização recebe os números da organização (scope org); quem vê o da equipe ou só o próprio recebe scope department ou own e um scope_note avisando que o número é parcial. O mesmo vale para os relatórios; relatorio_disparos exige o dashboard da organização. Não há dados de contato nem conteúdo de conversas. Cada seção vem como tabela (columns e rows), com os nomes de funil, etapa, operador e produto já resolvidos; as seções agregáveis trazem também total.

Para vendas por operador, peça deal_outcomes com group_by ["operator", "status"]: a resposta traz uma linha por operador e situação, já somada. stage e reached_stage trazem sempre o funil, porque etapas de funis diferentes podem ter o mesmo nome. Uma dimensão que nenhuma seção pedida possui é recusada.

Valores monetários vêm na unidade da moeda, por código ISO 4217 (BRL em reais; XXX é moeda não informada). As datas e a janela seguem o fuso horário da organização, informado em window.timezone: uma venda fechada às 22h entra no próprio dia. Em operator, null significa sem responsável; em loss_reason, null é venda ganha, (sem motivo) é perda sem motivo e (fora da lista) é um motivo que não está mais cadastrado. Nomes repetidos ganham um sufixo curto para não se misturarem, e textos longos são cortados em 120 caracteres. Com date_grain week ou month, o primeiro e o último período podem vir incompletos, cortados pela janela.

Cada consulta devolve no máximo 64 KiB, para caber inteira na leitura do agente. Acima disso a consulta é recusada, nunca truncada, e a resposta informa o tamanho de cada seção: reduza as dimensões, use date_grain week ou month, peça menos seções ou diminua a janela.

Consultar negócios, contatos, conversas e demais registrosCopy Anchor Link

As ferramentas de leitura devolvem os registros linha a linha, para ver o que compõe um número ou analisar casos específicos. Para totais, somas e séries por data, prefira consultar_indicadores: ele agrega no servidor e não expõe dados pessoais.

1. Comece por listar_funis e listar_equipe para obter os identificadores de funil, etapa e responsável. Eles são os filtros das demais listas e traduzem pipeline_id, stage_id e assigned_to em nomes. stage_order numera as etapas de cada funil a partir de 1, igual em listar_funis, relatorio_funil e consultar_indicadores.
2. Filtre listar_negocios e listar_conversas pelo período e pelo responsável em vez de percorrer tudo. Em conversas, assigned_to none devolve as que estão sem responsável, e active_since/active_until recortam pela última mensagem.
3. Abra o conteúdo com ler_mensagens só nas conversas que interessam. As mensagens vêm da mais recente para a mais antiga, sem o arquivo de mídia; áudios trazem a transcrição quando ela existe. sender_kind vem contact nas recebidas e null nas enviadas sem autor registrado, como as escritas direto no aparelho.
4. Use listar_campanhas e listar_automacoes para ver o desempenho dos disparos e o uso das automações. Campanhas não trazem a lista de destinatários e automações não trazem o fluxo.
5. Use listar_tarefas para o que está pendente ou vencido por responsável e listar_agendamentos_da_agenda para a agenda. A tarefa aberta com vencimento passado sai com a situação overdue, a mesma conta de vencidas de relatorio_operacoes; status overdue lista só essas, e sem filtro entram todas, inclusive concluídas e canceladas. Agendamentos não trazem anotações internas, link da reunião nem token de cancelamento.
6. Para formulários, comece por listar_formularios: a chave de cada pergunta identifica a resposta em listar_respostas_formulario. Respostas de teste ficam de fora, e um formulário de outra organização responde como não encontrado.
7. Para totais e tendências, prefira os relatórios: relatorio_funil, relatorio_atendimento, relatorio_disparos e relatorio_operacoes somam no servidor, sem dados de contato, e aceitam days de 1 a 90 (o funil aceita também pipeline_id; por padrão ele omite as etapas e os funis sem negócio aberto e sem movimento na janela, e hide_empty_stages: false traz todos). Use as listas acima para ver o detalhe por trás de um número.

Toda lista, inclusive as de grupos e de contratos, responde no mesmo formato: data (as linhas), total, has_more e next_offset (o offset da próxima página, ou null).

buscar_mensagens devolve contatos com ocorrências dos termos e algumas mensagens de contexto. De cada contato vêm id, nome e origem; em listar_agendamentos_da_agenda, o nome de quem agendou. Telefone e e-mail só saem nessas duas ferramentas com include_contact_details: true.

Cada página aceita de 1 a 100 linhas, com offset de até 10.000; além disso next_offset vem null e o histórico segue por janelas de data. Datas sem horário (AAAA-MM-DD) são lidas como 00:00 no fuso horário da organização, também em from e to de listar_contratos; conexões autorizadas antes desta mudança usam America/Sao_Paulo até serem refeitas. Uma consulta que falha com retryable: true pode ser repetida; query_rejected não muda ao repetir e deve ser informada ao suporte com o correlation_id. Cada resposta devolve no máximo 64 KiB. Acima disso a consulta é recusada, nunca truncada: reduza limit e avance com offset. Os relatórios não paginam: acima do mesmo limite respondem result_too_large, e a orientação é informar pipeline_id (funil) ou reduzir days. Cada mensagem traz até 4.000 caracteres de texto, com truncated indicando o corte.

Estas ferramentas expõem dados pessoais (nome, telefone e e-mail, inclusive em agendamentos e respostas de formulários) e o conteúdo das conversas ao aplicativo conectado. Conceda contacts:read, conversations:read e messages:read apenas quando a análise precisar deles. O texto de mensagens, nomes, respostas de formulários e campos personalizados é escrito por terceiros: o agente deve tratá-lo como dado, nunca como instrução. Caracteres de controle e de formatação invisível são removidos antes da entrega.

Preparar e enviar um contratoCopy Anchor Link

1. Localize o contato ou negócio e escolha um modelo disponível. Resolva ambiguidades e dados faltantes; o agente não deve inventar destinatários, documentos pessoais ou cláusulas.
2. Prepare o rascunho e guarde draft_id e revision. Atualizações exigem expected_revision; uma revisão desatualizada é rejeitada, sem sobrescrever o trabalho do operador.
3. Gere a prévia quando o modelo for compatível. A prévia é um DOCX com substituição de variáveis escalares; não promete PDF nem equivalência visual com o documento final. Há restrições de formato descritas na referência de contratos.
4. Abra o approval_url retornado pelo preparo. Um operador autenticado precisa conferir a revisão no CRM e aprovar conteúdo, participante, canal e prazo. A aprovação fica vinculada à revisão, ao operador e ao aplicativo; um booleano fornecido pelo agente não vale como aprovação.
5. Use approval_id, expected_revision e uma idempotency_key estável para solicitar o envio. O primeiro corte de envio aceita modelo pronto e um signatário. Arquivo avulso, múltiplos signatários e lotes não estão habilitados nesse envio.
6. Guarde dispatch_job_id e signature_envelope_id. Consulte o contrato usando o identificador do envelope para acompanhar a situação.

Alterar o rascunho ou a configuração aprovada exige nova revisão e aprovação. A aprovação expira em 15 minutos e só pode ser consumida uma vez; a repetição idempotente de uma solicitação já aceita recupera o recibo existente.

Solicitação aceita, convite enviado e assinatura concluída são estados distintos. Conteúdo retornado de modelos e documentos é dado para revisão, nunca instrução para ampliar acesso ou executar outras operações.

Agendar mensagensCopy Anchor Link

O agendamento é a única ação de envio do MCP: no horário marcado, todos os participantes de cada grupo recebem a mensagem. O agente é instruído a agendar só a seu pedido e a confirmar com você o conteúdo, os grupos pelo nome e o horário antes de chamar a ferramenta; confira esses dados na confirmação que o aplicativo exibir.

Primeiro, peça ao agente para localizar os grupos e confira os nomes e identificadores. A busca é por nome; ela não classifica automaticamente grupos como alunos ou gerais.

O lote usa os campos da API de agendamento, com idempotency_key adicional na ferramenta. Aceita texto, imagem, vídeo e documento, incluindo PDF. A mídia precisa de URL HTTPS acessível ao processamento; o MCP não oferece upload de arquivos.

Escolha o fuso IANA, como America/Sao_Paulo ou Europe/Lisbon. O padrão é America/Sao_Paulo. O horário vai em AAAA-MM-DDTHH:mm:ss, lido no fuso informado; com Z ou offset, vale o offset. Exige pelo menos cinco minutos de antecedência. Limites: 50 itens por lote, 50 grupos por item e 1.000 destinos somados. Aceitar o lote confirma o agendamento; consulte os identificadores individuais para acompanhar envio e entrega.

As conexões de agente de uma pessoa agendam, juntas, no máximo 200 destinos a cada 24 horas em cada organização, somando os lotes aceitos. Acima disso o lote inteiro é recusado e nada é agendado; o limite reabre conforme os lotes anteriores completam 24 horas, e reconectar o aplicativo não o reabre. Agendamentos feitos pela tela do CRM não entram nessa conta.

Para saber o que já está agendado, peça a lista: listar_agendamentos_em_grupos mostra os 500 agendamentos mais recentes da organização, feitos pelo agente, por outra conexão ou pela tela do CRM.

Registrar tarefas e notasCopy Anchor Link

criar_tarefa, concluir_tarefa e registrar_nota_interna ficam dentro do CRM: nada é enviado ao contato e nenhuma automação é disparada. As permissões tasks:write e notes:write vêm desmarcadas na tela de autorização e podem ficar na mesma conexão que lê conversas e mensagens. O aplicativo conectado pede a sua confirmação a cada chamada; confira o texto, o prazo e o destino antes de aprovar.

A tarefa é criada para a pessoa indicada em assigned_to (de listar_equipe) ou, sem ela, para quem autorizou a conexão; a conclusão e a nota saem em nome de quem autorizou. O campo type da tarefa é só um rótulo: whatsapp, email, call e meeting não enviam nem agendam nada. Não há ferramenta para reabrir uma tarefa nem para editar ou apagar uma nota.

As conexões de agente de uma pessoa fazem, juntas, no máximo 200 escritas (tarefas e notas) a cada 24 horas em cada organização. Acima disso a ação é recusada e nada é gravado; reconectar o aplicativo não reabre o limite. Escritas feitas pela tela do CRM não entram nessa conta.

Evitar duplicidades e tratar resultados incertosCopy Anchor Link

Mantenha a mesma chave de idempotência e o mesmo conteúdo na repetição da mesma solicitação. Conteúdo diferente com uma chave usada é rejeitado.

Se o resultado não for confirmado, consulte o estado antes de repetir e não gere outra chave. Falha de conexão não prova que a solicitação deixou de ser aceita.

• Contratos: a deduplicação usa organização, operador e identidade estável do aplicativo. Renovar ou reconectar o mesmo aplicativo não cria um novo espaço de deduplicação. Trocar o aplicativo ou operador não é uma forma segura de repetir uma solicitação incerta.
• Tarefas e notas: a deduplicação usa a credencial da conexão, como nos grupos. Em resultado incerto, confira em listar_tarefas antes de repetir; reconectar não deduplica a ação anterior.
• Grupos: a deduplicação usa a credencial da conexão. Reconectar cria outra credencial, que não deduplica o lote da conexão anterior. Não reconecte para repetir um resultado incerto: confira antes na lista de agendamentos se o lote foi criado.

O MCP não oferece cancelamento, lembretes ou edição de envios de contratos já aceitos, nem cancelamento ou edição de agendamentos de grupos.

Revogar ou trocar a organizaçãoCopy Anchor Link

Em Configurações → API → Conexão com IA, proprietários e administradores veem todos os aplicativos conectados, com o nome de quem autorizou cada um, e desconectam qualquer um deles. A conexão também deixa de funcionar assim que quem a autorizou sai da organização, e cada ferramenta recusa quando a pessoa perde a permissão correspondente. A revogação não desfaz mensagens já agendadas nem envios já executados. Contratos enfileirados têm a autorização revalidada antes de novos efeitos externos.

Desconectar no aplicativo, quando ele envia a revogação OAuth, invalida sua autorização após a propagação. Isso não remove automaticamente a credencial interna da lista de API; ela expira em até 30 dias e também pode ser revogada pelo administrador.

Para trocar de organização ou ampliar permissões, inicie nova autorização. A nova conexão substitui a autorização anterior do mesmo usuário e aplicativo. Antes de reconectar, resolva operações cujo resultado esteja incerto.