Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

Ligar o servidor MCP

O servidor MCP do Aggrega é o comando aggrega mcp, e o binário aggrega é o seu único pré-requisito: Instalar o binário instala-o com um único comando. O servidor corre como subprocesso do cliente através de stdio, lê os seus schemas a partir do binário e as suas páginas de documentação a partir de uma cópia que transfere uma única vez para a cache do computador, e não precisa de nenhum serviço, porta ou conta à parte. Quando outra pessoa já executa um servidor para si, não precisa nem do binário nem de nada disto: consulte Um servidor acedido por HTTPS.

Clientes que o adicionam com um único comando

Um assistente com o plugin do Aggrega instalado já está ligado. A instalação do plugin adiciona a skill do Aggrega e o servidor num único passo — no Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro e OpenClaw, como descreve Instalar o plugin —, pelo que nada mais nesta página é necessário para ligar esse assistente. O plugin inicia aggrega mcp com o aggrega encontrado no PATH com que o assistente foi iniciado, pelo que o binário tem de estar instalado aí. Alguns assistentes iniciam o servidor de um plugin na própria pasta do plugin, e não no projeto — o Codex fá-lo —, e o assistente indica então a pasta do projeto como workspace_root nas chamadas que o aceitam; a skill indica-lhe que verifique em que workspace o servidor responde.

Sem o plugin, adicione o servidor com o comando próprio do cliente. No Claude Code:

Terminal window
claude mcp add --transport stdio aggrega -- aggrega mcp

No Codex:

Terminal window
codex mcp add aggrega -- aggrega mcp

No Gemini CLI:

Terminal window
gemini mcp add aggrega aggrega mcp

Todos os outros clientes

A maioria dos clientes compatíveis com MCP lança o servidor da mesma forma — executam o comando aggrega com um único argumento mcp e falam o protocolo através da entrada e da saída padrão do processo. O que difere entre eles é onde cada um guarda a sua lista de servidores e como chama às entradas dessa lista. A forma comum:

{
"mcpServers": {
"aggrega": {
"command": "aggrega",
"args": ["mcp"]
}
}
}

Depois de o cliente reiniciar e se ligar, ficam disponíveis os prompts, os recursos e as ferramentas de criação do Aggrega. O que o assistente pode fazer com o Aggrega descreve-os, Criar ficheiros 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. O Aggrega fala tanto 2026-07-28 como 2025-06-18, na entrada e saída padrão e por HTTPS, pelo que um cliente de qualquer uma delas se liga e chega aos mesmos prompts, recursos e ferramentas. A revisão que um cliente pede é decidida na comunicação e não na configuração.

Um assistente capaz de executar comandos pode fazer tudo isto sozinho — instalar o binário, adicionar a skill do Aggrega e ligar-se ao servidor — a partir de um único prompt que se cola nele: consulte Configurar o Aggrega com o assistente de IA.

Onde cada cliente guarda a sua lista de servidores

ClienteOnde está a listaComo se chama a entrada
Claude Codeclaude mcp add, ou um ficheiro .mcp.json no projetomcpServers
Claude Desktopas suas definições de extensões para um servidor local; as suas definições de conectores para um servidor acedido por HTTPSver Claude Desktop
Cursor.cursor/mcp.json para um workspace, ou um mcp.json ao nível do utilizador para todos os workspacesmcpServers
Gemini CLIgemini mcp add, ou ~/.gemini/settings.json para todos os projetos e .gemini/settings.json para ummcpServers
Codex CLIcodex mcp add, ou ~/.codex/config.toml para todos os projetos e .codex/config.toml para um projeto fidedignouma tabela [mcp_servers.aggrega] — ver Codex CLI
ZedSettings → AI → MCP Servers, que escreve a entrada no ficheiro de definições do Zedcontext_servers — ver Zed
Visual Studio Codemcp.json no perfil do utilizador, ou .vscode/mcp.json para um workspaceservers — ver Visual Studio Code
GitHub Copilot CLIcopilot mcp add, ou o ficheiro mcp-config.json que guarda no diretório pessoalmcpServers
Antigravityo ficheiro mcp_config.json acessível a partir das suas definiçõesmcpServers
Windsurfo ficheiro mcp_config.json acessível a partir das suas definiçõesmcpServers
Clineas suas definições de MCP, suportadas por um ficheiro cline_mcp_settings.jsonmcpServers

