콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

MCP 서버 연결

Aggrega의 MCP 서버는 aggrega mcp 명령이며, 사전 요구 사항은 aggrega 바이너리 하나뿐입니다. 바이너리 설치에서 명령 하나로 바이너리를 설치합니다. 서버는 클라이언트의 하위 프로세스로 stdio를 통해 실행되고, 스키마는 바이너리에서, 문서 페이지는 머신의 캐시로 한 번 가져온 사본에서 읽으며, 별도의 서비스, 포트, 계정이 필요하지 않습니다. 다른 사람이 이미 서버를 운영하고 있다면 바이너리도, 이 설정도 필요하지 않습니다. HTTPS로 접근하는 서버를 참조하십시오.

명령 하나로 추가하는 클라이언트

Aggrega 플러그인이 설치된 어시스턴트는 이미 연결되어 있습니다. 플러그인을 설치하면 Aggrega 스킬과 서버가 한 단계로 추가되며(Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro, OpenClaw에서, 플러그인 설치에서 설명하는 방식으로), 따라서 해당 어시스턴트를 연결하는 데 이 페이지의 다른 내용은 필요하지 않습니다. 플러그인은 어시스턴트가 시작될 때의 PATH에서 찾은 aggrega로 aggrega mcp를 시작하므로, 바이너리가 그곳에 설치되어 있어야 합니다. 일부 어시스턴트는 플러그인의 서버를 프로젝트가 아니라 플러그인 자체 폴더에서 시작하며(Codex가 그렇습니다), 이 경우 어시스턴트는 해당 값을 받는 호출에서 프로젝트 폴더를 workspace_root로 지정합니다. 스킬은 서버가 어느 워크스페이스에서 응답하는지 확인하도록 어시스턴트에게 지시합니다.

플러그인 없이 사용할 때는 클라이언트 자체 명령으로 서버를 추가합니다. Claude Code에서는 다음과 같습니다:

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

Codex에서:

Terminal window
codex mcp add aggrega -- aggrega mcp

Gemini CLI에서:

Terminal window
gemini mcp add aggrega aggrega mcp

그 밖의 모든 클라이언트

MCP를 지원하는 대부분의 클라이언트는 같은 방식으로 서버를 실행합니다. 즉, 단일 mcp 인수로 aggrega 명령을 실행하고 프로세스의 표준 입력과 출력으로 프로토콜을 주고받습니다. 클라이언트마다 다른 점은 서버 목록을 어디에 보관하는지와 그 목록의 항목을 무엇이라고 부르는지입니다. 공통 형태는 다음과 같습니다:

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

클라이언트가 다시 시작되어 연결되면 Aggrega 작성용 프롬프트, 리소스, 도구를 사용할 수 있습니다. 이들은 어시스턴트가 Aggrega로 할 수 있는 일에서 설명하고, 활용 방법은 Aggrega 파일 작성에서 보여 주며, 명령 자체는 aggrega mcp 레퍼런스에서 다룹니다.

항목의 어떤 내용도 프로토콜 리비전을 선택하지 않습니다. Aggrega는 표준 입력과 출력에서든 HTTPS에서든 2026-07-28과 2025-06-18을 모두 지원하므로, 어느 쪽의 클라이언트든 연결하여 같은 프롬프트, 리소스, 도구에 도달합니다. 클라이언트가 어느 리비전을 요청하는지는 구성이 아니라 통신 과정에서 결정됩니다.

명령을 실행할 수 있는 어시스턴트는 이 모든 작업을 스스로 할 수 있습니다. 붙여 넣는 프롬프트 하나로 바이너리를 설치하고, Aggrega 스킬을 추가하고, 서버에 연결합니다. AI 어시스턴트로 Aggrega 설정하기를 참조하십시오.

클라이언트별 서버 목록 위치

