Como criar um agente de IA para vendas no seu SaaS: tutorial com MCP e API

O que este agente de IA realmente faz

“Vender sozinho” é uma promessa sedutora, mas ampla demais. Um SaaS B2B ainda precisa de posicionamento, demonstração, negociação e confiança. O melhor primeiro agente é um agente de pré-vendas: ele assume o trabalho repetitivo antes da conversa comercial e entrega contexto para você decidir.

Arquitetura: onde entram a IA, o MCP e a API

Pense no agente como três camadas. O modelo interpreta o objetivo e decide a próxima etapa. O TDFÁCIL fornece as ferramentas e os dados empresariais. Sua aplicação controla identidade, aprovação, orçamento, registro e eventual envio por outro canal.

Pré-requisitos para acompanhar o tutorial

1. Transforme a descrição do SaaS em um ICP pesquisável

O agente não começa procurando empresas. Ele começa fazendo boas perguntas. “Meu sistema ajuda negócios a vender mais” não gera um filtro confiável. Já uma descrição que inclui problema, usuário, região e contexto operacional permite construir uma hipótese.

“Meu SaaS automatiza cobranças recorrentes para academias. Quero começar por empresas ativas em Campinas e cidades próximas, com operação estruturada o bastante para sentir o problema.”

A partir daí, o agente deve separar o que foi informado, o que precisa ser perguntado e o que precisa ser pesquisado. O código CNAE, por exemplo, não deve sair da memória do modelo: ele deve consultar tdfacil_search_referencee apresentar as opções para confirmação.

Se esse recorte ainda é novo para você, veja também nosso guia sobrecomo buscar empresas por CNAEantes de automatizar a seleção.

2. Conecte o MCP remoto do TDFÁCIL

Para validar a ideia sem construir uma interface, use um cliente compatível com MCP Streamable HTTP e OAuth. Adicione o servidor abaixo; o cliente deve abrir o login e a tela de consentimento no navegador. Escolha somente as permissões necessárias para o teste.

{
  "mcpServers": {
    "tdfacil": {
      "type": "streamable-http",
      "url": "https://api.tdfacil.com/mcp"
    }
  }
}

Depois da autenticação, peça ao cliente para apenas listar as ferramentas. Você deverá encontrar recursos para pesquisar referências, fazer a prévia, criar e consultar listas, ler leads, solicitar enriquecimento e acompanhar operações. Ainda não execute uma ação que consuma créditos.

3. Crie o agente com a Responses API da OpenAI

A Responses API aceita servidores MCP remotos como ferramentas. Na primeira versão, mantenha require_approval comoalways. Assim, a resposta para quando o modelo deseja chamar uma ferramenta, sua aplicação mostra os argumentos e só continua depois da decisão do usuário.

Também limite o catálogo com allowed_tools. Isso reduz ambiguidade e impede que o agente enxergue ações desnecessárias ao caso de uso. A documentação oficial da OpenAI explica tanto a conexão com MCP remoto quanto o fluxo de aprovação.

Você é um agente de pré-vendas B2B para um SaaS.

Objetivo: transformar a descrição do produto em uma lista curta de empresas aderentes e preparar rascunhos de abordagem.

Regras:
1. Nunca invente um CNAE. Pesquise o catálogo antes de aplicar o filtro.
2. Sempre faça uma prévia antes de propor a criação de uma lista.
3. Antes de criar lista ou solicitar enriquecimento, mostre filtros, limite e motivo, e aguarde aprovação.
4. Use o run_id recebido para formar chaves de idempotência estáveis.
5. Priorize poucas contas com justificativa; não maximize volume.
6. Diferencie dado retornado pela ferramenta de inferência do modelo.
7. Não envie e-mail, WhatsApp ou qualquer mensagem externa.
8. Entregue: empresa, evidências de aderência, lacunas de informação, nota de 0 a 100 e rascunho de abordagem.
9. Se faltar informação para definir o ICP, faça perguntas antes de usar ferramentas.

import OpenAI from "openai";

const client = new OpenAI();
const model = process.env.OPENAI_MODEL;
const tdfacilToken = process.env.TDFACIL_OAUTH_ACCESS_TOKEN;

if (!model || !tdfacilToken) {
  throw new Error("Configure OPENAI_MODEL e TDFACIL_OAUTH_ACCESS_TOKEN");
}

const mcpTool = {
  type: "mcp" as const,
  server_label: "tdfacil",
  server_description: "Pesquisa e enriquecimento de leads B2B brasileiros.",
  server_url: "https://api.tdfacil.com/mcp",
  authorization: tdfacilToken,
  allowed_tools: [
    "tdfacil_search_reference",
    "tdfacil_preview_lead_search",
    "tdfacil_create_lead_list",
    "tdfacil_get_operation",
    "tdfacil_get_leads",
    "tdfacil_request_enrichment"
  ],
  require_approval: "always" as const
};

