Ferramentas e MCP

Ferramentas permitem que um agente leia informações ou execute ações. O Maestrly tem três tipos: as Ferramentas do Maestrly, as ferramentas da gaveta que você usa junto com o agente (terminal, navegador, editor) e os servidores MCP (Model Context Protocol) que você adiciona. O modo e o modo de permissão da conversa decidem o que o agente pode de fato fazer com elas.

Ferramentas do Maestrly

Desde a 0.14.0, as Ferramentas do Maestrly vêm ligadas por padrão, em grupos que você liga ou desliga separadamente. Escolhas que você já tinha feito são mantidas.

Grupo	O que dá ao agente
Terminal	Rodar e acompanhar comandos nos terminais da gaveta
Navegador	Navegar, ler e interagir com páginas no navegador da gaveta
Notas	Os cadernos da conversa e do projeto
Memória	Buscar e salvar memórias duráveis
Histórico da conversa	Buscar trechos anteriores da conversa
Debug	Breakpoints e passo a passo na aba Código, que precisa estar aberta
Artefatos	Publicar e atualizar páginas web, e ler os comentários e as respostas delas; veja Artefatos

Defina o padrão em Configurações → Maestrly Chat → Ferramentas: a chave Ferramentas do Maestrly liga ou desliga todas, e cada grupo tem a própria chave. Numa conversa, abra + → Ferramentas do Maestrly → Escolher os grupos desta conversa. Mudar um grupo ali fixa só esse grupo; os demais continuam seguindo as Configurações. Desligar grupos que você não usa economiza contexto, principalmente em modelos menores. Bots mantêm as Ferramentas do Maestrly sempre ligadas.

A mesma aba tem ajustes relacionados:

Busca na web (desde a 0.18.0) permite que os modelos pesquisem na web com a ferramenta web_search, em todos os runtimes. Escolha Automático, Tavily (chave de API), Brave Search (chave de API), Assinatura do ChatGPT, DuckDuckGo (sem chave, pode ser bloqueado) ou Desativada. As consultas vão para o provedor escolhido; o Automático usa primeiro uma chave de API configurada, depois sua assinatura do ChatGPT e, por fim, o DuckDuckGo. O webfetch continua lendo uma URL específica.
Respostas interativas (desde a 0.18.0) permite que os modelos respondam com pequenas interfaces que você vê e usa. Veja Chat, modelos e contexto. Desligar economiza cerca de 850 tokens de instruções por conversa.

Geração de imagem permite que os modelos criem imagens com a ferramenta generate_image (o Codex usa o gerador nativo dele). Desde a 0.25.0, Gerador escolhe Automático (padrão), ChatGPT ou Google AI (Gemini), consumindo a cota da assinatura conectada. O Automático usa primeiro o ChatGPT e depois o Google AI, enquanto conversas no Google AI usam primeiro a própria conta; uma escolha explícita nunca cai para a outra assinatura (a geração de imagens pelo Google AI exige o runtime 1.4.0). Saída compacta de comandos filtra a saída verbosa de comandos de shell compatíveis antes de chegar ao modelo, para economizar tokens.

Ferramentas da gaveta

A gaveta, aberta pelo cabeçalho da conversa, reúne as ferramentas que você e o agente usam juntos: Navegador, Código (um VS Code embutido), Terminal, Plano, Review e Notas. Use Abrir uma ferramenta (+) e Buscar ferramenta… para adicionar uma aba. As abas ficam guardadas por conversa e você pode arrastá-las para reordenar.

