Antigravity CLI MCP 서버 연결: agy mcp add와 설정 파일

Antigravity CLI의 작업 폴더 설정에 정상 MCP 서버 하나와 일부러 망가뜨린 서버 두 개를 같이 넣어 봤습니다. 하나는 없는 실행 파일을, 하나는 옛 키 url을 쓴 서버였어요.

그 상태로 agy -p를 실행하니 ok가 그대로 돌아오고, 종료 코드는 0, 표준 오류도 비어 있었습니다. 잘못 적은 서버 두 개가 아무 흔적 없이 빠진 거죠.

그래서 MCP 서버는 등록만 하고 끝내면 안 됩니다. 붙었는지를 따로 확인해야 해요.

다행히 확인할 단서는 있었습니다. 연결된 서버만 ~/.gemini/antigravity-cli/mcp/<서버 이름>/ 아래에 도구 정의 파일이 생기더라고요.

나머지는 단순합니다. 서버는 agy mcp add <이름> <명령> [인자...]로 등록하고, 이 명령은 항상 전역 설정 ~/.gemini/config/mcp_config.json에 씁니다. 프로젝트 전용 서버는 .agents/mcp_config.json을 직접 만들고요.

agy -p에서 쓰려면 전역 설정 ~/.gemini/antigravity-cli/settings.json에 "permissions": {"allow": ["mcp(서버이름/*)"]}를 넣어야 MCP 도구가 거부되지 않습니다.

2026년 10월 1일 Windows 11 · Windows PowerShell 5.1 테스트 환경에서 Antigravity CLI 1.2.14로 직접 실행해 확인했고, 공식 MCP·권한·이전 문서를 같은 날 다시 봤습니다.

연결 대상으로는 도구 두 개(덧셈, 정해진 단어 돌려주기)짜리 작은 Node.js MCP 서버를 썼습니다.

MCP(Model Context Protocol)는 에이전트에 외부 도구와 데이터를 붙이는 표준 규약입니다.

전역 파일과 작업 폴더 파일

둘 중 어디에 둘지는 그 서버를 어디서 쓸지로 정하면 됩니다.

범위	파일	만드는 법
전역(모든 폴더)	~/.gemini/config/mcp_config.json	agy mcp add 또는 직접 편집
작업 폴더	<프로젝트>/.agents/mcp_config.json	직접 편집

agy mcp add에는 Claude Code의 --scope 같은 범위 옵션이 없습니다. 직접 해 보니 매번 전역 파일에 썼어요. 그래서 프로젝트에서만 쓸 서버나 저장소에 넣어 팀과 나눌 서버는 .agents/mcp_config.json을 손으로 만들어야 합니다.

Gemini CLI에서 옮겨 온다면 위치와 키가 바뀝니다. Gemini CLI는 settings.json의 mcpServers에 적었지만 Antigravity CLI는 mcp_config.json으로 분리했고, 원격 서버 주소 키는 url·httpUrl이 아니라 serverUrl이어야 해요.

stdio 서버의 command·args·env는 모양이 같아서 그대로 복사해도 되지만, 원격 서버는 꼭 키를 바꾸세요. 옛 키 url을 두면 글 처음의 그 서버처럼 오류 없이 빠집니다.

처음 agy를 실행하면 기존 설정을 감지해 무엇을 옮길지 고르게 합니다. 이전 순서 전체는 Gemini CLI 종료 후 Antigravity CLI 설치·설정 옮기기에 있어요.

agy mcp add 쓰는 법

등록부터 관리까지 세 단계입니다.

1. 서버 등록

로컬 프로그램을 띄우는 stdio 서버는 이름, 실행할 명령, 인자 순으로 적습니다.

agy mcp add fs npx -y @modelcontextprotocol/server-filesystem <프로젝트 경로>

Added MCP server "fs" (stdio)

