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:

1. Agente recebe uma solicitação do usuário
2. LLM decide usar uma ferramenta do servidor MCP
3. SipPulse AI conecta ao servidor MCP
4. Servidor executa a ferramenta e retorna resultados
5. Agente usa resultados para responder ao usuário

---

Configurando um Servidor MCP

Acessando Configuração

1. Navegue para Agentes no menu lateral
2. Selecione ou crie um agente
3. Vá para a seção Ferramentas
4. Clique em Servidores MCP

Adicionando um Servidor

1. Clique em Adicionar Servidor MCP
2. 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	HTTP, SSE, WebSocket
Headers	Headers de autenticação	Authorization: Bearer ...

3. Clique em Criar para adicionar o servidor

Tipos de Transporte

Transporte	Descrição	Melhor Para
HTTP	Request/response tradicional	Ferramentas rápidas, síncronas
SSE	Server-Sent Events	Respostas streaming, operações longas
WebSocket	Conexão bidirecional persistente	Comunicação em tempo real

Detecção Automática

O transporte é auto-detectado por padrões da URL:

• /sse na URL → SSE
• ws:// ou wss:// → WebSocket
• Caso contrário → HTTP

Autenticação

Para servidores que requerem autenticação, adicione headers:

1. Na seção Headers, clique em Adicionar Header
2. Digite o nome e valor do header

Padrões comuns:

Header	Valor	Caso de Uso
Authorization	Bearer {token}	APIs OAuth/JWT
X-API-Key	{sua_chave}	Autenticação por chave API
X-Custom-Header	{valor}	Requisitos customizados

---

Gerenciando Ferramentas

Sincronizando Ferramentas

Quando o servidor MCP atualiza suas ferramentas disponíveis:

1. Localize o servidor na lista
2. Clique no ícone sincronizar (↻)
3. Novas ferramentas são carregadas automaticamente

Habilitando/Desabilitando Ferramentas

Controle quais ferramentas o agente pode acessar:

1. Expanda o servidor (clique na seta)
2. Alterne ferramentas individuais ligado/desligado
3. 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 {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:

1. Reconhece intenção de agendamento
2. Chama ferramenta create_event com parâmetros
3. Recebe confirmação do servidor MCP
4. 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 {sf_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

Servidor Não Conecta

1. Verifique se a URL está correta e acessível
2. Confirme que headers de autenticação são válidos
3. Teste endpoint diretamente com curl:

   curl -X POST https://seu-servidor-mcp.com/api \
     -H "Authorization: Bearer seu_token" \
     -H "Content-Type: application/json"

4. Verifique regras de firewall se self-hosted

Ferramentas Não Aparecem

1. Clique sincronizar para recarregar ferramentas
2. Verifique se servidor MCP retorna lista de ferramentas corretamente
3. Confirme que resposta segue especificação MCP
4. Verifique logs do servidor por erros

Erros de Execução

1. Verifique logs de execução do thread
2. Verifique se parâmetros da ferramenta estão corretos
3. Teste ferramenta diretamente no servidor MCP
4. Revise logs de erro do lado do servidor

Tempos de Resposta Lentos

1. Faça profile de performance do servidor MCP
2. Verifique latência de rede até o servidor
3. Considere caching para consultas repetidas
4. Use transporte SSE para operações longas

---

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 /tools listando 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