클라이언트목록 위치항목 이름
Claude Codeclaude mcp add 또는 프로젝트의 .mcp.json 파일mcpServers
Claude Desktop로컬 서버는 확장 설정, HTTPS로 연결하는 서버는 커넥터 설정Claude Desktop 참조
Cursor하나의 워크스페이스에는 .cursor/mcp.json, 모든 워크스페이스에는 사용자 범위의 mcp.jsonmcpServers
Gemini CLIgemini mcp add, 또는 모든 프로젝트용 ~/.gemini/settings.json과 한 프로젝트용 .gemini/settings.jsonmcpServers
Codex CLIcodex mcp add, 또는 모든 프로젝트용 ~/.codex/config.toml과 신뢰하는 한 프로젝트용 .codex/config.toml[mcp_servers.aggrega] 테이블 — Codex CLI 참조
ZedSettings → AI → MCP Servers(항목을 Zed 설정 파일에 기록)context_servers — Zed 참조
Visual Studio Code사용자 프로필의 mcp.json 또는 하나의 워크스페이스용 .vscode/mcp.jsonservers — Visual Studio Code 참조
GitHub Copilot CLIcopilot mcp add 또는 홈 디렉터리에 보관하는 mcp-config.json 파일mcpServers
Antigravity설정에서 열 수 있는 mcp_config.json 파일mcpServers
Windsurf설정에서 열 수 있는 mcp_config.json 파일mcpServers
Clinecline_mcp_settings.json 파일에 저장되는 MCP 설정mcpServers

아래에 별도 섹션이 있는 네 클라이언트를 제외하면, 표의 모든 클라이언트는 위에 작성된 항목을 해당 행의 경로에 그대로 받아들입니다. 표에 없는 클라이언트도 이러한 형태 중 하나의 서버 목록을 읽는다면 같은 방식으로 연결됩니다.

PATH에 관한 참고

그래픽 환경에서 실행된 클라이언트는 터미널과 같은 PATH를 항상 물려받지는 않습니다. 클라이언트가 aggrega 명령을 찾을 수 없다고 보고하면 "command": "aggrega"를 바이너리의 절대 경로로 바꾸십시오(예: "command": "/home/you/.local/bin/aggrega", Linux에서 you라는 사용자의 설치 위치). 나머지는 모두 그대로 둡니다.

Visual Studio Code

Visual Studio Code는 서버를 mcpServers가 아닌 servers 아래에 보관하며, 각 항목은 사용하는 전송 방식을 지정합니다:

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

Codex CLI

Codex는 서버를 JSON이 아닌 TOML로 보관합니다. 모든 프로젝트용은 ~/.codex/config.toml에, Codex가 신뢰하는 한 프로젝트용은 .codex/config.toml에 두며, 각 서버는 서버 이름을 딴 테이블입니다:

[mcp_servers.aggrega]
command = "aggrega"
args = ["mcp"]

위의 명령인 codex mcp add aggrega -- aggrega mcp를 실행하면 같은 테이블이 기록됩니다. Codex IDE 확장과 ChatGPT 데스크톱 앱도 같은 파일을 읽으므로, 항목 하나로 세 가지 모두에 사용할 수 있습니다.

Zed

Zed는 서버를 설정 파일의 context_servers 아래에 보관합니다. Settings → AI → MCP Servers에서 Add Server, 이어서 Add Local Server를 선택해 서버를 추가하면 항목이 그 파일에 기록됩니다. 또는 명령 팔레트에서 zed: open settings file을 실행하고 항목을 직접 추가합니다:

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

Zed는 프로토콜의 도구와 프롬프트를 지원하므로, Zed의 에이전트는 Aggrega의 도구와 작성 프롬프트에는 접근하지만 서버가 함께 제공하는 리소스에는 접근하지 않습니다.

Claude Desktop

Claude Desktop은 구성 파일의 항목이 아니라 확장 패키지에서 로컬 서버를 설치합니다. 확장 패키지는 서버와 이를 설명하는 manifest를 설치 가능한 하나의 파일로 묶은 것으로, 확장 설정에서 추가합니다. 각 Aggrega release에는 미리 빌드된 바이너리와 함께 이러한 패키지 aggrega-<version>.mcpb가 포함되어 있습니다.