이름 뒤의 -y가 agy의 옵션이 아니라 npx의 인자로 제대로 넘어갔습니다. 도움말은 이름 뒤에 온 플래그를 거부한다고 하지만 실제로는 문제없었어요. Claude Code에서는 같은 자리의 -y를 자기 옵션으로 읽어 --로 갈라야 했습니다(Claude Code MCP 서버 연결 글의 Windows 절).

--env·--header는 이름 앞에 두고, 원격 서버는 주소만 줍니다.

agy mcp add --env LAB=1 lab2 -- node lab-server.mjs
agy mcp add remote1 https://example.com/mcp

원격 서버에 인증 토큰을 넣으려면 agy mcp add --header "Authorization: Bearer <token>" 이름 주소처럼 헤더를 주거나 설정 파일의 headers에 적습니다. Google 자격 증명(authProviderType)과 OAuth(oauth) 방식도 있어요.

명령이나 인자가 -로 시작하면 그 앞에 --를 두라고 도움말에 나옵니다. 그런데 Windows PowerShell 5.1은 따옴표 없는 --를 외부 프로그램에 넘기지 않아요.

위 명령은 node가 -로 시작하지 않아 괜찮았고, '--'로 감싸 넘긴 경우와 저장 결과가 같았습니다. 정말 --가 필요하면 PowerShell에서는 '--'로 감싸세요.

2. 목록과 파일로 확인

PS> agy mcp list
NAME     TYPE   STATUS   COMMAND/URL
fs       stdio  enabled  npx -y @modelcontextprotocol/server-filesystem <프로젝트 경로>
lab2     stdio  enabled  node lab-server.mjs
remote1  http   enabled  https://example.com/mcp

mcp_config.json에는 "lab2": {"command": "node", "args": ["lab-server.mjs"], "env": {"LAB": "1"}, "disabled": false}처럼 저장되고, 원격 서버는 serverUrl 키로 저장됐습니다. 헷갈리기 쉬운 게 STATUS인데, enabled는 설정상 켜져 있다는 뜻이지 연결에 성공했다는 뜻이 아닙니다.

3. 끄고 켜고 지우기

PS> agy mcp disable lab2
Disabled MCP server "lab2"
PS> agy mcp enable lab2
Enabled MCP server "lab2"
PS> agy mcp remove remote1
Removed MCP server "remote1"

주의: 등록해 둔 서버는 질문과 관계없이 agy를 실행할 때마다 모두 띄워지니, 출처를 모르는 서버는 등록하지 마세요.

실제로 agy -p로 질문 하나를 던지자 fs 서버를 띄우려고 npx -y @modelcontextprotocol/server-filesystem이 돌았고, 그 패키지가 npm 캐시에 내려받아졌습니다. 등록은 “필요할 때 쓴다”보다 “실행할 때마다 띄운다”에 가깝다고 보면 됩니다.

프로젝트 전용 서버는 직접 쓰기

작업 폴더 파일은 전역 파일과 형식이 같습니다. 서버마다 command(stdio)나 serverUrl(원격) 중 하나가 필요하고, args·env·cwd·headers·disabled·disabledTools를 더 줄 수 있어요.

{
  "mcpServers": {
    "wslab": { "command": "node", "args": ["C:/<서버 폴더>/lab-server.mjs"] }
  }
}

Windows 경로를 슬래시(/)로 적어도 서버가 정상으로 떴습니다. 역슬래시로 적으려면 JSON 안에서 두 번(\\) 써야 합니다.

여기서 헷갈리기 쉬운 게 목록입니다. 이 파일의 서버는 agy mcp list에 나오지 않았고, 같은 폴더에서 봐도 전역 서버만 나왔어요.

그런데도 그 폴더에서 agy를 실행하면 wslab의 도구를 불러 쓸 수 있었습니다. 목록에 없다고 안 읽힌 게 아닙니다.

팀원마다 서버 경로가 다르면 .agents/mcp_config.json을 그대로 커밋하기 어렵습니다. 그럴 때는 저장소에는 공통 서버만 두고, 사람마다 다른 서버는 각자 agy mcp add로 전역에 등록하는 쪽을 권해요.