Todos os clientes dessa tabela, exceto os quatro com secção própria abaixo, aceitam a entrada exatamente como está escrita acima, no caminho indicado na sua linha. Um cliente não listado liga-se da mesma forma se ler uma lista de servidores de uma destas formas.

Uma nota sobre o PATH

Os clientes lançados a partir de um ambiente gráfico nem sempre herdam o mesmo PATH que o terminal. Se um cliente indicar 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 utilizador chamado you). Tudo o resto se mantém.

Visual Studio Code

O Visual Studio Code guarda os seus servidores em servers em vez de mcpServers, e cada entrada nomeia o transporte que usa:

{
"servers": {
"aggrega": {
"type": "stdio",
"command": "aggrega",
"args": ["mcp"]
}
}
}

Codex CLI

O Codex guarda os 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, escreve a mesma tabela automaticamente. A extensão de IDE do Codex e a aplicação de ambiente de trabalho do ChatGPT leem o mesmo ficheiro, pelo que a única entrada serve os três.

Zed

O Zed guarda os seus servidores em context_servers no seu ficheiro de definições. Acrescente o servidor a partir de Settings → AI → MCP Servers — Add Server e depois Add Local Server — o que escreve a entrada nesse ficheiro, ou execute zed: open settings file a partir da paleta de comandos e acrescente a entrada manualmente:

{
"context_servers": {
"aggrega": {
"command": "aggrega",
"args": ["mcp"]
}
}
}

O Zed suporta as ferramentas e os prompts do protocolo, pelo que 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 disponibiliza.

Claude Desktop

O Claude Desktop instala um servidor local a partir de um pacote de extensão — o servidor juntamente com um manifesto que o descreve, agrupados num único ficheiro instalável e acrescentado a partir das definições de extensões — e não a partir de uma entrada num ficheiro de configuração. Cada versão do Aggrega inclui um pacote destes, aggrega-<version>.mcpb, ao lado dos binários pré-compilados.

O pacote do Aggrega não contém nenhum programa próprio. Lança um executável aggrega já instalado na máquina, com o único argumento mcp, e fala o protocolo através da entrada e da saída padrão desse processo — o mesmo servidor que todas as entradas acima iniciam. Salvo se for escolhido outro executável, entrega ao Claude Desktop o nome de comando aggrega, tal como todas as entradas acima, pelo que a aplicação procura aggrega no PATH com que foi iniciada; e entrega a esse servidor o workspace escolhido. Para o acrescentar:

  1. Instale o binário aggrega, como descrito em Instalar o binário. Tanto o comando de instalação como os passos manuais aí descritos o guardam numa pasta do próprio utilizador — no Windows, %LOCALAPPDATA%\Programs\aggrega em vez de uma pasta do sistema como C:\Windows\System32 — para que seja possível substituí-lo sem direitos de administrador.
  2. Instale o aggrega-<version>.mcpb a partir das definições de extensões do Claude Desktop.
  3. Preencha as definições do pacote; nenhuma é obrigatória. Path to the aggrega executable é o programa que o pacote lança, e o seu valor predefinido é o nome de comando aggrega, que a aplicação procura no PATH com que foi iniciada. Uma pasta acrescentada ao PATH enquanto a aplicação está em execução — como o instalador do Windows e o comando de instalação no Windows acrescentam a sua — só chega à aplicação depois de esta ter sido encerrada e iniciada novamente, como no passo 4, e uma aplicação iniciada a partir de um ambiente gráfico pode não ver o mesmo PATH que o terminal (consulte Uma nota sobre PATH). Mantenha o valor predefinido quando o aggrega nesse PATH for o executável pretendido. Em alternativa, defina o campo com o caminho completo de um executável quando o pretendido não estiver nesse PATH, ou for um aggrega diferente do primeiro aí encontrado — no macOS e no Linux, para a localização de instalação, o aggrega em .local/bin na pasta pessoal, como /Users/you/.local/bin/aggrega; no Windows, o caminho completo terminado em aggrega.exe, como C:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe. Para voltar ao valor predefinido, defina o campo como aggrega em vez de o esvaziar. Quando não houver nenhum aggrega instalado, instale-o como descreve o passo 1. Workspace folder é a pasta do workspace Aggrega em que o assistente trabalha: a pasta que contém o .aggrega-config.yaml do projeto. Preencha esta: fica vazia até se escolher uma pasta, e enquanto está vazia o pacote entrega ao servidor um AGGREGA_WORKSPACE_ROOT vazio, pelo que o servidor responde a todos os pedidos que o assistente faz no workspace com uma recusa que diz que a definição Workspace folder está vazia e indica que deve ser definida para a pasta que contém o .aggrega-config.yaml do workspace, em vez de trabalhar na pasta em que o Claude Desktop o iniciou. O pacote entrega a pasta ao servidor apenas quando a aplicação o inicia, pelo que uma pasta definida enquanto o servidor está em execução só tem efeito depois de desativar e voltar a ativar a extensão nas definições de extensões, ou de reiniciar a aplicação como no passo 4.
  4. Saia completamente do Claude Desktop e volte a iniciá-lo. Um servidor que a aplicação já iniciou continua a correr, e mudar o nome do executável não o para, pelo que uma definição alterada só tem efeito quando a aplicação volta a iniciar o servidor: depois de ter sido fechada e iniciada de novo ou, para Workspace folder, depois de a extensão ser desativada e novamente ativada. No Windows, o Gestor de Tarefas mostra se um processo aggrega ainda está a correr.

