Antigravity IDE MCP 서버 설정 가이드

Antigravity IDE MCP 서버가 하는 일

Model Context Protocol(MCP)은 에이전트가 외부 도구와 문맥을 공통 방식으로 찾고 사용하는 표준입니다. 서버는 데이터베이스 스키마, 문서, 이슈 추적기, 클라우드 자원, 파일 분석기 또는 원격 API를 제공할 수 있습니다. Antigravity는 설정된 로컬 프로세스를 시작하거나 원격 엔드포인트에 연결해 도구 정의를 읽고, 승인한 권한 안에서 에이전트가 이용하도록 합니다.

MCP 서버 설치는 편집기 테마 설치와 다릅니다. 로컬 stdio 서버는 컴퓨터에서 명령을 실행합니다. 원격 서버는 요청을 받고 OAuth나 토큰을 요구할 수 있습니다. 추가하기 전에 게시자, 읽을 수 있는 데이터, 수행 가능한 쓰기 작업, 작업 공간 밖 접근의 필요성을 확인해야 합니다.

이 절차는 현재 Google 문서를 따르며 Antigravity IDE와 CLI를 구분합니다. IDE에는 MCP Store와 JSON 설정이 있습니다. CLI에는 /mcp 대화형 관리자가 있지만, CLI에 표시된 상태만으로 데스크톱 IDE가 같은 파일과 범위를 불러왔다고 판단하면 안 됩니다.

전역과 프로젝트 MCP 설정 선택

필요한 가장 좁은 범위를 사용하세요. 여러 프로젝트에서 반복 사용하는 개인 도구는 전역 설정, 저장소와 함께 검토·공유·제거해야 하는 도구는 프로젝트 설정이 적합합니다.

MCP Store에서 서버 설치

실제 프로젝트를 열고 로그인과 초기화가 끝날 때까지 기다립니다. 에이전트 패널 상단의 점 3개 메뉴에서 MCP Servers를 선택합니다. 지원 서버에 마우스를 올려 Install을 선택하거나 먼저 상세 정보를 읽습니다. 공식 인증 흐름을 완료한 뒤 목록으로 돌아가 서버가 표시되는지 확인합니다.

처음에는 서버 하나만 설치하세요. 여러 서버를 동시에 추가하면 어떤 프로세스, 인증 정보, 도구 정의가 실패했는지 구분하기 어렵고 에이전트가 선택해야 할 도구도 늘어납니다. 게시자 하나, 인증 흐름 하나, 시험 요청 하나로 기준을 만드세요.

1. 1단계 — 에이전트 패널과 점 3개 메뉴를 엽니다.
2. 2단계 — MCP Servers를 선택하고 게시자와 요구 권한을 확인합니다.
3. 3단계 — 서버 하나를 설치하고 공식 인증을 끝낸 뒤 다시 로드합니다.
4. 4단계 — 안전한 읽기를 요청하고 결과와 권한을 검토합니다.

mcp_config.json으로 사용자 서버 추가

Store에 없다면 Manage MCP Servers에서 View raw config를 엽니다. 공식 전역 파일은 ~/.gemini/config/mcp_config.json이고 프로젝트 파일은 .agents/mcp_config.json입니다. 루트에 하나의 mcpServers 객체를 둡니다. command, args, 엔드포인트, 인증 방식은 서버 게시자의 1차 문서에서 가져와야 합니다.

아래 예시는 일부러 실행되지 않게 작성했습니다. stdio 서버는 command와 args로 프로세스를 시작합니다. 현재 원격 설정에서 Google은 serverUrl을 안내하며 오래된 url 또는 httpUrl은 인식되지 않을 수 있습니다. 패키지 이름이나 CDN 규칙으로 주소를 추측하지 말고 개인 키를 Git에 넣지 마세요.

{
  "mcpServers": {
    "example-server": {
      "command": "OFFICIAL_COMMAND",
      "args": ["OFFICIAL_ARGUMENT"]
    },
    "example-remote": {
      "serverUrl": "https://OFFICIAL_EXAMPLE_ENDPOINT/mcp"
    }
  }
}

구조 예시일 뿐 실제 연결 정보가 아닙니다. 실행 파일, URL, 헤더, OAuth 값은 선택한 서버의 공식 문서에서만 복사하세요.

MCP 서버 다시 로드 및 검증

