Integração de plugins e servidores MCP
Como conectar um servidor MCP próprio ao Keural e criar um pacote de plugin para o app de desktop.
Os plugins do Keural são servidores MCP (Model Context Protocol). Esta especificação é destinada a desenvolvedores que conectam um servidor MCP próprio ao Keural ou criam um pacote de plugin para o app de desktop.
Métodos de transporte
| Plataforma | Método de transporte | Finalidade |
|---|---|---|
| Web e celular | HTTP (Streamable HTTP) · SSE | Servidores MCP remotos acessíveis pela internet |
| App de desktop | STDIO · HTTP | Servidores executados neste computador, servidores HTTP da rede interna |
- Em conversas na web, use apenas servidores HTTP ou SSE remotos. Servidores STDIO são executados no app de desktop.
- Se o endereço do servidor terminar em
/mcp, normalmente é um servidor Streamable HTTP. Nesse caso, escolha HTTP como transporte. - O HTTP do app de desktop é para endereços da rede interna. Endereços públicos da internet são cadastrados com HTTP na web.
Valores para adicionar manualmente
Os campos em Configurações → Plugins → ＋ Adicionar MCP personalizado são os seguintes.
| Campo | Conteúdo |
|---|---|
| Nome | Obrigatório |
| Descrição | Opcional |
| Transporte | Consulte a tabela acima |
| Categoria | Classificação na lista |
| URL do servidor | Obrigatória para HTTP ou SSE. Exemplo: https://example.com/mcp |
| Comando de execução | Obrigatório para STDIO. Exemplo: npx |
| Argumentos | Argumentos do STDIO (array JSON). Exemplo: ["-y", "@scope/server"] |
| Usar este plugin para pesquisa na web | Se ativado, a pesquisa na web usa este plugin em vez da pesquisa padrão. |
| Autenticação | Nenhuma · Chave de API |
| Nome do cabeçalho · Valor da chave de API | Quando for Chave de API. Exemplo: cabeçalho Authorization, valor Bearer … |
Ao escolher chave de API, o Keural adiciona o cabeçalho <nome do cabeçalho>: <valor> a cada requisição.
Servidores de autenticação OAuth
Os plugins que um administrador da organização cadastrou com OAuth exigem que o usuário clique em Conectar e faça login.
| Item | Valor |
|---|---|
| Descoberta do servidor | /.well-known/oauth-protected-resource (com o caminho; depois, a raiz) e, em seguida, /.well-known/oauth-authorization-server |
| Registro do cliente | Registro dinâmico de cliente (DCR) |
| URI de redirecionamento | https://api.keural.ai/api/user-connectors/oauth/callback |
| Cabeçalho da requisição | Authorization: Bearer <token de acesso> |
A janela de login abre em pop-up e, quando o login termina, a lista de plugins é atualizada.
Permissões das ferramentas
Defina como cada ferramenta do plugin é executada.
| Permissão | Comportamento |
|---|---|
| Sempre permitir | Executa sem confirmação. |
| Exige aprovação | Exibe um card de aprovação antes da execução. Os argumentos da ferramenta são exibidos no card. |
| Bloqueado | O agente não usa esta ferramenta. |
Pacote de plugin para desktop
O app de desktop instala plugins com Arquivo ZIP do plugin… ou Pasta do plugin…. O pacote precisa conter o manifesto plugin.json.
{
"id": "my-plugin",
"name": "My Plugin",
"version": "1.0.0",
"description": "Consulta de sistema interno",
"mcpServers": {
"my-server": {
"command": "node",
"args": ["server.js"],
"env": { "API_BASE": "https://intranet.example.com" }
}
}
}| Campo | Obrigatório | Conteúdo |
|---|---|---|
id | Sim | Letras minúsculas, números e hífens |
name | Não | Nome de exibição. Se ausente, usa-se id. |
version | Não | Padrão 1.0.0 |
description | Não | Descrição |
minAppVersion | Não | Versão mínima do app exigida |
mcpServers | Não | Definições dos servidores MCP. Para cada servidor, command, args e env. |
requests | Não | Permissões solicitadas (capabilities, commands, connectors, secrets, permissions). Array de strings |
Um plugin STDIO cadastrado na web é instalado no app de desktop com Instalar neste PC. Após a instalação, informe manualmente o token de autenticação e as variáveis de ambiente.