Claude MCP

O Model Context Protocol (MCP) é um padrão aberto que permite que assistentes de IA como o Claude acessem ferramentas e fontes de dados externas com segurança. A Finn expõe um servidor MCP, então você pode conectar a Finn ao Claude (ou a qualquer cliente compatível com MCP) e fazer com que seu assistente de IA consulte, configure e opere a plataforma de forma conversacional.

Para quem é isto. Para usuários avançados — desenvolvedores, engenheiros de automação e operadores familiarizados com IA que querem controlar a Finn pelo Claude Desktop, Claude Code ou qualquer outro cliente MCP. Se você não conhece o Claude ou o MCP, não precisa disto — o painel faz tudo o que o MCP expõe.

Status: o servidor MCP da Finn está em beta público. As APIs são estáveis, mas novas ferramentas são adicionadas com frequência.

O que dá para fazer com o MCP

Depois de conectado, seu Claude (ou outra IA compatível com MCP) pode fazer tudo isto em seu nome:

Operações de leitura

• Consultar o status de qualquer implantação.
• Listar seus Finns, públicos e números de telefone.
• Obter transcrições de chamadas e análises de qualquer período.
• Buscar padrões específicos no histórico de chamadas ("me mostre as chamadas em que o interlocutor falou em 'reembolso'").
• Consultar custos de implantação, uso do plano e resumos de faturamento.

Operações de escrita

• Iniciar uma nova implantação.
• Pausar ou parar uma implantação ativa.
• Adicionar contatos a um público.
• Atualizar os campos de análise pós-chamada de um Finn.
• Bloquear números (adicionar à lista de não perturbe).

Coordenação

• Gerar relatórios semanais/mensais automaticamente.
• Cruzar os resultados das chamadas com seu CRM para detectar lacunas de atribuição.
• Criar uma nova implantação automaticamente quando uma lista do CRM atingir determinado tamanho.
• Resumir uma implantação em linguagem simples, adequada para compartilhar com uma parte interessada não técnica.

Configuração do servidor MCP

Etapa 1 — Gerar um token MCP

Configurações → Integrações → MCP → Gerar Token.

Copie o token imediatamente — ele só aparece uma vez. Guarde no seu gerenciador de senhas ou cofre de segredos.

Os escopos do token são configuráveis:

• Somente leitura — consultar dados, sem modificar
• Leitura + escrita — acesso operacional completo (use com cautela)
• Restrito a Finns/públicos específicos — limita o acesso a um subconjunto

Para a maioria dos usuários, comece com Somente leitura para se familiarizar e amplie depois.

Etapa 2 — Configurar seu cliente MCP

Claude Desktop (Mac, Windows):

Edite o arquivo de configuração do Claude Desktop:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione o servidor da Finn:

{
  "mcpServers": {
    "finnai": {
      "command": "npx",
      "args": ["-y", "@finnai/mcp-server"],
      "env": {
        "FINNAI_API_TOKEN": "your_token_here"
      }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas da Finn ficam disponíveis em qualquer conversa.

Claude Code (CLI):

claude mcp add finnai \
  --command "npx -y @finnai/mcp-server" \
  --env FINNAI_API_TOKEN=your_token_here

Depois, claude a partir de qualquer diretório — as ferramentas do Finn estarão disponíveis.

Outros clientes MCP (Continue, Cursor, personalizados):

Use o mesmo comando npx na configuração do servidor MCP do seu cliente. O servidor usa MCP padrão via stdio.

Etapa 3 — Testar a conexão

No Claude (qualquer cliente), pergunte:

"Quais Finns eu tenho configurados?"

Se a conexão funcionar, o Claude chama a ferramenta list_finns e responde com uma resposta real.

Ferramentas expostas pelo MCP

O servidor oferece cerca de 30 ferramentas. Destaques:

Gerenciamento de Finns

• list_finns — lista todos os Finns da conta.
• get_finn — obtém a configuração completa de um Finn.
• create_finn — cria um novo Finn (avançado).
• update_finn — altera as configurações do Finn.

Gerenciamento de públicos

• list_audiences — lista todos os públicos.
• get_audience_stats — contagens, status de validação, importações recentes.
• add_contacts — adiciona contatos em massa.
• remove_contact — remove um único contato.

Ciclo de vida da implantação

• list_deployments — lista implantações passadas e ativas.
• launch_deployment — inicia uma nova.
• pause_deployment / resume_deployment / stop_deployment.
• get_deployment_status — status ao vivo com a contagem atual de chamadas.

Análises

• get_deployment_analytics — métricas completas de uma implantação.
• search_calls — encontra chamadas que correspondem a padrões de conteúdo.
• get_call — obtém a transcrição e a análise de uma chamada.
• aggregate_calls — agregações personalizadas por qualquer campo em qualquer período.

Conformidade

• add_to_suppression_list — bloqueia um número globalmente.
• remove_from_suppression_list — desbloqueia.
• check_suppression — o número está na lista?

Faturamento

• get_usage_this_month — gastos em andamento.
• forecast_month_end — projeção com base na trajetória.
• set_spend_cap — ajusta os limites.

Esquema completo de cada ferramenta: api.hirefinn.ai/academy/mcp.

Coisas que você pode pedir ao Claude

Prompts reais que funcionam:

"Mostre os resultados de implantação de ontem e diga qual Finn teve o melhor desempenho."

"Encontre todas as chamadas da última semana em que a pessoa disse 'muito caro' e resuma o contexto comum."

"Inicie a mesma implantação de segunda-feira passada, mas com o novo público que enviei hoje de manhã."

"Quanto gastamos na semana passada e estamos dentro do orçamento?"

"Adicione estes números de telefone à lista de supressão: [colar lista]"

"Qual é a diferença na taxa de sucesso entre nossas chamadas da manhã e as da tarde?"

"Gere um resumo de 1 página da campanha de lembrete de consultas do mês passado para o gerente da clínica."

O MCP torna a Finn conversacional. Operações que levariam de 5 a 10 cliques no painel viram uma única solicitação em linguagem natural.

Considerações de segurança

O que o token pode fazer

Os escopos do token determinam o que é permitido:

• Token somente leitura → pode consultar tudo, mas não altera nada.
• Leitura + escrita → acesso operacional completo. Trate como a senha do seu painel.
• Tokens com escopo → limitam por ID de Finn, ID de público ou tipo de operação.

Boas práticas

• Não cole tokens em mensagens de chat. Use variáveis de ambiente na configuração do seu cliente MCP.
• Rotacione os tokens periodicamente. Configurações → Integrações → MCP → Rotacionar.
• Use tokens com escopo para membros da equipe. Não dê um token de acesso total a um prestador de serviço.
• Log de auditoria. Toda chamada MCP é registrada. Configurações → Integrações → MCP → Log de atividades.
• Revogue os tokens imediatamente em caso de vazamento. Configurações → Integrações → MCP → Revogar.

O que o Claude não pode fazer

O MCP não expõe:

• Criação/exclusão de conta
• Alterações na forma de pagamento
• Upgrades/downgrades de plano
• Convites para membros da equipe
• Configuração de SSO

Isso exige acesso ao painel. Intencional — são decisões que você quer que um humano tome.

Aprovando ações sensíveis

Por padrão, o MCP exige aprovação humana explícita (pelo sistema de permissões do seu cliente MCP) para qualquer operação de escrita:

• Iniciar implantações
• Adicionar/remover contatos
• Modificar configurações de Finn
• Gastar dinheiro

Isso é aplicado no nível do protocolo — o Claude não consegue executar uma escrita sem sua confirmação na interface do cliente. Operações de leitura não exigem aprovação.

Você pode desativar isso por ferramenta em Configurações → Integrações → MCP → Lista de aprovação automática, caso queira que certas ferramentas rodem sem confirmação. Use com moderação — aprovar automaticamente "launch_deployment" é um jeito real de gastar muito dinheiro rápido.

Padrões comuns

Reunião diária

Configure o Claude para buscar as métricas do dia anterior toda manhã:

"Todo dia útil às 9h, resuma os resultados de implantação do dia anterior, destaque anomalias e publique no meu Slack."

(Requer o Claude Code com tarefas agendadas, ou seu próprio cron + wrapper MCP.)

Detecção de anomalias

"Verifique se alguma implantação nas últimas 24 horas teve taxa de sucesso abaixo de 50% ou custo mais de 2x acima da média de 7 dias. Sinalize com detalhes."

Auditoria em massa

"Liste todos os Finns que não têm campos de análise pós-chamada definidos. Sugira padrões razoáveis para cada um com base na descrição de identidade do Finn."

Exportações rápidas

"Extraia todas as chamadas da implantação X em que qualified=true, exporte como CSV e envie por e-mail para mim."

Solução de problemas

"O Claude não encontra as ferramentas da Finn"

• Reinicie o Claude Desktop após editar a configuração.
• Verifique se o JSON de configuração é válido (vírgulas, aspas).
• Execute npx -y @finnai/mcp-server --test no terminal para confirmar que o servidor inicia.

"Falha na autenticação"

• Token expirado ou revogado. Gere um novo.
• Variável de ambiente do token não está sendo repassada (erro de digitação na configuração).

"Tempo esgotado na chamada da ferramenta"

• Consultas grandes (por exemplo, buscar no histórico de chamadas) podem levar mais de 30 segundos.
• O tempo limite padrão na maioria dos clientes é de 30s. Aumente se necessário.

"Permissão negada para a ferramenta X"

• O escopo do seu token não inclui esta ferramenta.
• Gere um novo token com escopo mais amplo, ou use o painel para essa operação.

O que vem por aí

O roteiro do MCP (até o momento desta publicação):

• Ferramentas de fluxo de trabalho — crie e edite fluxos visuais pelo Claude.
• Ferramenta Test-on-Call — inicie chamadas de teste pelo Claude.
• Assinaturas de streaming — fluxos de eventos em tempo real para implantações ao vivo.
• Suporte a múltiplas contas — gerencie várias contas Finn em uma só sessão do Claude.
• Reprodução de gravações — transmita o áudio das chamadas para o Claude ouvir diretamente (Enterprise).

Sugira ferramentas que você quer em [email protected].

Além do Claude

Embora esta página trate do Claude, o servidor MCP é agnóstico de provedor. Ele funciona com:

• Continue.dev (extensão de IA para VS Code)
• Cursor (IDE com IA em primeiro lugar)
• OpenAI ChatGPT Desktop (quando o suporte a MCP for lançado)
• Clientes MCP personalizados criados sobre a especificação aberta

Qualquer cliente que fale MCP pode usar o Finn através do mesmo servidor.

Próximo

• Integrações → API REST — a API subjacente que o MCP encapsula.
• Integrações → Webhooks — notificações push para fluxos de trabalho orientados a eventos.
• Capacidade e escala → — limites de taxa que se aplicam às chamadas MCP.