const agentInstructions = [
  "Você é um agente de pré-vendas B2B para um SaaS.",
  "Nunca invente CNAE: pesquise o catálogo antes de aplicar filtros.",
  "Sempre faça uma prévia antes de propor uma lista.",
  "Peça aprovação antes de lista, enriquecimento ou contato externo.",
  "Separe dados retornados pelas ferramentas de inferências do modelo."
].join("\n");

export async function startProspecting(productDescription: string) {
  const runId = crypto.randomUUID();

  return client.responses.create({
    model,
    tools: [mcpTool],
    instructions: agentInstructions,
    input: [
      "run_id: " + runId,
      "Produto: " + productDescription,
      "Comece definindo o ICP. Não crie listas ainda."
    ].join("\n")
  });
}

export async function approveToolCall(
  previousResponseId: string,
  approvalRequestId: string
) {
  return client.responses.create({
    model,
    tools: [mcpTool],
    previous_response_id: previousResponseId,
    input: [{
      type: "mcp_approval_response",
      approval_request_id: approvalRequestId,
      approve: true
    }]
  });
}

4. Execute a prospecção na ordem certa

O valor do agente não está em chamar muitas ferramentas. Está em escolher uma sequência econômica, verificável e fácil de interromper. Use este fluxo como política do produto:

1. 1

   Confirme CNAE e município

   tdfacil_search_reference

   Pesquise pelo termo que o fundador usa e mostre as alternativas. O usuário confirma o recorte antes da próxima etapa.

2. 2

   Estime a busca

   tdfacil_preview_lead_search

   Envie os filtros e um limite. A prévia estima o universo sem criar uma lista paga, mas exige uma chave de idempotência.

3. 3

   Peça aprovação e crie a lista

   aprovação obrigatória

   tdfacil_create_lead_list

   Mostre título, filtros e quantidade solicitada. A criação reserva créditos e acontece de forma assíncrona.

4. 4

   Acompanhe a operação

   tdfacil_get_operation

   Consulte o estado sem repetir a criação. Quando concluir, recupere a lista correspondente.

5. 5

   Leia e reduza o conjunto

   tdfacil_get_leads

   Analise os dados empresariais retornados e descarte contas sem evidência suficiente de aderência.

6. 6

   Enriqueça somente os finalistas

   aprovação obrigatória

   tdfacil_request_enrichment

   Solicite enriquecimento de um lead por chamada e somente depois de outra aprovação explícita.

A mesma chave de idempotência deve ser reutilizada quando sua aplicação repete exatamente a mesma tentativa. Criar uma chave nova em todo retry elimina a proteção contra duplicidade.

5. Priorize contas e prepare uma abordagem útil

Depois de recuperar os leads, peça uma pontuação explicável. A nota não é uma verdade estatística: ela é uma regra operacional para ordenar o trabalho. Um modelo simples pode somar três blocos:

Exija que cada nota venha com evidências e lacunas. “Parece uma boa empresa” não basta. A saída precisa dizer quais campos sustentam o encaixe e o que ainda é apenas hipótese.

6. Leve as etapas determinísticas para a API REST

O MCP é excelente para descobrir o fluxo. Quando seu produto já sabe exatamente o que deve acontecer, mover parte da execução para a API facilita filas, limites próprios, webhooks, métricas e testes. Um desenho comum mantém o modelo na definição do ICP e na análise, enquanto o backend executa prévia, criação e acompanhamento.

const runId = crypto.randomUUID();

const response = await fetch(
  "https://api.tdfacil.com/v1/lead-search-previews",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + process.env.TDFACIL_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": "preview:" + runId
    },
    body: JSON.stringify({
      filters: {
        state: "SP",
        city: "Campinas",
        cnae: ["CODIGO_CONFIRMADO_NO_CATALOGO"]
      },
      limit: 100
    })
  }
);

if (!response.ok) {
  throw new Error("Falha na prévia: " + response.status);
}

const preview = await response.json();

Na criação de lista, a API responde de forma assíncrona. Seu backend acompanha a operação pelo endpoint correspondente ou usa webhooks para reagir à conclusão. Trate 429 com espera, respeite Retry-After e nunca transforme timeout em uma nova compra sem antes consultar o estado da operação.

Controles que não podem faltar no agente de vendas

Como saber se o agente está ajudando a vender

Não avalie o agente pelo número de chamadas de ferramenta nem pelo tamanho da lista. Meça a passagem de uma etapa para a seguinte e compare a qualidade com o processo manual.

Se você ainda está validando o produto, combine esse agente com um processo de prospecção liderado pelo fundador. Nosso guia sobrecomo conseguir os primeiros clientes para um SaaSajuda a transformar a lista em conversas e aprendizado comercial.

Documentação usada neste tutorial

• OpenAI: MCP e conectores na Responses API
• OpenAI: referência para criar uma Response
• TDFÁCIL: catálogo MCP, OAuth, limites e idempotência
• TDFÁCIL: contrato OpenAPI público

Perguntas frequentes