연결 실패는 캐시 폴더와 /mcp 화면으로 확인

글 처음에 말한 실험의 설정은 이랬습니다.

{
  "mcpServers": {
    "wslab": { "command": "node", "args": ["C:/<서버 폴더>/lab-server.mjs"] },
    "ghost": { "command": "does-not-exist-mcp" },
    "legacy": { "url": "https://example.com/mcp" }
  }
}

ghost는 없는 실행 파일, legacy는 지원하지 않는 옛 키 url입니다. 이 상태로 agy -p "Reply with exactly the word: ok"를 실행하자 ok가 돌아왔고, 종료 코드 0에 표준 오류도 비어 있었습니다. 로그에서도 두 서버의 이름이나 연결 오류를 찾을 수 없었어요.

대신 쓸 만한 단서가 있었습니다. 연결에 성공한 서버만 도구마다 JSON 파일이 생겼거든요.

~\.gemini\antigravity-cli\mcp\wslab\lab_add.json
~\.gemini\antigravity-cli\mcp\wslab\lab_secret_word.json

ghost와 legacy의 폴더는 생기지 않았습니다. 그러니 이 폴더에 서버 이름의 폴더와 도구 파일이 있는지, 파일 시각이 방금 실행한 시각인지로 가리면 됩니다. 시각까지 보는 이유는 agy mcp remove로 지운 서버의 폴더도 남아 있었기 때문이에요.

이 파일은 에이전트도 씁니다. stream-json 출력을 보면 MCP 도구를 바로 부르지 않고, 먼저 이 정의 파일을 view_file로 읽은 뒤 공용 도구 call_mcp_tool에 서버와 도구 이름을 넘겨 호출했어요.

{"event":"step_update",…"tool_name":"view_file",…"AbsolutePath":"%USERPROFILE%\\.gemini\\antigravity-cli\\mcp\\wslab\\lab_secret_word.json"…}
{"event":"step_update",…"tool_name":"call_mcp_tool",…"parameters":{"Arguments":{},"ServerName":"wslab","ToolName":"lab_secret_word"},"output":"PAPAYA-91"}}}

스트림에서 MCP 호출을 찾을 때는 tool_name이 call_mcp_tool인 단계를 보고, ServerName·ToolName을 읽으면 됩니다.

대화형 화면에서는 /mcp로 MCP 관리 화면을 열어 서버별 연결 상태를 볼 수 있습니다. agy -p에서는 조용히 빠지던 실패가 여기서는 그대로 보여요.

1.3.3에서 작업 폴더의 .agents/mcp_config.json에 정상 서버 demo와 없는 파일을 가리키는 서버 broken을 함께 두고 열어 본 화면입니다.

실패한 서버는 서버가 표준 오류로 낸 내용이 그대로 붙어 나와서, 원인(여기서는 Cannot find module)을 바로 읽을 수 있습니다. 서버 줄에서 Enter를 누르면 Restart와 Disable을 고를 수 있고요. 이때도 ~/.gemini/antigravity-cli/mcp/ 아래에는 붙은 demo 폴더만 생겼습니다.

화면 맨 위 묶음 이름은 Plugins (~\.gemini\config\plugins)로 나왔지만, 두 서버는 위에서 말한 대로 작업 폴더의 .agents/mcp_config.json에 적은 것입니다.

다른 도구의 연결 실패 점검 순서는 MCP 서버 연결 실패 원인 가르기에 있어요.

agy -p에서 MCP 쓰기

설정하지 않은 MCP 도구의 기본값은 묻기(Ask)이고, agy -p는 물을 수 없으니 거부합니다. 허용 규칙 없이 보낸 결과는 이랬어요.

{"conversation_id":"<id>","status":"SUCCESS","response":"",…,"denied_actions":[{"action":"mcp","display_name":"CallMcpTool"}]}

종료 코드 0, status도 SUCCESS인데 답이 비어 있습니다. 이런 “성공으로 보고되는 실패”를 스크립트에서 잡는 법은 Antigravity CLI 헤드리스 모드 글에 정리했습니다.