A pasta do workspace é onde é respondido cada pedido que não nomeia um workspace próprio. O Claude Desktop inicia o servidor numa pasta à sua escolha e não no projeto, pelo que o pacote passa a pasta escolhida ao servidor como a variável AGGREGA_WORKSPACE_ROOT no seu ambiente, em vez de como argumento na linha de comandos que a aplicação compõe. O servidor toma essa pasta como a própria raiz do workspace, tal como --workspace-root é tomado em todos os comandos: não procura acima dela um workspace envolvente, pelo que deve ser escolhida a pasta que contém o .aggrega-config.yaml e não uma pasta dentro dela. Para trabalhar noutro workspace, altere a definição e reinicie a aplicação como no passo 4. Num pedido que nomeia um workspace próprio com um workspace_root relativo, este também é lido a partir da pasta do workspace, pelo que um prompt nomeia uma pasta dentro dela — como quickstart-ai/1 — sem saber onde a pasta se encontra no computador; um workspace_root absoluto é usado tal como é indicado. Enquanto a definição estiver vazia, um relativo recebe a mesma recusa que um pedido que não nomeia nenhum.

Como o pacote não nomeia nenhum executável de nenhuma plataforma, o mesmo ficheiro aplica-se a todas as plataformas que declara: macOS, Windows e Linux.

O servidor indica que aggrega o pacote lançou. As definições de extensões do Claude Desktop listam a versão do próprio pacote — a versão da publicação de onde veio — e não a versão do executável que lança. Os dois são instalados separadamente, pelo que podem vir de versões diferentes. O pacote entrega ao servidor a sua própria versão como a variável AGGREGA_BUNDLE_VERSION no seu ambiente, e o servidor indica ambas: a resposta de describe-capabilities chamado sem argumentos — a ferramenta que um assistente chama para saber o que o servidor oferece — abre com uma linha que nomeia a versão do executável e a do pacote, e contém a mesma linha como version_summary na sua parte estruturada, para que um assistente a quem se pergunte que versão do Aggrega está a correr possa ler ambas aí, qualquer que seja a parte da resposta que a aplicação lhe entregue. Quando as duas vêm de versões diferentes, essa linha di-lo, nomeando ambas, e a orientação que o servidor entrega ao assistente quando este se liga abre com a mesma frase. Nada é recusado por causa de uma diferença, e o servidor responde a todos os pedidos normalmente; é indicado para que se saiba que executável o pacote está a executar. Para alinhar os dois, instale o aggrega-<version>.mcpb da versão de onde vem o executável — aggrega version num terminal imprime essa versão — ou defina Path to the aggrega executable com o caminho completo de um aggrega da versão do pacote e, em seguida, reinicie a aplicação como no passo 4.

