Skip to content

MCP 엔드포인트: Web Search/Reader/Vision을 호출 가능한 도구로 노출 ​

이 MCP 엔드포인트를 사용하여 z.ai의 검색, 읽기, 시각 능력을 외부 MCP 클라이언트에 노출합니다. "원격 리버스 프록시"와 "내장 서버"의 차이를 명확히 파악하고 이러한 엔드포인트를 활성화 및 호출하는 방법을 학습합니다.

학습 후 할 수 있는 것 ​

  • 세 가지 MCP 엔드포인트의 작동 원리 이해(원격 리버스 프록시 vs 내장 서버)
  • Antigravity Tools에서 Web Search/Web Reader/Vision MCP 엔드포인트 활성화
  • 외부 MCP 클라이언트(예: Claude Desktop, Cursor)가 로컬 게이트웨이를 통해 이러한 능력을 호출
  • 세션 관리(Vision MCP) 및 인증 모델 마스터

현재 직면한 문제 ​

많은 AI 도구가 MCP(Model Context Protocol)를 지원하기 시작했지만 업스트림 API Key와 URL을 구성해야 합니다. z.ai의 MCP 서버도 강력한 능력(검색, 읽기, 시각 분석)을 제공하지만 직접 구성하면 각 클라이언트에 z.ai Key를 노출해야 합니다.

Antigravity Tools의 솔루션은 로컬 게이트웨이 레벨에서 z.ai Key를 통합 관리하고 MCP 엔드포인트를 노출하며 클라이언트는 로컬 게이트웨이에만 연결하면 되고 z.ai Key를 알 필요가 없습니다.

이 방법을 사용하는 경우 ​

  • 여러 MCP 클라이언트(Claude Desktop, Cursor, 자체 개발 도구)가 있고 통합된 z.ai Key 세트를 사용하고 싶음
  • z.ai의 Web Search/Web Reader/Vision 능력을 도구로 AI에 노출하고 싶음
  • 여러 곳에서 반복적으로 구성하고 z.ai Key를 순환하고 싶지 않음

🎒 시작 전 준비 ​

전제 조건

  • 이미 Antigravity Tools의 "API Proxy" 페이지에서 리버스 프록시 서비스를 시작함
  • 이미 z.ai API Key 획득(z.ai 콘솔에서)
  • 리버스 프록시 포트 알기(기본값 8045)

MCP란 무엇입니까?

MCP(Model Context Protocol)는 AI 클라이언트가 외부 도구/데이터 소스를 호출할 수 있는 개방형 프로토콜입니다.

전형적인 MCP 상호작용 흐름:

  1. 클라이언트(예: Claude Desktop)가 MCP Server에 tools/list 요청을 보내 사용 가능한 도구 목록 획득
  2. 클라이언트가 컨텍스트에 따라 도구를 선택하고 tools/call 요청 전송
  3. MCP Server가 도구를 실행하고 결과 반환(텍스트, 이미지, 데이터 등)

Antigravity Tools는 세 가지 MCP 엔드포인트를 제공합니다:

  • 원격 리버스 프록시: z.ai MCP 서버로 직접 전달(Web Search/Web Reader)
  • 내장 서버: 로컬에서 JSON-RPC 2.0 프로토콜 구현, 도구 호출 처리(Vision)

MCP 엔드포인트란? ​

MCP 엔드포인트는 Antigravity Tools가 노출하는 HTTP 라우트 세트로 외부 MCP 클라이언트가 z.ai의 능력을 호출할 수 있으며 Antigravity Tools가 통합적으로 인증 및 구성을 관리합니다.

엔드포인트 분류 ​

엔드포인트 유형구현 방식로컬 경로업스트림 대상
Web Search원격 리버스 프록시/mcp/web_search_prime/mcphttps://api.z.ai/api/mcp/web_search_prime/mcp
Web Reader원격 리버스 프록시/mcp/web_reader/mcphttps://api.z.ai/api/mcp/web_reader/mcp
Vision MCP내장 서버(JSON-RPC 2.0)/mcp/zai-mcp-server/mcp내부에서 z.ai PaaS API 호출

핵심 차이 ​

원격 리버스 프록시 vs 내장 서버

