MCP (Model Context Protocol)

​

Visão Geral

• Acesso a Ferramentas Externas - Conecte-se a serviços e APIs de terceiros
• Integração de Fontes de Dados - Acesse bancos de dados, sistemas de arquivos e armazenamento em nuvem
• Funcionalidade Personalizada - Adicione ferramentas especializadas para seus casos de uso específicos
• Interface Padronizada - Use um protocolo consistente para todas as integrações
• Autenticação Segura - Suporte para OAuth 2.0 e headers personalizados

​

Como Funciona

​

1. Conexão com Servidor MCP

1. Registro do Servidor - O servidor é registrado na configuração do seu agente
2. Descoberta de Ferramentas - O agente descobre ferramentas disponíveis no servidor MCP
3. Integração de Ferramentas - As ferramentas ficam disponíveis para o agente durante conversas
4. Execução Dinâmica - O agente pode chamar essas ferramentas conforme necessário

​

2. Fluxo de Execução de Ferramentas

User Query → Agent → MCP Tool Call → MCP Server → External System → Response → Agent → User

​

3. Múltiplos Servidores

• Cada servidor fornece seu próprio conjunto de ferramentas
• As ferramentas são prefixadas com o nome do servidor (ex.: sentry_get_errors)
• Os servidores podem ser habilitados ou desabilitados independentemente

​

Início Rápido

​

Adicionando Servidores MCP Populares

1. Navegue até Agentes na barra lateral
2. Selecione ou crie um agente
3. Clique em Editar para abrir o construtor de agentes
4. Vá para a aba MCP
5. Na seção Adição Rápida de Servidores Populares, clique em um card de servidor para adicioná-lo

​

Servidores Populares

​

Sentry

• URL: https://mcp.sentry.dev/mcp
• Transporte: HTTP
• Autenticação: OAuth 2.0
• Escopos: org:read project:write team:write event:write

• Visualizar relatórios de erros
• Monitorar métricas de desempenho
• Gerenciar projetos e equipes
• Rastrear eventos e problemas

​

Tutorial em Vídeo

​

Adicionando Servidores MCP Personalizados

​

Passo 1: Acesse a Configuração MCP

1. Navegue até Agentes na barra lateral
2. Selecione ou crie um agente
3. Clique em Editar para abrir o construtor de agentes
4. Vá para a aba MCP
5. Role até a seção Configuração Avançada

​

Passo 2: Adicione um Novo Servidor

1. Clique no botão Adicionar Servidor
2. O formulário de configuração do servidor aparecerá

​

Passo 3: Configure as Configurações do Servidor

​

Nome do Servidor

• Use letras minúsculas e hífens
• Seja descritivo, mas conciso
• Evite caracteres especiais

​

Tipo de Transporte

• Requisições HTTP padrão
• Ideal para APIs REST e serviços web
• Suporta padrão de requisição/resposta

• Comunicação por streaming em tempo real
• Ideal para feeds de dados ao vivo
• Suporta streaming unidirecional do servidor ao cliente

​

URL do Servidor

• https://api.example.com/mcp
• http://localhost:8000/mcp/
• https://mcp.example.com/v1

• https://api.example.com/sse
• https://stream.example.com/events

​

Passo 4: Configure a Autenticação

​

Sem Autenticação

​

OAuth 2.0

1. Selecione OAuth 2.0 como método de autenticação
2. Insira os Escopos OAuth (separados por espaço)
   • Exemplo: read write admin
   • Exemplo: org:read project:write team:write

• Quando um usuário interage com o agente, ele será solicitado a autorizar
• A autorização é tratada automaticamente
• Os tokens são armazenados com segurança e atualizados conforme necessário

​

Passo 5: Headers Personalizados (Opcional)

1. Clique em Adicionar Header
2. Insira o nome do header (ex.: X-API-Key, Authorization)
3. Insira o valor do header
4. Adicione headers adicionais conforme necessário

