Como Construí um Servidor MCP que Combina Hunter.io e Apollo para Enriquecimento de Leads B2B

Agentes de IA são poderosos, mas sem dados reais, eles são apenas enganadores confiantes. Você pode conectar Claude a um CRM e perguntar "encontre leads em fintech com 50-200 funcionários" o dia todo, e ele vai inventar coisas. Até que você lhe dê ferramentas que realmente busquem dados.
É para isso que servem os servidores MCP. E foi isso que eu construí.
Este post passa por b2b-enrichment-mcp, um servidor MCP de código aberto que lancei recentemente. Ele combina duas APIs de dados B2B (Hunter.io para e-mails, Apollo.io para informações de empresas) em uma única camada de ferramenta que Claude pode usar diretamente. Todo o sistema é Python assíncrono, FastMCP, licenciado sob MIT, e funciona com chaves de API do nível gratuito.
Vou mostrar a arquitetura, as partes que quebraram e como contornei esses problemas.
O Problema com Geração de Leads de API Única
Se você já tentou configurar um fluxo de enriquecimento de leads, conhece a dor. Hunter é ótimo para encontrar e-mails de um domínio. Não é tão bom em dados em nível de empresa. Apollo tem o gráfico de empresas, mas seu localizador de e-mails é limitado a um número ridículo no nível gratuito.
Portanto, a maioria das pessoas acaba com uma dessas configurações:

Pague ambos os fornecedores e escreva código de integração entre eles
Escolha um e finja que o outro não existe
Construa um fluxo do Zapier que quebra toda vez que um payload parece estranho

O que você realmente quer é uma interface. O agente de IA não deveria se importar com qual API possui quais dados. Ele deve apenas dizer "enriquecer este domínio" e receber tudo de volta. Essa é toda a proposta do MCP, expondo ferramentas a um LLM de uma maneira normalizada.
Por que MCP e Por que FastMCP
Um contexto rápido se você é novo no MCP. O Modelo de Protocolo de Contexto é o padrão aberto da Anthropic para permitir que LLMs se comuniquem com ferramentas externas. Seu agente de IA de um lado, seu servidor de ferramentas do outro, chamadas estruturadas no meio. Claude Desktop, Cursor e vários outros clientes suportam isso nativamente.
FastMCP é o SDK Python que torna a construção de um servidor absurdamente simples. Você escreve funções assíncronas, as decora com @mcp.tool(), e basicamente é isso. O SDK lida com JSON-RPC, transporte, geração de esquema, todas as partes chatas.
Veja como uma ferramenta mínima se parece:

from fastmcp import FastMCP
import httpx

mcp = FastMCP("b2b-enrichment")

@mcp.tool()
async def find_emails(domain: str, limit: int = 10) -> dict:
"""Encontre e-mails associados a um domínio via Hunter.io."""
async with httpx.AsyncClient() as client:
response = await client.get(
"https://api.hunter.io/v2/domain-search",
params={"domain": domain, "limit": limit, "api_key": HUNTER_KEY}
)
return response.json()

Essa é uma ferramenta funcional. Claude agora pode chamar find_emails("stripe.com") e obter dados estruturados de volta. Sem Flask, sem FastAPI, sem boilerplate.
A Arquitetura
O servidor expõe 9 ferramentas divididas entre dois provedores:
Ferramentas Hunter (5):

find_emails_by_domain — lista e-mails para um domínio
find_email_by_name — encontra o e-mail de uma pessoa específica
verify_email — verifica a entregabilidade
count_emails — verificação rápida de volume antes de gastar créditos da API
get_account_info — cota restante, útil para o agente se auto-regular
**
Ferramentas Apollo (4):**

enrich_company — tamanho da empresa, setor, stack tecnológico, financiamento
search_companies — encontra empresas que correspondem aos critérios
get_company_employees — lista pessoas em uma empresa
bulk_enrich — lote de até 10 domínios em uma única chamada

