Конечные точки 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 вышестоящего уровня. MCP-сервер z.ai также предоставляет мощные возможности (поиск, чтение, визуальный анализ), но прямая настройка означает, что нужно раскрывать z.ai Key в каждом клиенте.

Решение Antigravity Tools: единообразно управлять z.ai Key на уровне локального шлюза, раскрыть конечные точки MCP, клиенту нужно только подключиться к локальному шлюзу, не нужно знать z.ai Key.

Когда использовать этот метод

У вас есть несколько клиентов MCP (Claude Desktop, Cursor, собственные инструменты), вы хотите единообразно использовать один набор z.ai Key
Вы хотите раскрыть возможности Web Search/Web Reader/Vision z.ai как инструменты для использования AI
Вы не хотите повторно настраивать и ротировать z.ai Key в нескольких местах

🎒 Подготовка

Предварительные условия

Вы уже запустили службу прокси на странице «API Proxy» Antigravity Tools
Вы уже получили z.ai API Key (из консоли z.ai)
Вы знаете порт прокси (по умолчанию 8045)

Что такое MCP?

MCP (Model Context Protocol) — это открытый протокол, позволяющий клиентам AI вызывать внешние инструменты/источники данных.

Типичный процесс взаимодействия MCP:

Клиент (например, Claude Desktop) отправляет запрос tools/list в MCP Server, получает список доступных инструментов
Клиент выбирает инструмент по контексту, отправляет запрос tools/call
MCP Server выполняет инструмент и возвращает результат (текст, изображение, данные и т.д.)

Antigravity Tools предоставляет три конечные точки MCP:

Удалённый обратный прокси: напрямую пересылает на MCP-сервер z.ai (Web Search/Web Reader)
Встроенный сервер: локальная реализация протокола JSON-RPC 2.0, обработка вызова инструментов (Vision)

Что такое конечные точки MCP?

Конечные точки MCP — это набор маршрутов HTTP, предоставляемых Antigravity Tools, позволяющий внешним клиентам MCP вызывать возможности z.ai, при этом Antigravity Tools единообразно управляет аутентификацией и конфигурацией.

Классификация конечных точек