유효한 JSON을 저장하고 서버 목록으로 돌아가 다시 불러옵니다. 서버 이름과 도구 또는 리소스를 확인할 수 있어야 합니다. 첫 작업으로 쓰기를 시키지 마세요. 사용 가능한 리소스 나열, 민감하지 않은 시험 문서 읽기, 도구 이름 표시처럼 검증하기 쉬운 요청으로 시작합니다.

인증이 필요하면 로그인한 계정과 범위를 확인합니다. 초록 상태는 연결을 증명할 뿐 비밀 데이터에 안전하다는 뜻이 아닙니다. 도구 이름, 인수, 반환된 출처를 검토한 뒤 권한을 기억할지 결정하세요.

• 로드 — 예상한 이름이 표시되고 도구 목록을 확인할 수 있습니다.
• 인증 — 계정과 승인 범위가 대상 프로젝트와 일치합니다.
• 근거 — 읽기 시험이 예상한 출처를 반환합니다.
• 복구 — 항목 비활성화, 토큰 취소, 설정 제거 방법을 알고 있습니다.

MCP 보안과 권한 규칙

모든 서버를 데이터 경계를 넘는 코드로 취급하세요. 1차 제공자나 내용을 검토할 수 있는 저장소를 우선하고 가능하면 버전을 고정합니다. 검증되지 않은 글의 다운로드 후 즉시 실행 명령은 피하세요. 데이터베이스와 클라우드 연동은 프로덕션 소유자 대신 최소 권한 개발 계정을 사용합니다.

프로젝트 설정에 두었다고 자동 샌드박스가 생기지는 않습니다. 프로세스는 운영체제 계정이 허용한 파일을 읽을 수 있습니다. 비밀 값을 프롬프트나 커밋되는 JSON에 넣지 마세요. 쓰기, 삭제, 배포, 결제, 메시지 전송, 계정 관리 작업은 명확한 정책이 생길 때까지 매번 검토합니다.

Antigravity IDE와 WSL의 MCP 오류 해결

주된 원인은 잘못된 설정 범위, JSON 오류, PATH, 인증, Windows와 WSL 경로 혼용입니다. 한 번에 한 항목만 바꾸세요.

다시 로드해도 서버가 보이지 않음

JSON을 검증하고 mcpServers가 루트에 있는지, Manage MCP Servers가 보여 준 파일을 수정했는지 확인합니다. 다른 전역 또는 로컬 파일도 찾습니다. 일반 다시 로드가 실패한 뒤에만 IDE를 재시작합니다.

터미널에서는 되지만 IDE에서는 실패

GUI 프로세스는 PATH, 홈 디렉터리, 셸, 환경 변수가 다를 수 있습니다. 제공자가 지원하면 실행 파일의 절대 경로를 쓰고 시스템 환경을 바꾼 후 Antigravity를 다시 엽니다.

WSL에서 MCP 서버 실행 실패

어느 운영체제가 프로세스를 시작하는지 결정합니다. Windows IDE에서 Linux 명령을 실행한다면 wsl.exe를 명시하고 그 내부에는 Linux 경로를 사용합니다. WSL 프로세스에 C:\ 경로를 Linux 경로처럼 넘기지 않습니다. IDE 밖에서 같은 명령을 먼저 시험하세요.

원격 연결은 되지만 도구가 없음

공식 엔드포인트, 인증, 전송 방식을 확인합니다. 현재 설정은 serverUrl을 사용합니다. 제품 소개 페이지나 대시보드 URL은 MCP 엔드포인트가 아닙니다.

서버가 계속 시작과 종료를 반복

비밀 값을 노출하지 않고 프로세스를 직접 실행해 stderr를 확인합니다. 런타임 누락, 비호환 버전, stdout의 불필요한 로그, 만료된 인증이 흔한 원인입니다.

최신 버전과 다운로드 출처 확인

이 사이트는 소프트웨어 다운로드 정보를 제공하므로 페이지 작성 전에 버전을 확인했습니다. 2026년 7월 24일 기준 Google 공식 changelog에는 2026년 6월 25일자 v2.2.1이 표시됐습니다. 사이트도 이미 v2.2.1을 사용해 버전 번호 수정은 필요하지 않았습니다. 이 페이지는 확인되지 않은 파일 크기, 체크섬, 보안 검사, 영구 패키지 URL을 만들지 않습니다.

다운로드 버튼은 검증된 공식 페이지로 연결됩니다. 단계적으로 배포될 수 있으므로 설치 시 다시 확인하세요. 현재 MCP 경로와 원격 설정 형식은 아래 공식 문서를 최종 기준으로 사용합니다.