• X-API-Key: your-api-key
• Authorization: Bearer token
• X-Custom-Header: custom-value

​

Passo 6: Habilitar/Desabilitar Servidor

• Habilitado: As ferramentas do servidor estão disponíveis para o agente
• Desabilitado: As ferramentas do servidor estão ocultas, mas a configuração é preservada

​

Passo 7: Teste a Conexão

1. Clique no botão Testar para verificar a conexão
2. Aguarde o resultado do teste:
   • Sucesso: O servidor está acessível e configurado corretamente
   • Erro: Verifique sua configuração e conectividade de rede

​

Passo 8: Salve a Configuração

1. Clique em Salvar para armazenar a configuração do seu servidor MCP
2. O servidor agora está disponível para o seu agente

​

Gerenciando Servidores MCP

​

Visualizando Servidores Configurados

• Contagem de Servidores - Número de servidores configurados
• Status do Servidor - Status habilitado/desabilitado
• Nomes dos Servidores - Lista de todos os servidores configurados

​

Editando a Configuração do Servidor

1. Encontre o servidor na seção Configuração Avançada
2. Clique para expandir a configuração do servidor
3. Modifique qualquer configuração
4. Clique em Testar para verificar as alterações
5. A configuração é salva automaticamente

​

Removendo Servidores

1. Encontre o servidor que deseja remover
2. Clique no ícone Remover (lixeira)
3. Confirme a remoção
4. O servidor é removido da configuração do seu agente

​

Habilitando/Desabilitando Servidores

• Habilitar: Torna as ferramentas do servidor disponíveis
• Desabilitar: Oculta as ferramentas do servidor, mas preserva a configuração

• Desabilitar temporariamente servidores com problemas
• Testar diferentes configurações de servidor
• Gerenciar a disponibilidade do servidor sem remover a configuração

​

Tipos de Transporte

​

HTTP (streamable_http)

• Conectando-se a APIs REST
• Padrões de requisição/resposta padrão
• Serviços web e microsserviços

• A URL deve apontar para o endpoint MCP
• Suporta métodos HTTP padrão
• Funciona com a maioria dos serviços web

URL: https://api.example.com/mcp
Transport: HTTP

​

SSE (Server-Sent Events)

• Streams de dados em tempo real
• Atualizações ao vivo e notificações
• Comunicação unidirecional do servidor ao cliente

• A URL deve apontar para o endpoint SSE
• O servidor deve suportar o protocolo SSE
• Reconexão automática após desconexão

URL: https://stream.example.com/sse
Transport: SSE

​

Métodos de Autenticação

​

Sem Autenticação

• APIs públicas
• Serviços internos
• Servidores de desenvolvimento/testes

• Selecione Sem Autenticação
• Nenhuma configuração adicional necessária

​

OAuth 2.0

• Serviços de terceiros (Sentry, Canva, etc.)
• Acesso a dados específicos do usuário
• Permissões com escopo

1. Selecione OAuth 2.0
2. Insira os escopos OAuth (separados por espaço)
3. Os usuários autorizarão no primeiro uso

• Sentry: org:read project:write team:write event:write
• Canva: asset:read asset:write design:read design:write
• Personalizado: read write admin

1. O usuário interage com o agente
2. O agente precisa de uma ferramenta MCP de um servidor protegido por OAuth
3. O usuário é solicitado a autorizar
4. A autorização é concluída automaticamente
5. O token é armazenado com segurança
6. Solicitações futuras usam o token armazenado

​

Headers Personalizados

• Chaves de API
• Tokens de autenticação personalizados
• Headers específicos de serviço
• Metadados de solicitação

​

Adicionando Headers

1. Na configuração do servidor, encontre a seção Headers Personalizados
2. Clique em Adicionar Header
3. Insira o nome do header (ex.: X-API-Key)
4. Insira o valor do header
5. Adicione mais headers conforme necessário

​