Aggrega의 패키지에는 자체 프로그램이 포함되어 있지 않습니다. 패키지는 컴퓨터에 이미 설치된 aggrega 실행 파일을 단일 mcp 인수로 실행하고, 해당 프로세스의 표준 입력과 출력으로 프로토콜을 주고받습니다. 위의 모든 항목이 시작하는 것과 같은 서버입니다. 다른 실행 파일을 선택하지 않는 한, 패키지는 위의 모든 항목과 마찬가지로 명령 이름 aggrega를 Claude Desktop에 전달하므로, 애플리케이션은 자신이 시작될 때의 PATH에서 aggrega를 찾습니다. 또한 선택한 워크스페이스를 해당 서버에 전달합니다. 추가하는 방법은 다음과 같습니다.

  1. 바이너리 설치에 설명된 대로 aggrega 바이너리를 설치합니다. 그곳의 설치 명령과 수동 단계는 모두 관리자 권한 없이 교체할 수 있도록, C:\Windows\System32 같은 시스템 폴더가 아니라 사용자 소유의 폴더(Windows에서는 %LOCALAPPDATA%\Programs\aggrega)에 바이너리를 둡니다.
  2. Claude Desktop의 확장 설정에서 aggrega-<version>.mcpb를 설치합니다.
  3. 패키지의 설정을 지정합니다. 둘 다 필수는 아닙니다. Path to the aggrega executable은 패키지가 실행하는 프로그램이며, 기본값은 명령 이름 aggrega입니다. 애플리케이션은 자신이 시작될 때의 PATH에서 이를 찾습니다. 애플리케이션이 실행되는 동안 PATH에 추가된 폴더는(Windows 설치 프로그램과 Windows의 설치 명령이 각자의 폴더를 추가하는 것처럼) 4단계와 같이 애플리케이션을 종료했다가 다시 시작해야 반영되며, 그래픽 환경에서 시작된 애플리케이션은 터미널과 같은 PATH를 보지 못할 수 있습니다(PATH에 관한 참고 사항 참조). 그 PATH의 aggrega가 원하는 실행 파일이면 기본값을 그대로 둡니다. 원하는 실행 파일이 그 PATH에 없거나 그곳에서 처음 발견되는 aggrega와 다른 경우에는 대신 필드를 실행 파일의 전체 경로로 설정합니다. macOS와 Linux에서는 설치 위치인 홈 폴더의 .local/bin에 있는 aggrega(예: /Users/you/.local/bin/aggrega), Windows에서는 aggrega.exe로 끝나는 전체 경로(예: C:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe)입니다. 기본값으로 되돌리려면 필드를 비우는 대신 aggrega로 설정합니다. aggrega가 전혀 설치되어 있지 않다면 1단계의 설명에 따라 설치합니다. Workspace folder는 어시스턴트가 작업하는 Aggrega 워크스페이스의 폴더, 즉 프로젝트의 .aggrega-config.yaml이 있는 폴더입니다. 이 설정은 지정해야 합니다. 폴더를 선택하기 전까지는 비어 있으며, 비어 있는 동안 패키지는 서버에 빈 AGGREGA_WORKSPACE_ROOT를 전달하므로, 서버는 Claude Desktop이 서버를 시작한 폴더에서 작업하는 대신, 어시스턴트가 워크스페이스에서 보내는 모든 요청에 Workspace folder 설정이 비어 있으니 워크스페이스의 .aggrega-config.yaml이 있는 폴더로 설정하라는 거부 응답을 반환합니다. 패키지는 애플리케이션이 서버를 시작할 때만 폴더를 서버에 전달하므로, 서버가 실행되는 동안 설정한 폴더는 확장 설정에서 확장을 껐다가 다시 켜거나 4단계와 같이 애플리케이션을 다시 시작해야 적용됩니다.
  4. Claude Desktop을 완전히 종료한 다음 다시 시작합니다. 애플리케이션이 이미 시작한 서버는 계속 실행되며 실행 파일의 이름을 바꿔도 중지되지 않으므로, 변경한 설정은 애플리케이션이 서버를 다시 시작한 후에만 적용됩니다. 즉, 애플리케이션을 종료했다가 다시 시작한 후, 또는 Workspace folder의 경우 확장을 껐다가 다시 켠 후입니다. Windows에서는 작업 관리자에서 aggrega 프로세스가 아직 실행 중인지 확인할 수 있습니다.

워크스페이스 폴더는 자체 워크스페이스를 지정하지 않은 모든 요청이 처리되는 곳입니다. Claude Desktop은 프로젝트가 아니라 스스로 선택한 폴더에서 서버를 시작하므로, 패키지는 선택한 폴더를 애플리케이션이 구성하는 명령줄의 인수가 아니라 환경의 AGGREGA_WORKSPACE_ROOT 변수로 서버에 전달합니다. 서버는 모든 명령에서 --workspace-root를 받아들이는 것과 마찬가지로 해당 폴더를 워크스페이스 루트 자체로 받아들입니다. 그 위에서 상위 워크스페이스를 찾지 않으므로, 그 안의 폴더가 아니라 .aggrega-config.yaml이 있는 폴더를 선택해야 합니다. 다른 워크스페이스에서 작업하려면 설정을 변경하고 4단계와 같이 애플리케이션을 다시 시작합니다. 상대 workspace_root로 자체 워크스페이스를 지정하는 요청도 그 경로를 워크스페이스 폴더를 기준으로 읽으므로, 프롬프트는 폴더가 컴퓨터의 어디에 있는지 몰라도 그 안의 폴더(예: quickstart-ai/1)를 지정할 수 있습니다. 절대 workspace_root는 주어진 그대로 사용됩니다. 설정이 비어 있는 동안에는 상대 경로에도 워크스페이스를 지정하지 않은 요청과 같은 거부 응답이 반환됩니다.