Os registos do próprio Claude Desktop mostram o que lançou. No Windows, podem estar numa pasta de pacote no diretório local de dados de aplicações e não em %APPDATA%\Claude\logs, mesmo quando o Claude Desktop foi instalado a partir da sua própria transferência: em %LOCALAPPDATA%\Packages\, na pasta cujo nome começa por Claude_, em LocalCache\Local\Claude\logs. Os ficheiros aí incluem mcp.log e mcp-server-Aggrega.log, o segundo com o que o servidor Aggrega escreve no seu erro padrão. Uma linha com Using MCP server command: nomeia o comando que a aplicação iniciou, obtido da definição Path to the aggrega executable do pacote. Quando a definição indica um caminho onde não existe nada, o registo contém a mensagem do interpretador de comandos do Windows de que o caminho não é reconhecido como comando e, em seguida, indica que o servidor não pôde iniciar. Quando a pasta do workspace não existe — mudou de nome, foi movida ou nunca foi criada — o servidor inicia na mesma e responde a todos os pedidos que o assistente faz nesse workspace com a sua recusa, pelo que o assistente recebe a recusa como resposta ao seu pedido em vez de a aplicação reportar uma falha de ligação. A recusa nomeia AGGREGA_WORKSPACE_ROOT como a variável que a definição Workspace folder do pacote define, e cita a pasta exatamente como a aplicação a passou; o mcp-server-Aggrega.log contém a mesma recusa. Uma Workspace folder deixada vazia é respondida da mesma forma, com a recusa do passo 3 que nomeia a definição vazia, que o registo também contém. Corrija a definição e reinicie a aplicação como no passo 4.

As definições de conectores do Claude Desktop são a outra via, para um servidor acedido por HTTPS: ver Um servidor acedido por HTTPS.

Quando um cliente não aceita toda a superfície de ferramentas

O Aggrega anuncia toda a sua superfície de ferramentas e deixa ao cliente a decisão de quanto dela apresentar ao modelo. Alguns clientes limitam o número de ferramentas que registam de uma vez e descartam as restantes. Quando isso acontece, o mcp.announce_tools reduz o que o servidor anuncia às ferramentas que se nomearem — ver Restringir o que o servidor anuncia.

Um servidor acedido por HTTPS

Todas as entradas acima lançam o próprio servidor. Um servidor que outra pessoa executa — um processo de longa duração num host, a servir um workspace — é, em vez disso, acedido pela rede, e a sua entrada nomeia um endereço em vez de um comando:

{
"mcpServers": {
"aggrega": {
"url": "https://aggrega.example.com/mcp"
}
}
}

O caminho é sempre /mcp; o host é aquele que o operador publicou para esse servidor. Peça-lho. O Gemini CLI recebe o endereço em httpUrl e não em url: lê 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.

É o cliente que obtém o token, não o utilizador. Nada sobre o início de sessão é configurado na entrada: o servidor responde a um pedido não autenticado nomeando o documento que indica que servidor de autorização emite os seus tokens, e um cliente que fale o fluxo de autorização do protocolo lê esse documento, encaminha o utilizador para iniciar sessão e anexa o token que recebe a todos os pedidos posteriores. Os nomes de âmbito que pode pedir estão publicados nesse mesmo documento. Um cliente que não implemente o fluxo não consegue chegar a um servidor deste tipo, e nada que se acrescente à entrada o substitui.

Uma ferramenta que os âmbitos do seu início de sessão não alcançam continua na lista de ferramentas. Chamá-la é recusado, com a indicação do âmbito que a admitiria, e um cliente que implemente o step-up do protocolo responde a essa recusa pedindo ao utilizador que volte a iniciar sessão para esse âmbito. Um cliente que não faça step-up pode ainda assim receber os âmbitos de escrita: quem executa o servidor de autorização torna-os âmbitos predefinidos para esse cliente, pelo que o seu primeiro início de sessão já os inclui — com o custo de que todos os inícios de sessão através desse cliente passam a ter alcance de escrita. O que um chamador pode alcançar explica o que cada âmbito admite e como essa definição se comporta para um cliente que se regista de novo de cada vez que se liga.

O que um servidor destes exige, e o que o seu operador configura, está na referência de aggrega mcp.

Verificar a ligação

Depois de o cliente se voltar a ligar, confirme que a integração está ativa: o cliente deve listar os prompts de autoria do Aggrega (um para cada um dos papéis de programador, arquiteto e operações, mais um template por entidade) e as ferramentas de autoria — entre elas scaffold, validate, describe e get-schema. Peça ao assistente que crie o esqueleto de um componente, e ele deve devolver um esqueleto com os campos que um Component exige. Se nada aparecer, verifique que aggrega version corre a partir de um terminal e que o command do cliente resolve para o binário — a nota sobre o PATH acima cobre a causa habitual.