Padrões Comuns de Headers

Header: X-API-Key
Value: your-api-key-here

Header: Authorization
Value: Bearer your-token-here

Header: X-Service-Name
Value: your-service-identifier

​

Casos de Uso

​

Monitoramento de Erros

{
  "server_name": "sentry",
  "transport": "streamable_http",
  "url": "https://mcp.sentry.dev/mcp",
  "auth_type": "oauth",
  "oauth_scopes": "org:read project:write team:write event:write"
}

• “Mostre-me os erros das últimas 24 horas”
• “Qual é a taxa de erros do projeto X?”
• “Liste todos os problemas não resolvidos”

​

Acesso a Banco de Dados

{
  "server_name": "postgres-db",
  "transport": "streamable_http",
  "url": "https://mcp.example.com/database",
  "auth_type": "oauth",
  "headers": {
    "X-Database-Name": "production"
  }
}

• “Consulte a tabela de usuários”
• “Mostre-me os pedidos recentes”
• “Obtenha estatísticas de clientes”

​

Acesso ao Sistema de Arquivos

{
  "server_name": "filesystem",
  "transport": "streamable_http",
  "url": "https://mcp.example.com/files",
  "auth_type": "oauth"
}

• “Liste os arquivos na pasta de documentos”
• “Leia o arquivo de configuração”
• “Pesquise arquivos contendo ‘error‘“

​

Streams de Dados em Tempo Real

{
  "server_name": "live-data",
  "transport": "sse",
  "url": "https://stream.example.com/sse",
  "auth_type": "oauth"
}

• “Mostre-me as cotações de ações ao vivo”
• “Monitore as métricas do sistema”
• “Rastreie eventos em tempo real”

​

Melhores Práticas

​

Nomenclatura de Servidores

• Seja Descritivo: Use nomes claros e significativos
• Use Minúsculas: Prefira minúsculas com hífens
• Evite Caracteres Especiais: Mantenha-se a letras, números e hífens
• Seja Consistente: Siga uma convenção de nomenclatura

• sentry-monitoring
• postgres-production
• weather-api

• Server1
• my_mcp_server
• MCP-Server!!!

​

Configuração de URL

• Use HTTPS: Prefira sempre conexões seguras
• Inclua o Caminho Completo: Especifique a URL completa do endpoint
• Teste as URLs: Verifique se as URLs estão acessíveis antes de salvar
• Documente os Endpoints: Mantenha documentação dos seus endpoints

​

Autenticação

• Use OAuth Quando Possível: Mais seguro que chaves de API
• Minimize os Escopos: Solicite apenas permissões necessárias
• Armazene com Segurança: Os tokens são tratados automaticamente
• Teste a Autorização: Verifique se o fluxo OAuth funciona corretamente

​

Tratamento de Erros

• Teste as Conexões: Use o botão Testar antes de salvar
• Monitore os Logs: Verifique erros de conexão
• Trate Falhas: Configure fallbacks para servidores críticos
• Desabilite Servidores com Problemas: Desabilite temporariamente se necessário

​

Desempenho

• Limite a Quantidade de Servidores: Muitos servidores podem desacelerar os agentes
• Desabilite Servidores Não Usados: Mantenha apenas servidores ativos habilitados
• Otimize os Headers: Inclua apenas headers personalizados necessários
• Monitore Tempos de Resposta: Observe respostas lentas de servidores MCP

​

Solução de Problemas

​

Falhas de Conexão

• URL incorreta
• Problemas de conectividade de rede
• Servidor não está em execução
• Firewall bloqueando a conexão

• Verifique se a URL está correta e acessível
• Verifique a conectividade de rede
• Certifique-se de que o servidor está em execução
• Revise as regras de firewall

​

Erros de Autenticação

• Escopos OAuth incorretos
• O servidor não suporta OAuth
• O usuário não autorizou
• Token expirado