패키지는 어떤 플랫폼의 실행 파일도 지정하지 않으므로, 같은 파일이 패키지가 선언하는 모든 플랫폼, 즉 macOS, Windows, Linux에 적용됩니다.

서버는 패키지가 실행한 aggrega를 보고합니다. Claude Desktop의 확장 설정에는 패키지가 실행하는 실행 파일의 버전이 아니라 패키지 자체의 버전, 즉 패키지가 나온 release의 버전이 표시됩니다. 둘은 따로 설치되므로 서로 다른 release에서 나올 수 있습니다. 패키지는 자체 버전을 환경의 AGGREGA_BUNDLE_VERSION 변수로 서버에 전달하며, 서버는 둘 다 보고합니다. 어시스턴트가 서버가 제공하는 기능을 알아보기 위해 호출하는 도구인 describe-capabilities를 인수 없이 호출하면, 그 응답은 실행 파일의 버전과 패키지의 버전을 나타내는 줄로 시작하고 구조화된 부분에도 같은 줄을 version_summary로 담습니다. 따라서 실행 중인 Aggrega의 버전을 질문받은 어시스턴트는 애플리케이션이 응답의 어느 부분을 전달하든 거기서 두 버전을 읽을 수 있습니다. 둘이 서로 다른 release에서 나온 경우 그 줄은 두 버전을 모두 명시하며 그 사실을 알리고, 서버가 연결 시 어시스턴트에 전달하는 안내도 같은 문장으로 시작합니다. 차이가 있다고 거부되는 것은 없으며 서버는 모든 요청에 평소대로 응답합니다. 이는 패키지가 어떤 실행 파일을 실행하고 있는지 알 수 있도록 보고되는 것입니다. 둘을 맞추려면 실행 파일이 나온 release의 aggrega-<version>.mcpb를 설치하거나(터미널에서 aggrega version을 실행하면 해당 버전이 출력됩니다) Path to the aggrega executable을 패키지의 release에 해당하는 aggrega의 전체 경로로 설정한 다음, 4단계와 같이 애플리케이션을 다시 시작합니다.

Claude Desktop 자체 로그에 실행한 내용이 표시됩니다. Windows에서는 Claude Desktop을 자체 다운로드로 설치한 경우에도 로그가 %APPDATA%\Claude\logs가 아니라 로컬 애플리케이션 데이터 디렉터리의 패키지 폴더 아래, 즉 %LOCALAPPDATA%\Packages\ 아래에서 이름이 Claude_로 시작하는 폴더의 LocalCache\Local\Claude\logs에 있을 수 있습니다. 그곳의 파일에는 mcp.log와 mcp-server-Aggrega.log가 있으며, 두 번째 파일에는 Aggrega 서버가 표준 오류에 쓰는 내용이 담깁니다. Using MCP server command:가 포함된 줄은 애플리케이션이 시작한 명령을 나타내며, 이 명령은 패키지의 Path to the aggrega executable 설정에서 가져온 것입니다. 설정이 아무것도 없는 경로를 지정하면 로그에는 경로가 명령으로 인식되지 않는다는 Windows 명령 인터프리터의 메시지가 기록된 다음, 서버를 시작할 수 없다는 내용이 기록됩니다. 워크스페이스 폴더가 없는 경우(이름이 바뀌었거나, 이동되었거나, 만들어지지 않은 경우) 서버는 그대로 시작되어 어시스턴트가 해당 워크스페이스에서 보내는 모든 요청에 거부 응답을 반환하므로, 애플리케이션이 연결 실패를 보고하는 대신 어시스턴트가 요청에 대한 응답으로 거부를 받습니다. 이 거부는 AGGREGA_WORKSPACE_ROOT를 패키지의 Workspace folder 설정이 지정하는 변수로 명시하고, 애플리케이션이 전달한 폴더를 그대로 인용합니다. mcp-server-Aggrega.log에도 같은 거부가 기록됩니다. Workspace folder가 비어 있는 경우에도 같은 방식으로, 비어 있는 설정을 명시하는 3단계의 거부로 응답하며 로그에도 기록됩니다. 설정을 수정하고 4단계와 같이 애플리케이션을 다시 시작합니다.

