Conectar o servidor MCP
O servidor MCP do Aggrega é o comando aggrega mcp, e o binário aggrega é seu único pré-requisito: Instalar o binário o instala com um único comando. O servidor é executado como subprocesso do seu cliente via stdio, lê seus schemas do binário e suas páginas de documentação de uma cópia que baixa uma única vez para o cache da sua máquina, e não precisa de nenhum serviço, porta ou conta separados. Quando outra pessoa já executa um servidor para você, você não precisa nem do binário nem de nada disto: veja Um servidor acessado por HTTPS.
Clientes que o adicionam com um único comando
Um assistente com o plugin do Aggrega instalado já está conectado. Instalar o plugin adiciona a skill do Aggrega e o servidor em uma única etapa — no Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro e OpenClaw, como descreve Instalar o plugin —, então nada mais nesta página é necessário para conectar esse assistente. O plugin inicia aggrega mcp com o aggrega encontrado no PATH com que o assistente foi iniciado, então o binário precisa estar instalado ali. Alguns assistentes iniciam o servidor de um plugin na própria pasta do plugin, e não no seu projeto — o Codex faz isso —, e o assistente então informa a pasta do seu projeto como workspace_root nas chamadas que o aceitam; a skill diz a ele para verificar em qual workspace o servidor responde.
Sem o plugin, adicione o servidor com o comando próprio do cliente. No Claude Code:
claude mcp add --transport stdio aggrega -- aggrega mcpNo Codex:
codex mcp add aggrega -- aggrega mcpNo Gemini CLI:
gemini mcp add aggrega aggrega mcpTodos os outros clientes
A maioria dos clientes compatíveis com MCP inicia o servidor da mesma forma — eles executam o comando aggrega com um único argumento mcp e falam o protocolo pela entrada e saída padrão do processo. O que muda entre eles é onde cada um mantém sua lista de servidores e como chama as entradas dela. O formato comum:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Depois que o cliente é reiniciado e se conecta, os prompts, os recursos e as ferramentas de criação do Aggrega ficam disponíveis. O que seu assistente pode fazer com o Aggrega os descreve, Criar arquivos do Aggrega mostra o que fazer com eles, e a referência de aggrega mcp cobre o próprio comando.
Nada na entrada seleciona uma revisão do protocolo. Aggrega fala tanto 2026-07-28 quanto 2025-06-18, pela entrada e saída padrão e também via HTTPS, de modo que um cliente de qualquer uma delas se conecta e chega aos mesmos prompts, recursos e ferramentas. Qual delas um cliente solicita é decidido na comunicação, e não na sua configuração.
Um assistente capaz de executar comandos pode fazer tudo isso sozinho — instalar o binário, adicionar a skill do Aggrega e se conectar ao servidor — a partir de um único prompt que você cola nele: veja Configurar o Aggrega com seu assistente de IA.
Onde cada cliente mantém sua lista de servidores
| Cliente | Onde fica a lista | Como a entrada se chama |
|---|---|---|
| Claude Code | claude mcp add, ou um arquivo .mcp.json no projeto | mcpServers |
| Claude Desktop | suas configurações de extensões para um servidor local; suas configurações de conectores para um acessado via HTTPS | consulte Claude Desktop |
| Cursor | .cursor/mcp.json para um workspace, ou um mcp.json no escopo do usuário para todos os workspaces | mcpServers |
| Gemini CLI | gemini mcp add, ou ~/.gemini/settings.json para todos os projetos e .gemini/settings.json para um | mcpServers |
| Codex CLI | codex mcp add, ou ~/.codex/config.toml para todos os projetos e .codex/config.toml para um projeto confiável | uma tabela [mcp_servers.aggrega] — consulte Codex CLI |
| Zed | Settings → AI → MCP Servers, que grava a entrada no arquivo de configurações do Zed | context_servers — consulte Zed |
| Visual Studio Code | mcp.json no seu perfil de usuário, ou .vscode/mcp.json para um workspace | servers — consulte Visual Studio Code |
| GitHub Copilot CLI | copilot mcp add, ou o arquivo mcp-config.json que ele mantém no seu diretório pessoal | mcpServers |
| Antigravity | o arquivo mcp_config.json acessível pelas suas configurações | mcpServers |
| Windsurf | o arquivo mcp_config.json acessível pelas suas configurações | mcpServers |
| Cline | suas configurações de MCP, baseadas em um arquivo cline_mcp_settings.json | mcpServers |
Todos os clientes dessa tabela, exceto os quatro que têm uma seção própria abaixo, aceitam a entrada exatamente como escrita acima, no caminho indicado na sua linha. Um cliente não listado se conecta da mesma forma se ler uma lista de servidores em um destes formatos.
Uma observação sobre o PATH
Clientes iniciados a partir de um ambiente gráfico nem sempre herdam o mesmo PATH do seu terminal. Se um cliente informar que não encontra o comando aggrega, substitua "command": "aggrega" pelo caminho absoluto do binário (por exemplo "command": "/home/you/.local/bin/aggrega", o local de instalação no Linux para um usuário chamado you). Todo o resto permanece igual.
Visual Studio Code
O Visual Studio Code mantém seus servidores em servers em vez de mcpServers, e cada entrada indica o transporte que usa:
{ "servers": { "aggrega": { "type": "stdio", "command": "aggrega", "args": ["mcp"] } }}Codex CLI
O Codex mantém seus servidores em TOML em vez de JSON — em ~/.codex/config.toml para todos os projetos, ou em .codex/config.toml para um projeto em que o Codex confia — cada um como uma tabela com o nome do servidor:
[mcp_servers.aggrega]command = "aggrega"args = ["mcp"]codex mcp add aggrega -- aggrega mcp, o comando acima, grava a mesma tabela para você. A extensão de IDE do Codex e o aplicativo de desktop do ChatGPT leem o mesmo arquivo, então a única entrada serve aos três.
Zed
O Zed mantém seus servidores em context_servers no seu arquivo de configurações. Adicione o servidor em Settings → AI → MCP Servers — Add Server e depois Add Local Server — o que grava a entrada nesse arquivo, ou execute zed: open settings file na paleta de comandos e adicione a entrada você mesmo:
{ "context_servers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}O Zed oferece suporte às ferramentas e aos prompts do protocolo, então seu agente alcança as ferramentas e os prompts de criação do Aggrega, mas não os recursos que o servidor também oferece.
Claude Desktop
O Claude Desktop instala um servidor local a partir de um pacote de extensão — o servidor junto com um manifesto que o descreve, reunidos em um único arquivo instalável e adicionados pelas suas configurações de extensões — em vez de a partir de uma entrada em um arquivo de configuração. Cada release de Aggrega traz um pacote desse tipo, aggrega-<version>.mcpb, ao lado dos seus binários pré-compilados.
O pacote de Aggrega não traz nenhum programa próprio. Ele inicia um executável aggrega já instalado na sua máquina, com o único argumento mcp, e fala o protocolo pela entrada e saída padrão desse processo — o mesmo servidor que cada entrada acima inicia. A menos que você escolha outro executável, ele entrega ao Claude Desktop o nome de comando aggrega, como faz cada entrada acima, de modo que o aplicativo procura aggrega no PATH com que foi iniciado; e entrega a esse servidor o workspace que você escolher. Para adicioná-lo:
- Instale o binário
aggrega, como descrito em Instalar o binário. O comando de instalação e as etapas manuais descritas lá o mantêm em uma pasta sua — no Windows,%LOCALAPPDATA%\Programs\aggregaem vez de uma pasta do sistema comoC:\Windows\System32— para que você possa substituí-lo sem direitos de administrador. - Instale
aggrega-<version>.mcpbpelas configurações de extensões do Claude Desktop. - Defina as configurações do pacote; nenhuma é obrigatória. Path to the aggrega executable é o programa que o pacote inicia, e seu padrão é o nome de comando
aggrega, que o aplicativo procura noPATHcom que foi iniciado. Uma pasta adicionada ao seuPATHenquanto o aplicativo está em execução — como o instalador do Windows e o comando de instalação no Windows adicionam a deles — só chega a ele depois que ele é encerrado e iniciado novamente, como na etapa 4, e um aplicativo iniciado a partir de um ambiente gráfico pode não ver o mesmoPATHque o seu terminal (veja Uma observação sobrePATH). Mantenha o padrão quando oaggreganessePATHfor o executável que você quer. Em vez disso, defina o campo como o caminho completo de um executável quando o que você quer não estiver nessePATH, ou for umaggregadiferente do primeiro encontrado ali — no macOS e no Linux, para o local de instalação, oaggregaem.local/binna sua pasta pessoal, como/Users/you/.local/bin/aggrega; no Windows, o caminho completo terminado emaggrega.exe, comoC:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe. Para voltar ao padrão, defina o campo comoaggregaem vez de esvaziá-lo. Onde nenhumaggregaestiver instalado, instale-o como descreve a etapa 1. Workspace folder é a pasta do workspace Aggrega em que o assistente trabalha: a pasta que contém o.aggrega-config.yamldo seu projeto. Defina esta: ela fica vazia até você escolher uma pasta, e enquanto está vazia o pacote entrega ao servidor umAGGREGA_WORKSPACE_ROOTvazio, de modo que o servidor responde a cada solicitação que o assistente faz no workspace com uma recusa dizendo que a configuração Workspace folder está vazia e pedindo que você a defina como a pasta que contém o.aggrega-config.yamldo seu workspace, em vez de trabalhar na pasta em que o Claude Desktop o iniciou. O pacote entrega a pasta ao servidor somente quando o aplicativo o inicia, então uma pasta que você define enquanto o servidor está em execução entra em vigor depois que você desativa e reativa a extensão nas configurações de extensões, ou reinicia o aplicativo como na etapa 4. - Encerre o Claude Desktop por completo e inicie-o novamente. Um servidor que o aplicativo já iniciou continua em execução, e renomear o executável não o interrompe, então uma configuração alterada só entra em vigor quando o aplicativo inicia o servidor novamente: depois que ele é encerrado e iniciado novamente ou, para Workspace folder, depois que a extensão é desativada e reativada. No Windows, o Gerenciador de Tarefas mostra se um processo
aggregaainda está em execução.
A pasta do workspace é onde é respondida cada solicitação que não indica um workspace próprio. O Claude Desktop inicia o servidor em uma pasta escolhida por ele, e não no seu projeto, então o pacote passa a pasta que você escolheu para o servidor como a variável AGGREGA_WORKSPACE_ROOT no ambiente dele, em vez de como um argumento na linha de comando que o aplicativo monta. O servidor toma essa pasta como a própria raiz do workspace, assim como --workspace-root é tomado em cada comando: ele não procura acima dela um workspace que a contenha, então escolha a pasta que contém .aggrega-config.yaml, e não uma dentro dela. Para trabalhar em outro workspace, altere a configuração e reinicie o aplicativo como na etapa 4. Em uma solicitação que indica um workspace próprio com um workspace_root relativo, ele também é lido a partir da pasta do workspace, de modo que um prompt indica uma pasta dentro dela — como quickstart-ai/1 — sem saber onde a pasta fica na sua máquina; um workspace_root absoluto é usado como informado. Enquanto a configuração estiver vazia, um relativo recebe a mesma recusa que uma solicitação que não indica nenhum.
Como o pacote não indica nenhum executável de nenhuma plataforma, o mesmo arquivo vale para cada plataforma que ele declara: macOS, Windows e Linux.
O servidor informa qual aggrega o pacote iniciou. As configurações de extensões do Claude Desktop mostram a versão do próprio pacote — a versão da release de onde ele veio — e não a versão do executável que ele inicia. Os dois são instalados separadamente, então podem vir de releases diferentes. O pacote entrega ao servidor sua própria versão como a variável AGGREGA_BUNDLE_VERSION no ambiente dele, e o servidor informa ambas: a resposta de describe-capabilities chamado sem argumentos — a ferramenta que um assistente chama para saber o que o servidor oferece — começa com uma linha que indica a versão do executável e a do pacote, e traz a mesma linha como version_summary na sua parte estruturada, de modo que um assistente a quem se pergunta qual versão de Aggrega está em execução pode ler ambas ali, qualquer que seja a parte da resposta que o aplicativo lhe entregue. Quando as duas vêm de releases diferentes, essa linha diz isso, indicando ambas, e as orientações que o servidor entrega ao assistente ao se conectar começam com a mesma frase. Nada é recusado por causa de uma diferença, e o servidor responde a cada solicitação normalmente; isso é informado para que você saiba qual executável o pacote está executando. Para alinhá-los, instale o aggrega-<version>.mcpb da release de onde vem seu executável — aggrega version em um terminal imprime essa versão — ou defina Path to the aggrega executable como o caminho completo de um aggrega da release do pacote e depois reinicie o aplicativo como na etapa 4.
Os próprios logs do Claude Desktop mostram o que ele iniciou. No Windows, eles podem ficar em uma pasta de pacote no diretório local de dados de aplicativos em vez de em %APPDATA%\Claude\logs, mesmo quando o Claude Desktop foi instalado pelo seu próprio download: em %LOCALAPPDATA%\Packages\, na pasta cujo nome começa com Claude_, em LocalCache\Local\Claude\logs. Os arquivos ali incluem mcp.log e mcp-server-Aggrega.log, o segundo com o que o servidor Aggrega escreve na sua saída de erro padrão. Uma linha com Using MCP server command: indica o comando que o aplicativo iniciou, obtido da configuração Path to the aggrega executable do pacote. Quando a configuração indica um caminho em que não há nada, o log traz a mensagem do interpretador de comandos do Windows de que o caminho não é reconhecido como um comando e depois informa que o servidor não pôde ser iniciado. Quando a pasta do workspace não existe — renomeada, movida ou nunca criada —, o servidor inicia mesmo assim e responde a cada solicitação que o assistente faz nesse workspace com sua recusa, de modo que o assistente recebe a recusa como resposta à sua solicitação, em vez de o aplicativo informar uma falha de conexão. A recusa indica AGGREGA_WORKSPACE_ROOT como a variável que a configuração Workspace folder do pacote define, e cita a pasta exatamente como o aplicativo a passou; mcp-server-Aggrega.log traz a mesma recusa. Uma Workspace folder deixada vazia recebe a mesma resposta, com a recusa da etapa 3 indicando a configuração vazia, que o log também traz. Corrija a configuração e reinicie o aplicativo como na etapa 4.
As configurações de conectores do Claude Desktop são o outro caminho, para um servidor acessado via HTTPS: consulte Um servidor acessado via HTTPS.
Quando um cliente não aceita todo o conjunto de ferramentas
Aggrega anuncia todo o seu conjunto de ferramentas e deixa o cliente decidir quanto dele apresentar ao modelo. Alguns clientes limitam quantas ferramentas registram de uma vez e descartam o restante. Quando isso acontece, mcp.announce_tools reduz o que o servidor anuncia às ferramentas que você indicar — consulte Restringir o que o servidor anuncia.
Um servidor acessado via HTTPS
Cada entrada acima inicia o próprio servidor. Um servidor que outra pessoa executa — um único processo de longa duração em um host, servindo um workspace — é acessado pela rede, e sua entrada indica um endereço em vez de um comando:
{ "mcpServers": { "aggrega": { "url": "https://aggrega.example.com/mcp" } }}O caminho é sempre /mcp; o host é o que o operador publicou para esse servidor. Peça-o a ele. O Gemini CLI recebe o endereço em httpUrl em vez de url: ele interpreta url como um servidor no transporte mais antigo de fluxo de eventos e httpUrl como um servidor no transporte HTTP streamable, que é o que este servidor fala.
Quem obtém o token é o seu cliente, não você. Nada sobre o login é configurado na entrada: o servidor responde a uma solicitação não autenticada indicando o documento que diz qual servidor de autorização emite seus tokens, e um cliente que fala o fluxo de autorização do protocolo lê esse documento, leva você a fazer login e anexa o token que recebe a cada solicitação posterior. Os nomes dos escopos que ele pode solicitar são publicados nesse mesmo documento. Um cliente que não implementa o fluxo não consegue acessar um servidor desse tipo, e nada que você adicione à entrada o substitui.
Uma ferramenta que os escopos do seu login não alcançam continua na lista de ferramentas. A chamada a ela é recusada, indicando o escopo que a permitiria, e um cliente que implementa o step-up do protocolo responde a essa recusa pedindo que você faça login novamente para esse escopo. Um cliente que não faz step-up ainda pode receber os escopos de escrita: quem administra o servidor de autorização os torna escopos padrão para esse cliente, de modo que o primeiro login dele já os traz — ao custo de que cada login por meio desse cliente passe então a trazer acesso de escrita. O que um chamador pode alcançar expõe o que cada escopo permite e como essa configuração se comporta para um cliente que se registra novamente a cada conexão.
O que um servidor desse tipo exige, e o que o seu operador configura, está descrito na página aggrega mcp da referência.
Verificar a conexão
Depois que o cliente se reconectar, confirme que a integração está ativa: o cliente deve listar os prompts de criação de Aggrega (um para cada um dos papéis de desenvolvedor, arquiteto e operações, mais um modelo por entidade) e as ferramentas de criação — entre elas scaffold, validate, describe e get-schema. Peça ao assistente que gere o esqueleto de um componente, e ele deve retornar um esqueleto com os campos que um Component exige. Se nada aparecer, verifique se aggrega version é executado em um terminal e se o command do cliente aponta para o binário — a observação sobre o PATH acima cobre a causa mais comum.