원격 리버스 프록시(Web Search/Web Reader):

  • 프록시는 부분 요청 헤더(content-type, accept, user-agent)를 유지하고 Authorization 헤더를 주입
  • 프록시는 업스트림 응답 본문 및 상태 코드를 전달하지만 CONTENT_TYPE 응답 헤더만 유지
  • 상태 없음, 세션 관리 필요 없음

내장 서버(Vision MCP):

  • JSON-RPC 2.0 프로토콜 완전 구현(initialize, tools/list, tools/call)
  • 상태 있음: 세션 생성(mcp-session-id), GET 엔드포인트는 SSE keepalive 반환
  • 도구 로직은 로컬에서 구현되며 z.ai PaaS API를 호출하여 시각 분석 수행

핵심 아이디어 ​

Antigravity Tools의 MCP 엔드포인트는 다음 설계 원칙을 따릅니다:

  1. 통합 인증: Antigravity에서 z.ai Key 관리, 클라이언트 구성 불필요
  2. 온오프 가능: 세 엔드포인트가 독립적으로 활성화/비활성화 가능
  3. 세션 격리: Vision MCP는 mcp-session-id로 다른 클라이언트 격리
  4. 오류 투명: 업스트림 응답 본문 및 상태 코드를 그대로 전달(응답 헤더 필터링)

인증 모델 ​

MCP 클라이언트 → Antigravity 로컬 프록시 → z.ai 업스트림
                ↓
            [선택 사항] proxy.auth_mode
                ↓
            [자동] z.ai Key 주입

Antigravity Tools의 프록시 미들웨어(src-tauri/src/proxy/middleware/auth.rs)는 proxy.auth_mode를 확인합니다. 인증을 활성화하면 클라이언트가 API Key를 휴대해야 합니다.

중요: proxy.auth_mode가 어떻든 z.ai Key는 프록시에서 자동으로 주입되며 클라이언트는 구성할 필요가 없습니다.

따라 해 보기 ​

1단계: z.ai 구성 및 MCP 기능 활성화 ​

이유 먼저 z.ai 기본 구성이 올바른지 확인한 다음 MCP 엔드포인트를 하나씩 활성화합니다.

  1. Antigravity Tools 열기, API Proxy 페이지 진입
  2. z.ai 구성 카드 찾기, 확장 클릭
  3. 다음 필드 구성:
yaml
 # z.ai 구성
base_url: "https://api.z.ai/api/anthropic"  # z.ai Anthropic 호환 엔드포인트
api_key: "z.ai-api-key"                    # z.ai 콘솔에서 획득
enabled: true                              # z.ai 활성화
  1. MCP 구성 하위 카드 찾기, 다음 구성:
yaml
 # MCP 구성
enabled: true                              # MCP 마스터 스위치 활성화
web_search_enabled: true                    # Web Search 활성화
web_reader_enabled: true                    # Web Reader 활성화
vision_enabled: true                        # Vision MCP 활성화

다음을 보아야 합니다: 구성 저장 후 페이지 하단에 "로컬 MCP 엔드포인트" 목록이 나타나며 세 엔드포인트의 전체 URL이 표시됩니다.

2단계: Web Search 엔드포인트 검증 ​

이유 Web Search는 원격 리버스 프록시이므로 가장 간단하며 기본 구성 검증에 적합합니다.

bash
 # 1) 먼저 Web Search 엔드포인트가 제공하는 도구 나열(도구 이름은 실제 반환을 기준)
curl -X POST http://127.0.0.1:8045/mcp/web_search_prime/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

다음을 보아야 합니다: tools 리스트가 포함된 JSON 응답을 반환합니다.

tools/call 계속 검증(선택 사항)

tools[].name 및 tools[].inputSchema를 얻은 후 schema에 따라 tools/call 요청을 조합할 수 있습니다(매개변수는 schema를 기준으로 하며 필드 추측 금지).

엔드포인트를 찾을 수 없음?

404 Not Found를 수신하면 다음을 확인하세요:

  1. proxy.zai.mcp.enabled가 true인지
  2. proxy.zai.mcp.web_search_enabled가 true인지
  3. 리버스 프록시 서비스가 실행 중인지

3단계: Web Reader 엔드포인트 검증 ​

이유 Web Reader도 원격 리버스 프록시이지만 매개변수 및 반환 형식이 다르며 프록시가 다른 엔드포인트를 올바르게 처리하는지 검증합니다.