• Verifique se os escopos OAuth estão corretos
• Consulte a documentação OAuth do servidor
• Reautorize a conexão
• Verifique as configurações de expiração do token

​

Ferramentas Indisponíveis

• O servidor está desabilitado
• A conexão não foi estabelecida
• O servidor não está respondendo
• A descoberta de ferramentas falhou

• Habilite o servidor
• Teste a conexão
• Verifique se o servidor está em execução
• Verifique os logs do servidor

​

Erros de Timeout

• Resposta lenta do servidor
• Latência de rede
• Servidor sobrecarregado
• Configurações de timeout incorretas

• Verifique o desempenho do servidor
• Verifique a velocidade da rede
• Reduza a carga do servidor
• Ajuste as configurações de timeout, se configurável

​

Testando Servidores MCP

​

Testar Conexão

1. Configure seu servidor MCP
2. Clique no botão Testar
3. Aguarde os resultados:
   • Sucesso: Indicador verde com mensagem de sucesso
   • Erro: Indicador vermelho com detalhes do erro

​

Resultados dos Testes

• Mensagem de conexão bem-sucedida
• Servidor respondendo corretamente
• Autenticação funcionando (se aplicável)

• Timeout de conexão
• Autenticação falhou
• URL inválida
• Servidor não respondendo

​

Interpretando os Resultados

✓ Connection successful
MCP server connection tested successfully

✗ Connection failed
Failed to connect to server: Connection timeout

​

Considerações de Segurança

​

Segurança OAuth

• Armazenamento de Tokens: Os tokens são armazenados com segurança
• Atualização de Tokens: Atualização automática de tokens quando expiram
• Limitação de Escopos: Solicite os escopos mínimos necessários
• Autorização do Usuário: Os usuários devem autorizar explicitamente

​

Headers Personalizados

• Dados Sensíveis: Não coloque dados sensíveis nos headers, se evitável
• Chaves de API: Use OAuth quando possível em vez de chaves de API
• Visibilidade dos Headers: Os headers são armazenados na configuração
• Controle de Acesso: Limite quem pode visualizar/editar configurações MCP

​

Segurança de Rede

• Apenas HTTPS: Use sempre HTTPS para servidores de produção
• Redes Internas: Use URLs internas para servidores privados
• Regras de Firewall: Configure firewalls adequadamente
• Acesso via VPN: Use VPN para conexões seguras quando necessário

​

Exemplos

​

Exemplo 1: Integração com Sentry

{
  "server_name": "sentry",
  "transport": "streamable_http",
  "url": "https://mcp.sentry.dev/mcp",
  "auth_type": "oauth",
  "oauth_scopes": "org:read project:write team:write event:write",
  "enabled": true
}

• O agente pode monitorar erros
• Visualizar métricas de desempenho
• Gerenciar projetos Sentry

​

Exemplo 2: Integração com API Personalizada

{
  "server_name": "custom-api",
  "transport": "streamable_http",
  "url": "https://api.example.com/mcp",
  "auth_type": "oauth",
  "oauth_scopes": "read write",
  "headers": {
    "X-Client-ID": "your-client-id"
  },
  "enabled": true
}

• O agente pode chamar endpoints de API personalizados
• Acessar recursos protegidos
• Usar headers personalizados para identificação

​

Exemplo 3: Serviço Interno

{
  "server_name": "internal-service",
  "transport": "streamable_http",
  "url": "http://internal-service:8000/mcp",
  "auth_type": "none",
  "headers": {
    "X-Internal-Key": "internal-key-value"
  },
  "enabled": true
}

• O agente pode acessar serviços internos
• Nenhum OAuth necessário
• Header personalizado para autenticação interna

​

Recursos Relacionados

• Toolkits - Integrações e ferramentas integradas
• Ferramentas - Ferramentas e ações personalizadas
• Configuração do Agente - Configure o comportamento do agente
• Integração de API - Conecte-se a APIs externas

​

Suporte