해결은 전역 설정 ~/.gemini/antigravity-cli/settings.json에 서버 단위 허용 규칙을 넣는 겁니다. 형식은 mcp(서버/도구), mcp(서버/*), mcp(*) 세 가지예요.

{
  "permissions": {
    "allow": ["mcp(wslab/*)"]
  }
}

이 한 줄을 넣고 다시 실행하자 PAPAYA-91이 돌아왔습니다. 에이전트가 먼저 읽은 정의 파일은 작업 폴더 밖(~/.gemini/...)에 있었지만 그 읽기 때문에 막히지는 않았어요.

mcp(*)로 한 번에 다 열면 편하긴 합니다. 하지만 그러면 나중에 등록하는 서버까지 묻지 않고 열려요. 위에서 봤듯 등록된 서버는 실행할 때마다 다 뜨니까, 저는 서버 단위로 여는 쪽을 권합니다.

특정 도구만 빼려면 서버 설정의 disabledTools에 이름을 적습니다. lab_secret_word를 빼고 같은 질문을 보내자 MCP 호출은 일어나지 않았어요. 다만 에이전트가 대신 셸 명령을 시도하다 거부돼 결과는 빈 답의 SUCCESS였고, 캐시 폴더의 lab_secret_word.json은 그대로 남아 있었습니다.

직접 해 보니 막힌 두 군데

상대 경로로 등록한 서버가 다른 폴더에서 안 뜸

agy mcp add lab2 -- node lab-server.mjs처럼 상대 경로로 등록한 서버가, 서버 파일이 있는 폴더에서는 붙었는데 다른 폴더에서 실행하자 쓸 수 없었습니다. 인자의 상대 경로가 agy를 실행한 폴더 기준으로 풀린 것으로 짐작해요. 전역 설정은 모든 폴더에서 읽히니, 전역에 등록하는 서버는 인자를 절대 경로로 적거나 cwd 키로 작업 폴더를 고정하세요.

모든 권한을 열자 에이전트가 설정 파일을 직접 고침

위의 상대 경로 서버를 다른 폴더에서 부르라고 하면서 --dangerously-skip-permissions를 붙였더니, 에이전트가 서버에 닿지 못하자 전역 mcp_config.json을 스스로 고쳤습니다. lab2의 인자를 절대 경로로 바꾸면서 "disabled": false 키도 지웠고, 서버 파일도 작업 폴더로 복사했어요. 묻지 않고 진행되는 모드라 확인 단계가 없었고, 진행을 지켜보다 중간에 멈췄습니다.

이 플래그는 파일 쓰기와 명령 실행을 모두 승인합니다. MCP 도구만 필요했다면 위의 mcp(서버/*) 규칙으로 충분했어요.

마치며

Antigravity CLI에서 MCP 서버를 붙이는 명령 자체는 어렵지 않습니다. 어려운 건 agy -p에서는 실패가 보이지 않는다는 점이었어요. 잘못 적은 서버는 조용히 빠지고, 권한이 없으면 빈 답이 SUCCESS로 돌아옵니다. 대화형 화면의 /mcp에서는 같은 실패가 ✗와 오류 출력으로 바로 보였고요.

그래서 서버를 등록했다면 먼저 /mcp에서 ✓가 붙었는지 보세요. agy -p로 쓸 서버라면 ~/.gemini/antigravity-cli/mcp/ 아래에 그 서버의 도구 파일이 방금 시각으로 생겼는지까지 확인하는 걸 등록의 마지막 단계로 생각하시길 권합니다.

권한은 --dangerously-skip-permissions로 통째로 열기보다 mcp(서버/*)처럼 서버 단위로 여는 게 낫습니다. 모든 권한을 연 실행에서는 에이전트가 전역 설정 파일까지 스스로 고쳤으니까요. 같은 서버를 Claude Code에도 붙이려면 Claude Code MCP 설정: stdio·HTTP와 범위 고르기로 이어 가면 됩니다.