Claude Desktop의 커넥터 설정은 HTTPS로 접근하는 서버를 위한 또 다른 방법입니다. HTTPS로 접근하는 서버를 참조하십시오.

클라이언트가 전체 도구 표면을 받아들이지 않는 경우

Aggrega는 전체 도구 표면을 알리고, 그중 얼마만큼을 모델에 제공할지는 클라이언트가 결정하도록 맡깁니다. 일부 클라이언트는 한 번에 등록하는 도구 수를 제한하고 나머지는 버립니다. 이런 경우 mcp.announce_tools로 서버가 알리는 도구를 지정한 도구로 줄일 수 있습니다. 서버가 알리는 도구 좁히기를 참조하십시오.

HTTPS로 연결하는 서버

위의 모든 항목은 서버를 직접 실행합니다. 다른 사람이 운영하는 서버, 즉 호스트에서 하나의 워크스페이스를 제공하며 오래 실행되는 단일 프로세스에는 대신 네트워크로 연결하며, 그 항목에는 명령 대신 주소를 지정합니다.

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

경로는 항상 /mcp이며, 호스트는 운영자가 해당 서버에 대해 공개한 주소입니다. 운영자에게 문의하십시오. Gemini CLI는 주소를 url이 아니라 httpUrl 아래에 받습니다. Gemini CLI는 url을 이전 이벤트 스트림 전송 방식의 서버로, httpUrl을 이 서버가 사용하는 스트리밍 가능 HTTP 전송 방식의 서버로 읽습니다.

토큰은 사용자가 아니라 클라이언트가 받습니다. 로그인에 관한 설정은 항목에 전혀 없습니다. 서버는 인증되지 않은 요청에 대해 어떤 권한 부여 서버가 토큰을 발급하는지 밝히는 문서를 지정하여 응답하며, 프로토콜의 권한 부여 흐름을 구현한 클라이언트는 그 문서를 읽고 사용자를 로그인 화면으로 안내한 뒤, 받은 토큰을 이후의 모든 요청에 첨부합니다. 클라이언트가 요청할 수 있는 스코프 이름도 같은 문서에 공개되어 있습니다. 이 흐름을 구현하지 않은 클라이언트는 이런 종류의 서버에 연결할 수 없으며, 항목에 무엇을 추가해도 이를 대신할 수 없습니다.

로그인의 스코프가 닿지 않는 도구도 도구 목록에는 그대로 나타납니다. 그 도구를 호출하면 거부되며, 거부 응답에는 호출을 허용할 스코프가 명시됩니다. 프로토콜의 step-up을 구현한 클라이언트는 이 거부에 대해 해당 스코프로 다시 로그인하도록 요청합니다. step-up을 지원하지 않는 클라이언트에도 쓰기 스코프를 부여할 수 있습니다. 권한 부여 서버를 운영하는 사람이 그 클라이언트의 기본 스코프로 지정하면 첫 로그인부터 해당 스코프가 포함됩니다. 다만 그 대가로 그 클라이언트를 통한 모든 로그인에 쓰기 권한이 포함됩니다. 호출자가 접근할 수 있는 범위에서 각 스코프가 허용하는 것과, 연결할 때마다 자신을 새로 등록하는 클라이언트에서 이 설정이 어떻게 동작하는지 설명합니다.

이런 서버에 필요한 것과 운영자가 구성하는 내용은 aggrega mcp 레퍼런스에 있습니다.

연결 확인

클라이언트가 다시 연결되면 통합이 동작하는지 확인합니다. 클라이언트에는 Aggrega 작성 프롬프트(개발자, 아키텍트, 운영 역할마다 하나씩, 그리고 엔터티별 템플릿 하나)와 작성 도구(scaffold, validate, describe, get-schema 등)가 표시되어야 합니다. 어시스턴트에게 컴포넌트의 골격을 생성해 달라고 요청하면, Component에 필요한 필드를 담은 골격을 반환해야 합니다. 아무것도 나타나지 않으면 터미널에서 aggrega version이 실행되는지, 그리고 클라이언트의 command가 바이너리를 가리키는지 확인합니다. 흔한 원인은 위의 PATH 관련 참고 사항에서 다룹니다.