Ir para o conteúdo principal

Adicionar um servidor MCP próprio

Com um servidor MCP próprio, você conecta a AI-School a uma aplicação própria, fonte de dados ou serviço especializado. Primeiro, escolha qual transporte se adequa ao local de uso.

Escolha o transporte correto​

TransporteWebMobileDesktopUso
Streamable HTTPSimSimSimRecomendado para servidores hospedados
stdioNãoNãoSimProcessos locais e integrações de desktop
SSEApenas configurações existentesApenas configurações existentesSimTransporte legado; para novos servidores, escolha Streamable HTTP

Requisitos para Streamable HTTP​

Use o endpoint público completo, incluindo o caminho MCP, por exemplo:

https://mcp.example.nl/mcp

O endpoint deve:

  • usar HTTPS;
  • funcionar sem nome de usuário ou senha na URL;
  • não exigir redirecionamento;
  • estar acessível via DNS público;
  • responder a um handshake válido initialize do MCP;
  • ter um conjunto explícito de ferramentas permitidas.

Endereços locais, endereços de rede privada e endpoints de metadados da nuvem são bloqueados. Por isso, você não pode registrar um servidor em localhost a partir da webapp.

Adicionar um servidor​

  1. Abra Preferências → Ferramentas.
  2. Escolha Adicionar ferramentas ou Adicionar servidor MCP. Esse botão só aparece se você tiver acesso a MCP.
  3. Veja primeiro os presets disponíveis.
  4. Escolha Adicionar um servidor MCP próprio.
  5. Preencha nome, endpoint completo e método de autenticação.
  6. Salve a configuração e aguarde a verificação da conexão.
  7. Ative o servidor para seu conjunto padrão de ferramentas.

Um administrador também pode registrar um servidor para todo o ambiente em Administração → Configurações de IA → Ferramentas → MCP.

Autenticação e secrets​

A AI-School suporta OAuth do conector e secrets estáticos. Tokens OAuth, refresh tokens, chaves de API e senhas ficam em armazenamento apenas do servidor. Um chat recebe somente o connectorId registrado, nunca a configuração secreta.

Quando a URL ou a autenticação mudam, a nova configuração é verificada novamente primeiro. Se essa verificação falhar, uma configuração aprovada anteriormente pode permanecer ativa até que o problema seja resolvido.

Permissões de ferramentas​

Disponibilize apenas as ferramentas de que os usuários realmente precisam. Um servidor MCP pode oferecer ações de leitura e gravação, como excluir arquivos, enviar e-mail ou alterar registros. A AI-School filtra as ferramentas descobertas pela allowlist do lado do servidor, mas o administrador do servidor continua responsável pelos escopos e pela autorização adequados.

Teste local​

Você testa um servidor stdio local no aplicativo desktop. O renderer não pode iniciar comandos shell arbitrários: a instalação ocorre por meio de um preset aprovado ou do fluxo seguro para desktop. Comando, argumentos, chaves de ambiente e acesso solicitado são exibidos antes da instalação.

Solução de problemas​

  • Endpoint inacessível: verifique HTTPS, DNS, firewall e o caminho completo /mcp.
  • Reconexão necessária: renove a autorização OAuth ou o secret salvo.
  • Pertence a outro ambiente: registre o conector novamente no ambiente atual.
  • Nenhuma ferramenta visível: verifique a allowlist de ferramentas, seu acesso a MCP e se o servidor está ativo.
  • Funciona apenas no desktop: provavelmente o servidor usa stdio ou um endereço local.

Recursos de desenvolvimento​

Ver também​

Ao editar, a configuração registrada do servidor é recuperada. A chave armazenada permanece oculta: deixe o campo da chave em branco para mantê-la. Com outra URL ou método de autenticação, é necessário reconectar. Um erro em uma única ferramenta MCP não significa que todas as ferramentas desse servidor estejam inacessíveis.

Nesta página