flowral.docs
Início/Agentes & IA

Flowral MCP Manager

Objetivo

Gerenciar servidores MCP locais e remotos para agentes instalados: adicionar, remover, habilitar/desabilitar, atribuir por cliente/projeto, testar transporte, editar configuração, inspecionar permissões e logs sem expor segredos.

Source of truth

Registry normalizado em $XDG_CONFIG_HOME/flowral/mcp/registry.toml (metadados, não credenciais). Um adapter por cliente gera ou edita configurações suportadas, com backup e merge seguro. Não manter um servidor MCP central permanente só para listar registros.

OpenCode V2+ — contrato específico

Estrutura correta: mcp.servers. Propriedade para desativação: disabled: true (não enabled: false). Respeitar precedência global/projeto e que uma definição com o mesmo nome pode substituir a configuração da anterior.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "disabled": true
      },
      "local-example": {
        "type": "local",
        "command": ["example-mcp-server"],
        "environment": { "TOKEN": "{env:EXAMPLE_MCP_TOKEN}" }
      }
    }
  }
}

Exemplo didático, não autoinstalar example-mcp-server nem armazenar TOKEN real em Git. A sintaxe do OpenCode V2 está documentada em https://dev.opencode.ai/v2/docs/mcp-servers/.

Tipos e estado

transport: stdio | Streamable HTTP | outro explicitamente suportado pela versão do cliente. scope: global | project | session (somente quando cliente permite). state: defined | disabled | connecting | ready | auth_required | failed | incompatible. policy: allowlisted executables/URLs; network host approval; redaction; timeout; process/resource limits.

Operações

  • Add: registrar origem (registro oficial, pacote local ou URL), revisar comando, permissões, variáveis.
  • Enable/disable: gravar config do cliente corretamente; avisar se restart de sessão for necessário.
  • Test: iniciar temporariamente, handshake, listar capacidades com tempo limite, encerrar.
  • Remove: remover definição/config local confirmada; perguntar separadamente se apagar binário, dados ou credenciais.
  • Audit: histórico por who/when/what sem registrar tokens.
  • Overrides: detectar colisão de nomes normalizados e shadowing global/project.

Suporte por cliente

OpenCode V2 adapter é prioridade. Claude Code, Codex, Hermes, Antigravity e outros entram por adaptadores versionados somente após inspeção da configuração real, sem presumir formato JSON ou ACP universal.

Segurança

MCP local pode executar código arbitrário do usuário. Mostrar comando real + diretório de trabalho + variáveis visíveis (valores secretos mascarados) antes de ativar. Exigir consentimento separado para comando externo, download/instalação, acesso a arquivos sensíveis e rede. Não instalar por nome arbitrário de pacote sem verificação de origem. Ver segurança.

Testes

Parse round-trip JSONC preservando campos desconhecidos, idempotência, merge sem destruir conteúdo manual, situações de servidor ausente, timeout, processo malicioso que não encerra, OAuth necessário e credenciais incorretas.