bash
 # 2) Web Reader 엔드포인트가 제공하는 도구 나열
curl -X POST http://127.0.0.1:8045/mcp/web_reader/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 2
  }'

다음을 보아야 합니다: tools 리스트가 포함된 JSON 응답을 반환합니다.

4단계: Vision MCP 엔드포인트 검증(세션 관리) ​

이유 Vision MCP는 내장 서버이며 세션 상태가 있으므로 먼저 initialize한 다음 도구를 호출해야 합니다.

4.1 세션 초기화 ​

bash
 # 1) initialize 요청 전송
curl -X POST http://127.0.0.1:8045/mcp/zai-mcp-server/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05"
    },
    "id": 1
  }'

다음을 보아야 합니다: 응답에 mcp-session-id 헤더가 포함되어 있으며 이 ID를 저장합니다.

json
{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": {
      "name": "zai-mcp-server",
      "version": "<app-version>"
    }
  },
  "id": 1
}

알림

serverInfo.version은 Rust의 env!("CARGO_PKG_VERSION")에서 오며 본인의 실제 설치 버전을 기준으로 합니다.

응답 헤더:

mcp-session-id: uuid-v4-string

4.2 도구 목록 획득 ​

bash
 # 2) tools/list 요청 전송(세션 ID 포함)
curl -X POST http://127.0.0.1:8045/mcp/zai-mcp-server/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: 세션ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 2
  }'

다음을 보아야 합니다: 8개 도구의 정의를 반환합니다(ui_to_artifact, extract_text_from_screenshot, diagnose_error_screenshot 등).

4.3 도구 호출 ​

bash
 # 3) analyze_image 도구 호출
curl -X POST http://127.0.0.1:8045/mcp/zai-mcp-server/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: 세션ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "analyze_image",
      "arguments": {
        "image_source": "https://example.com/image.jpg",
        "prompt": "이미지 내용 설명"
      }
    },
    "id": 3
  }'

다음을 보아야 합니다: 이미지 분석 결과의 텍스트 설명을 반환합니다.

세션 ID 중요

Vision MCP의 모든 요청(initialize 제외)은 mcp-session-id 헤더를 휴대해야 합니다.

세션 ID는 initialize 응답에서 반환되며 후속 요청은 동일한 ID를 사용해야 합니다. 세션이 손실되면 다시 initialize해야 합니다.

5단계: SSE keepalive 테스트(선택 사항) ​

이유 Vision MCP의 GET 엔드포인트는 SSE(Server-Sent Events) 스트림을 반환하며 연결을 활성 상태로 유지하는 데 사용됩니다.

bash
 # 4) GET 엔드포인트 호출(SSE 스트림 획득)
curl -N http://127.0.0.1:8045/mcp/zai-mcp-server/mcp \
  -H "mcp-session-id: 세션ID"

다음을 보아야 합니다: 15초마다 event: ping 메시지를 받으며 형식은 다음과 같습니다:

event: ping
data: keepalive

event: ping
data: keepalive
...

체크포인트 ✅ ​

구성 확인 ​

  • [ ] proxy.zai.enabled가 true임
  • [ ] proxy.zai.api_key가 구성되었음(비어 있지 않음)
  • [ ] proxy.zai.mcp.enabled가 true임
  • [ ] 최소 하나의 MCP 엔드포인트가 활성화됨(web_search_enabled / web_reader_enabled / vision_enabled)
  • [ ] 리버스 프록시 서비스가 실행 중

기능 검증 ​

  • [ ] Web Search 엔드포인트가 검색 결과를 반환
  • [ ] Web Reader 엔드포인트가 웹 페이지 내용을 반환
  • [ ] Vision MCP 엔드포인트가 성공적으로 initialize하고 mcp-session-id를 획득
  • [ ] Vision MCP 엔드포인트가 도구 목록을 반환(8개 도구)
  • [ ] Vision MCP 엔드포인트가 성공적으로 도구를 호출하고 결과를 반환

Vision MCP 도구 요약 ​