Todos assíncronos, todos compartilhando uma única instância de httpx.AsyncClient, todos envolvidos com o mesmo padrão de tratamento de erros. O agente escolhe ferramentas com base na intenção. Se precisa de um e-mail, vai de Hunter. Se precisa de firmográficos, vai de Apollo. Se precisa de ambos, chama ambos e mescla os resultados por conta própria.
Limitação de Taxa Sem Perder a Cabeça
É aqui que a maioria dos tutoriais faz uma abordagem superficial e você descobre da maneira difícil que seu servidor está recebendo 429 em cada outra chamada.
Tanto Hunter quanto Apollo têm níveis gratuitos generosos, mas não são ilimitados. Hunter oferece 25 pesquisas por mês no gratuito, Apollo oferece 50 créditos. O agente não sabe disso. Se você deixar ele apenas enviar chamadas, você vai queimar créditos em cinco minutos.
O padrão que eu uso é um balde de tokens por provedor, aplicado dentro do wrapper do cliente:

import asyncio
from time import monotonic

class RateLimiter:
def init(self, rate: float, burst: int):
self.rate = rate
self.burst = burst
self.tokens = burst
self.last = monotonic()
self.lock = asyncio.Lock()

async def acquire(self):
    async with self.lock:
        now = monotonic()
        elapsed = now - self.last
        self.tokens = min(self.burst, self.tokens + elapsed * self.rate)
        self.last = now
        if self.tokens < 1:
            wait = (1 - self.tokens) / self.rate
            await asyncio.sleep(wait)
            self.tokens = 0
        else:
            self.tokens -= 1

Cada ferramenta adquire um token antes de acessar a API. Se o balde estiver vazio, ela espera. Sem tentativas, sem loops de exceção, o agente apenas aguarda. Claude é paciente, você pode deixá-lo esperar dois segundos.
A Armadilha do Nível Gratuito do Apollo
Aqui está a parte que me pegou, e a parte que tive que redesenhar.
O nível gratuito do Apollo diz oficialmente que você obtém enriquecimento de empresas e pesquisa de pessoas. No meio da construção, percebi que people_search e email_finder começaram a retornar payloads vazios em contas gratuitas. Sem erro, sem 403, apenas nada silencioso. Acontece que o Apollo restringiu silenciosamente esses endpoints para planos pagos em algum momento, e a documentação não acompanhou.
Minhas opções eram:

Dizer aos usuários que precisam de uma conta paga do Apollo (mata a promessa do nível gratuito do projeto)
Eliminar o Apollo completamente (perde todos os dados em nível de empresa)
Reestruturar para que o Hunter faça o trabalho pesado e o Apollo permaneça para o que ainda funciona (enriquecimento de empresas)

Eu escolhi a opção 3. O fluxo agora se parece com isso:

O trabalho de encontrar e-mails vai para o Hunter (ainda funciona no gratuito)
Firmográficos da empresa vão para o enrich_company do Apollo (ainda funciona no gratuito)
Pesquisa de pessoas, removida da versão pública, mantida como um caminho de código de nível pago com uma nota clara no README

Essa decisão salvou o projeto. Se eu tivesse permanecido teimoso na opção 1, ninguém teria tentado.
A lição é simples: quando você depende de APIs de terceiros, especialmente em seus níveis gratuitos, construa como se o tapete pudesse ser puxado. Mantenha sua superfície de ferramenta modular o suficiente para que você possa eliminar um provedor sem reescrever todo o servidor.
Isolamento de Falhas Quando Ferramentas Chamam Ferramentas
O agente frequentemente deseja enriquecer um domínio de ponta a ponta: e-mails mais dados da empresa mais verificação. Isso é no mínimo três chamadas de API entre dois provedores.
A abordagem ingênua é aguardá-las sequencialmente. Não faça isso. Se um provedor estiver fora do ar, toda a sua ferramenta para.
O padrão que eu encontrei usa asyncio.gather com return_exceptions=True, para que uma falha do Hunter não mate os resultados do Apollo:

@mcp.tool()
async def full_domain_enrichment(domain: str) -> dict:
"""Combine dados do Hunter e Apollo para um único domínio."""
hunter_task = find_emails_by_domain(domain, limit=20)
apollo_task = enrich_company(domain)

hunter_result, apollo_result = await asyncio.gather(
    hunter_task, apollo_task, return_exceptions=True
)

return {
    "domain": domain,
    "emails": hunter_result if not isinstance(hunter_result, Excep