Configurações → Tools e gaveta define a ordem padrão das Abas da gaveta para conversas novas e os Atalhos das tools. Uma ferramenta também pode abrir numa janela flutuante.
Os agentes são orientados a usar os terminais da gaveta para processos que você quer acompanhar, como servidores de desenvolvimento ou modos watch, e o próprio shell para comandos rápidos e pontuais. Um comando bash termina quando o shell dele encerra, mesmo se um programa deixado em segundo plano ainda segurar a saída.
O navegador embutido é um cliente de rede real, separado do navegador do sistema. Ele nega pedidos de permissão dos sites por padrão. Os sites em que você entra por ele também ficam disponíveis para agentes que usam as ferramentas de Navegador (num bot, as ferramentas de Navegador controlam o próprio Chromium no desktop dele, com perfil e logins de sites próprios; veja Bots). Desde a 0.26.0, os snapshots incluem elementos em shadow roots abertos e frames da mesma origem, as ações rolam um elemento que mudou de lugar até a tela ou avisam quando ele sumiu, e chamadas numa página que parou de responder expiram para que a próxima navegação ou recarga a reinicie.
A barra de endereço sugere páginas do histórico e das abas abertas, além de sugestões de busca do Google, e completa sites frequentes enquanto você digita. Entradas como localhost:3000 e IPs locais abrem por HTTP em vez de virar uma busca. Cmd+T (Ctrl+T) abre uma aba e Cmd+W (Ctrl+W) fecha a aba ativa sem fechar a janela. O texto digitado que não é um endereço, host local ou IP vai para o serviço de sugestões do Google, sem cookies.
O histórico é compartilhado por todas as conversas e fica neste computador. Remover do histórico (o × de uma sugestão, ou Shift+Delete) tira uma página, e Limpar dados de navegação apaga o histórico junto com cache, cookies e storage do navegador.
Se o editor travar, Reiniciar o VS Code o reinicia sem fechar o app. A primeira configuração baixa o servidor do VS Code da Microsoft (mostrando o progresso em porcentagem e megabytes, depois Instalando… e Iniciando o editor…), e enquanto você tiver aberto a aba Código nos últimos 14 dias, versões novas do VS Code são baixadas em segundo plano.

Permissões

Cada conversa tem um modo de permissão no composer:

Modo	Comportamento
Solicitar aprovação	Pede aprovação antes de editar arquivos, rodar comandos e usar a internet.
Aprovar por mim	Pede aprovação só para ações potencialmente perigosas, como comandos de shell e pastas fora do projeto.
Acesso completo	Nunca pergunta. Use só com repositórios e instruções em que você confia.

Conversas novas começam com Configurações → Execução → Modo de permissão padrão (Perguntar antes, Automático ou Acesso total). Chats avulsos novos começam no último modo que você escolheu num deles (Pergunta na primeira vez), com Solicitar aprovação. Um pedido oferece Permitir uma vez, Sempre permitir (salvo para o projeto; Sempre permitir neste chat num chat avulso) ou Negar.

Sempre permitir num comando salva uma regra como npm test *. Desde a 0.22.0, o Maestrly divide o comando em todos os comandos que ele rodaria, do jeito que o shell dele lê, e cada um precisa estar permitido; assim, um comando mais longo montado para esconder um segundo não casa mais com uma regra salva. Um comando cuja estrutura ele não consegue ler com certeza não casa com nenhuma regra: pergunta toda vez, a menos que a conversa tenha acesso total, e não oferece Sempre permitir. Comandos comuns, com pipes inclusive, continuam casando com as regras deles.

Os modos também restringem as ferramentas: Pergunta e Plano expõem só ferramentas MCP somente leitura e as Ferramentas do Maestrly permitidas naquele modo. Um modo de permissão não é um sandbox. Os comandos rodam com o acesso da sua conta no sistema operacional, no /bin/sh no macOS e no Linux e, desde a 0.22.0, no Windows PowerShell 5.1 no Windows. Os modelos e os subagents sabem qual é o shell.

Adicionar um servidor MCP

Abra Configurações → Maestrly Chat → Ferramentas → Servidores MCP e escolha Adicionar servidor MCP:

HTTP: a URL do servidor e eventuais headers, um por linha, como Authorization: Bearer ....
stdio: o comando (por exemplo npx), os argumentos e os valores de ambiente, um por linha.

Cada servidor tem a própria chave de liga/desliga, e + → Servidores MCP liga ou desliga servidores numa conversa. O Maestrly só lista as ferramentas de um servidor quando uma conversa precisa delas pela primeira vez. Ferramentas MCP pedem aprovação ao serem usadas, conforme o modo de permissão da conversa.