Тип конечной точки	Способ реализации	Локальный путь	Цель вышестоящего уровня
Web Search	Удалённый обратный прокси	`/mcp/web_search_prime/mcp`	`https://api.z.ai/api/mcp/web_search_prime/mcp`
Web Reader	Удалённый обратный прокси	`/mcp/web_reader/mcp`	`https://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 для выполнения визуального анализа

Основная идея

Конечные точки MCP Antigravity Tools следуют следующим принципам проектирования:

Единообразная аутентификация: Antigravity управляет z.ai Key, клиенту не нужно настраивать
Возможность включения/выключения: три конечные точки могут независимо включаться/отключаться
Изоляция сеансов: Vision MCP использует mcp-session-id для изоляции разных клиентов
Прозрачность ошибок: тело ответа и код состояния вышестоящего уровня будут пересылаться как есть (заголовки будут отфильтрованы)

Модель аутентификации

Клиент 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.

Откройте Antigravity Tools, перейдите на страницу API Proxy
Найдите карточку Конфигурация z.ai, нажмите раскрыть
Настройте следующие поля:

yaml

 # Конфигурация z.ai
base_url: "https://api.z.ai/api/anthropic"  # Конечная точка z.ai Anthropic compatibility
api_key: "ваш-z.ai-api-key"               # Получить из консоли z.ai
enabled: true                              # Включить z.ai

Найдите подкарточку Конфигурация 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
  }'

Что вы должны увидеть: Возвращается ответ JSON, содержащий список tools.

Продолжить проверку tools/call (опционально)

Получив tools[].name и tools[].inputSchema, вы можете собрать запрос tools/call по schema (параметры ориентируются на schema, не гадайте поля).

Конечная точка не найдена?

Если получено 404 Not Found, проверьте:

proxy.zai.mcp.enabled ли true
proxy.zai.mcp.web_search_enabled ли true
Запущен ли прокси-сервис

Шаг 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
  }'

Что вы должны увидеть: Возвращается ответ JSON, содержащий список tools.

Шаг 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 (опционально)

Зачем GET конечная точка Vision MCP возвращает поток 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_artifact`	Преобразовать скриншот UI в код/промпт/спецификацию/описание	`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.

Причина:

Конечная точка не включена (соответствующий *_enabled — false)
Прокси-сервис не запущен
Неверный путь URL (обратите внимание на префикс /mcp/)

Решение:

Проверьте конфигурацию proxy.zai.mcp.enabled и соответствующего *_enabled
Проверьте статус прокси-сервиса
Подтвердите формат пути 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 недействителен.

Решение:

Убедитесь, что запрос initialize успешен, и получите mcp-session-id из заголовка ответа
Последующие запросы (tools/list, tools/call, а также SSE keepalive) должны приносить этот заголовок
Если сеанс потерян (например, перезапуск сервиса), нужно повторно initialize

z.ai is not configured

Симптом: Возвращается 400 Bad Request, подсказка z.ai is not configured.

Причина: proxy.zai.enabled — false или api_key пуст.

Решение:

Убедитесь, что proxy.zai.enabled — true
Убедитесь, что proxy.zai.api_key настроен (не пусто)

Неудача вышестоящего запроса

Симптом: Возвращается 502 Bad Gateway или внутренняя ошибка.

Причина:

z.ai API Key недействителен или истёк
Проблема сетевого подключения (нужен вышестоящий прокси)
Ошибка на стороне сервиса z.ai

Решение:

Проверьте правильность z.ai API Key
Проверьте конфигурацию proxy.upstream_proxy (если для доступа к z.ai нужен прокси)
Просмотрите журналы для получения подробной информации об ошибке

Интеграция с внешними клиентами MCP

Пример конфигурации Claude Desktop

Файл конфигурации клиента MCP Claude Desktop (~/.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

Клиент MCP Claude Desktop должен общаться через stdio, если вы напрямую используете HTTP конечную точку, нужно написать wrapper-скрипт для преобразования stdio в HTTP запрос.

Или используйте клиент, поддерживающий HTTP MCP (например, Cursor).

HTTP MCP клиент (например, Cursor)

Если клиент поддерживает HTTP MCP, напрямую настройте URL конечной точки:

yaml

 # Конфигурация MCP Cursor
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

Итог урока

Конечные точки MCP Antigravity Tools раскрывают возможности z.ai как вызываемые инструменты, разделены на два типа:

Удалённый обратный прокси（Web Search/Web Reader）：простая пересылка, без состояния
Встроенный сервер（Vision MCP）：полная реализация JSON-RPC 2.0, управление сеансами

Ключевые моменты:

Единообразная аутентификация: z.ai Key управляется Antigravity, клиенту не нужно настраивать
Возможность включения/выключения: три конечные точки могут независимо включаться/отключаться
Изоляция сеансов: Vision MCP использует mcp-session-id для изоляции клиентов
Гибкая интеграция: поддерживает любой клиент, совместимый с протоколом MCP

Предпросмотр следующего урока

В следующем уроке мы изучим Туннель Cloudflared в один клик.
Вы узнаете:
Как установить и запустить туннель Cloudflared в один клик
Разница между режимом quick и режимом auth
Как безопасно раскрыть локальный API в публичную сеть

Приложение: Справочник по исходному коду

Нажмите, чтобы раскрыть расположение исходного кода

Обновлено: 2026-01-23

Функция	Путь к файлу	Строки
Конечная точка Web Search	`src-tauri/src/proxy/handlers/mcp.rs`	115-135
Конечная точка Web Reader	`src-tauri/src/proxy/handlers/mcp.rs`	137-157
Конечная точка Vision MCP (главный вход)	`src-tauri/src/proxy/handlers/mcp.rs`	376-397
Обработка initialize Vision MCP	`src-tauri/src/proxy/handlers/mcp.rs`	271-293
Обработка tools/list Vision MCP	`src-tauri/src/proxy/handlers/mcp.rs`	311-314
Обработка tools/call Vision MCP	`src-tauri/src/proxy/handlers/mcp.rs`	315-363
Управление состоянием сеанса Vision MCP	`src-tauri/src/proxy/zai_vision_mcp.rs`	1-42
Определение инструментов Vision MCP	`src-tauri/src/proxy/zai_vision_tools.rs`	166-271
Реализация вызова инструментов Vision MCP	`src-tauri/src/proxy/zai_vision_tools.rs`	273-400
Регистрация маршрутов	`src-tauri/src/proxy/server.rs`	157-169
Промежуточное ПО аутентификации	`src-tauri/src/proxy/middleware/auth.rs`	1-78
UI конфигурации MCP	`src/pages/ApiProxy.tsx`	1304-1357
Документация описания в репозитории	`docs/zai/mcp.md`	1-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

Запуск с нуля

Что делать при возникновении ошибки

Руководство по обновлению без ошибок

Подключите вашу AI платформу

Обновите систему до производственного уровня

Конечные точки MCP: Раскрыть Web Search/Reader/Vision как вызываемые инструменты

Чему вы научитесь

Текущие проблемы

Когда использовать этот метод

🎒 Подготовка

Что такое конечные точки MCP?

Классификация конечных точек

Ключевые различия

Основная идея

Модель аутентификации

Пошаговое руководство

Шаг 1: Настройте z.ai и включите функциональность MCP

Шаг 2: Проверьте конечную точку Web Search

Шаг 3: Проверьте конечную точку Web Reader

Шаг 4: Проверьте конечную точку Vision MCP (управление сеансом)

4.1 Инициализация сеанса

4.2 Получить список инструментов

4.3 Вызвать инструмент

Шаг 5: Проверьте SSE keepalive (опционально)

Контрольные точки ✅

Проверка конфигурации

Проверка функциональности

Справочник инструментов Vision MCP

Частые ошибки

404 Not Found

400 Bad Request: Missing Mcp-Session-Id

z.ai is not configured

Неудача вышестоящего запроса

Интеграция с внешними клиентами MCP

Пример конфигурации Claude Desktop

HTTP MCP клиент (например, Cursor)

Итог урока

Предпросмотр следующего урока

Приложение: Справочник по исходному коду

Конечные точки MCP: Раскрыть Web Search/Reader/Vision как вызываемые инструменты ​

Чему вы научитесь ​

Текущие проблемы ​

Когда использовать этот метод ​

🎒 Подготовка ​

Что такое конечные точки MCP? ​

Классификация конечных точек ​

Ключевые различия ​

Основная идея ​

Модель аутентификации ​

Пошаговое руководство ​

Шаг 1: Настройте z.ai и включите функциональность MCP ​

Шаг 2: Проверьте конечную точку Web Search ​

Шаг 3: Проверьте конечную точку Web Reader ​

Шаг 4: Проверьте конечную точку Vision MCP (управление сеансом) ​

4.1 Инициализация сеанса ​

4.2 Получить список инструментов ​

4.3 Вызвать инструмент ​

Шаг 5: Проверьте SSE keepalive (опционально) ​

Контрольные точки ✅ ​

Проверка конфигурации ​

Проверка функциональности ​

Справочник инструментов Vision MCP ​

Частые ошибки ​

404 Not Found ​

400 Bad Request: Missing Mcp-Session-Id ​

z.ai is not configured ​

Неудача вышестоящего запроса ​

Интеграция с внешними клиентами MCP ​

Пример конфигурации Claude Desktop ​

HTTP MCP клиент (например, Cursor) ​

Итог урока ​

Предпросмотр следующего урока ​

Приложение: Справочник по исходному коду ​

Конечные точки MCP: Раскрыть Web Search/Reader/Vision как вызываемые инструменты

Чему вы научитесь

Текущие проблемы

Когда использовать этот метод

🎒 Подготовка

Что такое конечные точки MCP?

Классификация конечных точек

Ключевые различия

Основная идея

Модель аутентификации

Пошаговое руководство

Шаг 1: Настройте z.ai и включите функциональность MCP

Шаг 2: Проверьте конечную точку Web Search

Шаг 3: Проверьте конечную точку Web Reader

Шаг 4: Проверьте конечную точку Vision MCP (управление сеансом)

4.1 Инициализация сеанса

4.2 Получить список инструментов

4.3 Вызвать инструмент

Шаг 5: Проверьте SSE keepalive (опционально)

Контрольные точки ✅

Проверка конфигурации

Проверка функциональности

Справочник инструментов Vision MCP

Частые ошибки

404 Not Found

400 Bad Request: Missing Mcp-Session-Id

z.ai is not configured

Неудача вышестоящего запроса

Интеграция с внешними клиентами MCP

Пример конфигурации Claude Desktop

HTTP MCP клиент (например, Cursor)

Итог урока

Предпросмотр следующего урока

Приложение: Справочник по исходному коду