Servidores MCP
Servidores MCP (Model Context Protocol) permitem que você estenda as capacidades do seu agente conectando-o a serviços externos que fornecem ferramentas adicionais. Com MCP, você integra APIs, bancos de dados, sistemas de terceiros e mais através de um protocolo padronizado.
O Que é MCP?
O Model Context Protocol (MCP) é um protocolo aberto que padroniza a comunicação entre modelos de linguagem (LLMs) e serviços externos. Pense nele como um "plugue" universal para integrações de IA.
| Capacidade | Descrição |
|---|---|
| Acessar ferramentas externas | Execute ações em sistemas de terceiros |
| Consultar dados em tempo real | Obtenha informações atualizadas de APIs e bancos |
| Integrar serviços enterprise | Conecte a CRMs, ERPs, calendários |
| Expandir funcionalidade | Adicione capacidades customizadas sem modificar o agente |
MCP vs. Integração com API
- Servidores MCP: Protocolo padronizado, capacidades mais ricas, requer servidor MCP
- Integração com API: Setup mais simples, chamadas REST únicas, sem servidor necessário
Use MCP quando precisar de ecossistemas de ferramentas complexos. Use Integração com API para endpoints REST simples.
Como o MCP Funciona
┌─────────────┐ ┌─────────────┐ ┌─────────────────┐
│ SipPulse │────▶│ SipPulse │────▶│ Servidor MCP │
│ Agente │ │ AI │ │ (Externo) │
└─────────────┘ └─────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────┐ ┌───────────┐
│ Resultados │ │ Sistema │
│ da Tool │◀──────│ Externo │
└─────────────┘ └───────────┘Fluxo:
- Agente recebe uma solicitação do usuário
- LLM decide usar uma ferramenta do servidor MCP
- SipPulse AI conecta ao servidor MCP
- Servidor executa a ferramenta e retorna resultados
- Agente usa resultados para responder ao usuário
Configurando um Servidor MCP
Acessando Configuração
- Navegue para Agentes no menu lateral
- Selecione ou crie um agente
- Vá para a seção Ferramentas
- Clique em Servidores MCP
Adicionando um Servidor
- Clique em Adicionar Servidor MCP
- Preencha os campos obrigatórios:
| Campo | Descrição | Exemplo |
|---|---|---|
| Nome | Identificador do servidor | "Google Calendar" |
| URL | Endpoint do servidor MCP | https://mcp.exemplo.com/api |
| Transporte | Protocolo de comunicação | auto |
| Headers | Headers de autenticação | Authorization: Bearer {{$MEU_TOKEN}} |
- Clique em Criar para adicionar o servidor
Tipos de Transporte
| Transporte | Descrição | Melhor Para |
|---|---|---|
| auto (padrão, recomendado) | Streamable HTTP com fallback automático para HTTP+SSE | Qualquer servidor moderno |
| HTTP | Streamable HTTP sem fallback | Servidores que só falam Streamable HTTP |
| SSE | HTTP+SSE | Servidores que exigem SSE |
| WebSocket | Conexão bidirecional persistente | Apenas entradas criadas antes; não é oferecido em servidores novos |
Os timeouts por servidor são 10 s para conectar e 60 s por chamada (connect_ms e call_ms), ajustáveis somente pela API.
Prefira uma Conexão MCP
Para servidores com OAuth ou que você reaproveita em vários agentes, crie uma Conexão MCP em Configurações > Conexões MCP e selecione-a no agente. A conexão guarda a credencial e o cache de tools uma vez só, em vez de repetir a configuração em cada agente.
Autenticação
Para servidores que requerem autenticação, adicione headers:
- Na seção Headers, clique em Adicionar Header
- Digite o nome e valor do header
Padrões comuns:
| Header | Valor | Caso de Uso |
|---|---|---|
Authorization | Bearer {{$MEU_TOKEN}} | APIs OAuth/JWT |
X-API-Key | {{$MINHA_CHAVE}} | Autenticação por chave API |
X-Custom-Header | {{$MEU_VALOR}} | Requisitos customizados |
O valor entre {{$...}} é o nome de um secret do projeto, resolvido em memória apenas no momento da chamada. Veja o Cofre de Secrets.
Gerenciando Ferramentas
Sincronizando Ferramentas
Quando o servidor MCP atualiza suas ferramentas disponíveis:
- Localize o servidor na lista
- Clique no ícone sincronizar (↻)
- Novas ferramentas são carregadas automaticamente
Habilitando/Desabilitando Ferramentas
Controle quais ferramentas o agente pode acessar:
- Expanda o servidor (clique na seta)
- Alterne ferramentas individuais ligado/desligado
- Ferramentas desabilitadas não estarão disponíveis para o agente
Otimização de Performance
Desabilite ferramentas não usadas. Menos ferramentas significa:
- Tomada de decisão mais rápida pelo LLM
- Menor uso de tokens
- Comportamento do agente mais focado
Desabilitando um Servidor
Para desabilitar temporariamente todas as ferramentas sem remover o servidor:
- Alterne o switch ao lado do nome do servidor
- Todas as ferramentas do servidor ficam indisponíveis
Exemplo: Integração com Google Calendar
Passo 1: Configure o Servidor
| Campo | Valor |
|---|---|
| Nome | Google Calendar |
| URL | https://mcp-calendar.exemplo.com/api |
| Transporte | HTTP |
Passo 2: Adicione Autenticação
| Header | Valor |
|---|---|
| Authorization | Bearer {{$GOOGLE_OAUTH_TOKEN}} |
Passo 3: Ferramentas Disponíveis
Após sincronização, ferramentas típicas de calendário incluem:
| Ferramenta | Propósito |
|---|---|
get_calendar_events | Listar eventos futuros |
create_event | Agendar novo evento |
update_event | Modificar evento existente |
delete_event | Remover evento |
check_availability | Encontrar horários livres |
Passo 4: Agente em Ação
Usuário: "Agende uma reunião para amanhã às 14h chamada 'Revisão do Projeto'"
Agente:
- Reconhece intenção de agendamento
- Chama ferramenta
create_eventcom parâmetros - Recebe confirmação do servidor MCP
- Responde: "Pronto! Agendei 'Revisão do Projeto' para amanhã às 14h."
Exemplo: Integração com CRM
Configuração
| Campo | Valor |
|---|---|
| Nome | Salesforce CRM |
| URL | https://mcp-salesforce.exemplo.com/api |
| Transporte | HTTP |
| Authorization | Bearer {{$SALESFORCE_ACCESS_TOKEN}} |
Ferramentas Disponíveis
| Ferramenta | Propósito |
|---|---|
search_contacts | Buscar contatos por nome/email |
get_contact_details | Informações completas do contato |
create_lead | Adicionar novo lead |
update_opportunity | Modificar status de negócio |
log_activity | Registrar interação |
Exemplo de Conversa
Usuário: "Pode encontrar as informações de contato do João Silva?"
Agente: [Usa search_contacts: "João Silva"] "Encontrei João Silva no seu CRM. Ele é VP de Engenharia na Acme Corp. O email dele é joao@acme.com e o telefone é (11) 98765-4321. Gostaria que eu registrasse esta ligação como uma atividade?"
Melhores Práticas
Segurança
| Prática | Por quê |
|---|---|
| Nunca exponha credenciais nas instruções | Previne vazamentos de dados em prompts |
| Use HTTPS para todas as conexões | Criptografa dados em trânsito |
| Rotacione tokens regularmente | Limita danos de credenciais comprometidas |
| Limite permissões às ferramentas necessárias | Princípio do menor privilégio |
Performance
- Mantenha poucos servidores por agente - Cada servidor adiciona latência
- Desabilite ferramentas não usadas - Reduz complexidade de decisão do LLM
- Monitore latência dos servidores - Servidores lentos degradam a experiência
- Configure timeouts apropriados - Previna requisições travadas
Manutenção
- Documente configurações - Ajuda troubleshooting
- Teste após atualizações de servidor - Capture breaking changes
- Monitore logs de execução - Identifique falhas cedo
- Versione seus servidores MCP - Habilite rollbacks
Solução de Problemas
Quando uma chamada falha, o agente recebe um erro tipado e a conversa continua. Use a tabela para saber o que fazer:
| Erro | O que significa | O que fazer |
|---|---|---|
mcp_auth_required | O servidor pediu credenciais, ou a credencial não é mais aceita | Corrija os cabeçalhos ou reconecte a conexão |
mcp_unreachable | Não foi possível alcançar o servidor: DNS, conexão recusada ou falha de rede | Confira a URL, a rede e se o servidor está no ar |
mcp_timeout | A conexão ou a chamada passou do tempo limite | Aumente connect_ms ou call_ms, ou verifique a lentidão do servidor |
mcp_tool_failed | A ferramenta respondeu com erro | Veja a mensagem do servidor; a conversa continua e o modelo decide o próximo passo |
Quando o servidor pede autenticação, o badge da conexão fica Precisa reautenticar e a plataforma oferece reconectar.
Criando Seu Próprio Servidor MCP
Se você quer criar um servidor MCP customizado para suas ferramentas:
Requisitos
- Implemente a especificação MCP
- Exponha endpoint
/toolslistando ferramentas disponíveis - Trate requisições de execução de ferramentas
- Retorne respostas estruturadas
Recursos
- Especificação MCP - Documentação oficial do protocolo
- SDKs MCP - SDKs oficiais para várias linguagens
Alternativa: Ferramentas Manuais
Para integrações mais simples onde você controla o backend, considere Ferramentas Manuais. São mais fáceis de implementar e não requerem um servidor MCP completo.
Documentação Relacionada
- Visão Geral de Ferramentas - Entendendo ferramentas de agentes
- Integração com API - Integrações REST mais simples
- Ferramentas Manuais - Lógica backend customizada
- Testando Agentes - Valide ferramentas no playground