Desde a 0.11.0, os dados de conexão MCP (URLs, headers, comandos, argumentos e valores de ambiente) ficam criptografados em repouso quando o armazenamento seguro do sistema operacional está disponível. Sem ele, ficam legíveis no perfil do app, então trate esse perfil como sensível. Versões anteriores à 0.11.0 não leem os dados criptografados: depois de um downgrade, configure esses servidores de novo.

Desde a 0.20.0, um servidor HTTP que exige OAuth mostra Precisa entrar: escolha Entrar e termine no navegador. O host que roda o servidor guarda o login e o renova. Um servidor pode ter várias contas (Adicionar conta, Renomear, Entrar de novo, Remover), cada uma valendo para todas as conversas ou para projetos escolhidos; com várias, o modelo diz qual conta usa em cada chamada. Servidores que não registram apps sozinhos, como os do Google e do Slack, usam um cliente OAuth seu. Veja os detalhes em Plugins. Desde a 0.21.0, um servidor stdio que para logo ao iniciar diz por quê: o erro dele, com os valores de ambiente mascarados, chega ao modelo e ao Testar conexão.

Ambientes de bots têm os próprios servidores MCP, configurados pelo app; veja Bots.

Plugins

Plugins reúnem skills e servidores MCP, e às vezes comandos, agentes e hooks, de fontes Codex, Claude Code e Agent Plugins no Git. Instale em Configurações → Maestrly Chat → Plugins, aprove o que eles rodam, e as partes deles funcionam igual com qualquer modelo. Os servidores deles aparecem marcados como vindos do plugin e podem ser desligados por conversa como qualquer outro. Veja Plugins.

Revisar o acesso antes de habilitar

Para cada servidor ou ferramenta, pergunte:

Quais dados ela pode ler?
O que ela pode criar, alterar, enviar ou excluir?
Ela chama um serviço remoto?
Qual conta e quais permissões ela usa?
Ações importantes vão esperar sua aprovação?

Habilite o menor conjunto necessário. Uma tarefa somente de leitura raramente precisa de acesso de escrita ou administração.

Usar ferramentas num chat

Declare na solicitação qualquer limite importante, como repositório, banco de dados, workspace ou intervalo de datas. Acompanhe as primeiras chamadas e confirme argumentos e destinos antes de permitir uma execução mais ampla. O modelo escolhido precisa aceitar chamadas de ferramentas, e um servidor pode estar indisponível, limitado por taxa ou restrito pelo plano da própria conta.

Entender o caminho dos dados

Servidores stdio locais rodam na sua máquina, mas podem contatar serviços externos.
Servidores remotos recebem os dados necessários para executar suas ferramentas.
Seu provedor de IA recebe prompt, descrições das ferramentas, contexto relevante e resultados necessários para a inferência.
O navegador embutido, as ferramentas web e as buscas de skills contatam os sites que você ou o agente abrirem.
O Maestrly não tem backend hospedado nem proxy de inferência/MCP. As integrações conectam-se diretamente aos seus destinos.

Revise os termos de privacidade de cada provedor e servidor antes de enviar dados sensíveis.

Resolver falhas com segurança

Servidor não inicia: confirme que o executável existe, que os argumentos são válidos e que os valores de ambiente necessários estão presentes.
Mensagem "Configure de novo": os dados de conexão salvos não podem ser lidos neste computador. Remova o servidor e adicione-o de novo.
Falha de autenticação: confira os headers ou escolha Entrar de novo quando o servidor mostrar Precisa entrar e use permissões restritas quando possível.
Ferramenta ausente: confira a chave do servidor, as escolhas de Servidores MCP e Ferramentas do Maestrly da conversa e o modo; Pergunta e Plano expõem só ferramentas MCP somente leitura.
Chamada expira: confira rede, saúde do servidor e limites de taxa antes de tentar de novo.
Ação inesperada: pare a execução, desligue o servidor ou a ferramenta, revise o que foi feito e troque credenciais expostas se necessário.

A seguir: Plugins.