도구 이름기능필수 매개변수예시 시나리오
ui_to_artifactUI 스크린샷을 코드/프롬프트/사양/설명으로 변환image_source, output_type, prompt디자인 초안에서 프론트엔드 코드 생성
extract_text_from_screenshot스크린샷에서 텍스트/코드 추출(OCR과 유사)image_source, prompt오류 로그 스크린샷 읽기
diagnose_error_screenshot오류 스크린샷 진단(스택 추적, 로그)image_source, prompt런타임 오류 분석
understand_technical_diagram아키텍처/흐름/UML/ER 다이어그램 분석image_source, prompt시스템 아키텍처 다이어그램 이해
analyze_data_visualization차트/대시보드 분석image_source, prompt대시보드에서 트렌드 추출
ui_diff_check두 UI 스크린샷 비교 및 차이점 보고expected_image_source, actual_image_source, prompt시각적 회귀 테스트
analyze_image일반 이미지 분석image_source, prompt이미지 내용 설명
analyze_video비디오 내용 분석video_source, prompt비디오 장면 분석

매개변수 설명

  • image_source: 로컬 파일 경로(예: /tmp/screenshot.png) 또는 원격 URL(예: https://example.com/image.jpg)
  • video_source: 로컬 파일 경로 또는 원격 URL(MP4, MOV, M4V 지원)
  • output_type(ui_to_artifact): code / prompt / spec / description

피해야 할 함정 ​

404 Not Found ​

현상: MCP 엔드포인트 호출 시 404 Not Found 반환.

원인:

  1. 엔드포인트 활성화되지 않음(해당 *_enabled가 false)
  2. 리버스 프록시 서비스 시작되지 않음
  3. URL 경로 오류(/mcp/ 접두사 주의)

해결:

  1. proxy.zai.mcp.enabled 및 해당 *_enabled 구성 확인
  2. 리버스 프록시 서비스 상태 확인
  3. URL 경로 형식 확인(예: /mcp/web_search_prime/mcp)

400 Bad Request: Missing Mcp-Session-Id ​

현상: Vision MCP 호출 시(initialize 제외) 400 Bad Request 반환.

  • GET 엔드포인트: 순 텍스트 Missing Mcp-Session-Id 반환
  • POST 엔드포인트: JSON-RPC 오류 {"error":{"code":-32000,"message":"Bad Request: missing Mcp-Session-Id"}} 반환

원인: 요청 헤더에 mcp-session-id가 없거나 ID가 무효함.

해결:

  1. initialize 요청이 성공했는지 확인하고 응답 헤더에서 mcp-session-id 획득
  2. 후속 요청(tools/list, tools/call, SSE keepalive)는 모두 해당 헤더를 휴대해야 함
  3. 세션이 손실된 경우(예: 서비스 재시작) 다시 initialize해야 함

z.ai is not configured ​

현상: 400 Bad Request를 반환하며 z.ai is not configured 메시지.

원인: proxy.zai.enabled가 false이거나 api_key가 비어 있음.

해결:

  1. proxy.zai.enabled가 true인지 확인
  2. proxy.zai.api_key가 구성되었는지 확인(비어 있지 않음)

업스트림 요청 실패 ​

현상: 502 Bad Gateway 또는 내부 오류 반환.

원인:

  1. z.ai API Key가 무효하거나 만료됨
  2. 네트워크 연결 문제(업스트림 프록시 필요)
  3. z.ai 서버 오류

해결:

  1. z.ai API Key가 올바른지 확인
  2. proxy.upstream_proxy 구성 확인(z.ai 액세스에 프록시가 필요한 경우)
  3. 로그를 확인하여 상세한 오류 정보 획득

외부 MCP 클라이언트와 통합 ​

Claude Desktop 구성 예시 ​

Claude Desktop의 MCP 클라이언트 구성 파일(~/.config/claude/claude_desktop_config.json):

json
{
  "mcpServers": {
    "antigravity-vision": {
      "command": "node",
      "args": [
        "/path/to/mcp-client-wrapper.js",
        "--endpoint",
        "http://127.0.0.1:8045/mcp/zai-mcp-server/mcp"
      ]
    },
    "antigravity-web-search": {
      "command": "node",
      "args": [
        "/path/to/mcp-client-wrapper.js",
        "--endpoint",
        "http://127.0.0.1:8045/mcp/web_search_prime/mcp"
      ]
    }
  }
}

Claude Desktop의 제한

Claude Desktop의 MCP 클라이언트는 stdio로 통신해야 합니다. HTTP 엔드포인트를 직접 사용하면 stdio를 HTTP 요청으로 변환하는 wrapper 스크립트를 작성해야 합니다.

또는 HTTP MCP를 지원하는 클라이언트(예: Cursor)를 사용하세요.

HTTP MCP 클라이언트(예: Cursor) ​

클라이언트가 HTTP MCP를 지원하면 엔드포인트 URL을 직접 구성할 수 있습니다:

yaml
 # Cursor MCP 구성
mcpServers:
  - name: antigravity-vision
    url: http://127.0.0.1:8045/mcp/zai-mcp-server/mcp
  - name: antigravity-web-search
    url: http://127.0.0.1:8045/mcp/web_search_prime/mcp

이 수업 요약 ​

Antigravity Tools의 MCP 엔드포인트는 z.ai의 능력을 호출 가능한 도구로 노출하며 두 가지 유형으로 나뉩니다:

  • 원격 리버스 프록시(Web Search/Web Reader): 간단한 전달, 상태 없음
  • 내장 서버(Vision MCP): JSON-RPC 2.0 완전 구현, 세션 관리 포함

핵심 포인트:

  1. 통합 인증: z.ai Key는 Antigravity에서 관리하며 클라이언트는 구성할 필요 없음
  2. 온오프 가능: 세 엔드포인트가 독립적으로 활성화/비활성화 가능
  3. 세션 격리: Vision MCP는 mcp-session-id로 클라이언트 격리
  4. 유연한 통합: MCP 프로토콜을 지원하는 모든 클라이언트 지원

다음 수업 예고 ​

다음 수업에서는 **Cloudflared 원클릭 터널**를 학습합니다.

학습하게 될 내용:

  • Cloudflared 터널을 원클릭으로 설치 및 시작하는 방법
  • quick 모드 vs auth 모드의 차이
  • 로컬 API를 공개 네트워크에 안전하게 노출하는 방법

부록: 소스코드 참조 ​

클릭하여 소스코드 위치 확인

업데이트 시간: 2026-01-23

기능파일 경로행 번호
Web Search 엔드포인트src-tauri/src/proxy/handlers/mcp.rs115-135
Web Reader 엔드포인트src-tauri/src/proxy/handlers/mcp.rs137-157
Vision MCP 엔드포인트(메인 엔트리)src-tauri/src/proxy/handlers/mcp.rs376-397
Vision MCP initialize 처리src-tauri/src/proxy/handlers/mcp.rs271-293
Vision MCP tools/list 처리src-tauri/src/proxy/handlers/mcp.rs311-314
Vision MCP tools/call 처리src-tauri/src/proxy/handlers/mcp.rs315-363
Vision MCP 세션 상태 관리src-tauri/src/proxy/zai_vision_mcp.rs1-42
Vision MCP 도구 정의src-tauri/src/proxy/zai_vision_tools.rs166-271
Vision MCP 도구 호출 구현src-tauri/src/proxy/zai_vision_tools.rs273-400
라우팅 등록src-tauri/src/proxy/server.rs157-169
인증 미들웨어src-tauri/src/proxy/middleware/auth.rs1-78
MCP 구성 UIsrc/pages/ApiProxy.tsx1304-1357
저장소 내 설명 문서docs/zai/mcp.md1-57

핵심 상수:

  • ZAI_PAAZ_CHAT_COMPLETIONS_URL = "https://api.z.ai/api/paas/v4/chat/completions": z.ai PaaS API 엔드포인트(Vision 도구 호출용)

핵심 함수:

  • handle_web_search_prime(): Web Search 엔드포인트의 원격 리버스 프록시 처리
  • handle_web_reader(): Web Reader 엔드포인트의 원격 리버스 프록시 처리
  • handle_zai_mcp_server(): Vision MCP 엔드포인트의 모든 메서드 처리(GET/POST/DELETE)
  • mcp_session_id(): 요청 헤더에서 mcp-session-id 추출
  • forward_mcp(): 일반 MCP 전달 함수(인증 주입 및 업스트림 전달)
  • tool_specs(): Vision MCP의 도구 정의 목록 반환
  • call_tool(): 지정된 Vision MCP 도구 실행