Документация MCP Marketplace

MCP Marketplace — Руководство по интеграциям

Что такое MCP и зачем он нужен?

MCP (Model Context Protocol) – это открытый стандарт, позволяющий AI-ассистентам использовать внешние инструменты. Представьте его как «USB для AI» – так же, как USB позволяет подключить любое периферийное устройство к компьютеру, MCP позволяет подключить любой инструмент к AI-агенту.

MCP Marketplace — список серверов

Без MCP AI-ассистент может только читать текст и генерировать текст. С MCP он может просматривать веб-сайты, искать код в репозиториях, читать файлы, делать запросы к БД и вызывать API – через единый стандартный интерфейс.

Зачем это в Mockarty: MCP Marketplace – это место, где вы подключаете внешние инструменты к встроенному AI-агенту Mockarty. После подключения AI может использовать эти инструменты при генерации моков, запуске тестов или анализе API. Например:

  • Подключите Playwright, чтобы AI мог делать скриншоты вашего веб-приложения и создавать моки, соответствующие реальному UI.
  • Подключите ваш GitHub-репозиторий, чтобы AI смотрел на реальный код при генерации моков.
  • Подключите базу знаний с документацией API, чтобы AI генерировал точные ответы.

Опыт работы с AI не требуется. Вам не нужно разбираться в AI или LLM, чтобы использовать маркетплейс. Просто подключите инструмент, включите его, и AI сам определит, когда и как его использовать.

URL-адреса в примерах: Во всех примерах используется localhost:5770 как адрес Mockarty по умолчанию. Если ваш экземпляр работает на удалённом сервере, замените localhost:5770 на реальный адрес (например, https://mockarty.company.com или http://192.168.1.50:5770). Подробнее — в разделе Полезные функции и советы.

Страница MCP Marketplace с подключёнными интеграциями

Как это работает

MCP Marketplace поддерживает шесть типов источников для подключения внешних инструментов:

Тип источника Что подключает Примеры
MCP Server Специальные провайдеры инструментов для AI Playwright, Filesystem, GitHub, Fetch
OpenAPI Spec Любой REST API со спецификацией Swagger/OpenAPI Ваши внутренние API, сторонние сервисы
gRPC gRPC-сервисы (через серверную рефлексию) Микросервисы с proto-определениями
WSDL Устаревшие SOAP веб-сервисы Корпоративные интеграции
A2A Agent Другие AI-агенты (протокол Agent-to-Agent) Специализированные агенты анализа
RAG Базы знаний RAGFlow, AnythingLLM, Dify

Каждый тип источника подробно описан ниже.

MCP Server OpenAPI / gRPC WSDL / A2A RAG (базы знаний) Mockarty MCP Marketplace обнаружение + маршрутизация инструменты ИИ-агент Конструктор, API Tester, Чат с агентом

Как добавить интеграцию

  1. Перейдите в Администрирование → ИИ и LLM → MCP Marketplace
  2. Нажмите Добавить интеграцию или используйте Пресет быстрой настройки
  3. Выберите тип источника, укажите URL, настройте аутентификацию
  4. Нажмите Сохранить — инструменты обнаруживаются автоматически
  5. Откройте любую ИИ-функцию (Конструктор, API Тестер и т.д.), нажмите иконку шестерёнки и включите нужные инструменты

Интеграции MCP-серверов

MCP (Model Context Protocol) — серверы специально созданные для предоставления инструментов. Они общаются через JSON-RPC и могут поддерживать сессии с состоянием — например, MCP-сервер Playwright может держать браузер открытым между вызовами инструментов в одном чате.

Playwright (Автоматизация браузера)

Автоматизация реального браузера: скриншоты, клики, заполнение форм, навигация по страницам. Идеально для сценариев UI-тестирования, когда ИИ должен взаимодействовать с вашим веб-приложением.

Развёртывание:

# Через npx (требуется Node.js)
npx @anthropic/mcp-playwright --port 8931

# Через Docker
docker run -d --name playwright-mcp -p 8931:8931 \
  mcr.microsoft.com/playwright:latest \
  npx @anthropic/mcp-playwright --port 8931

Подключение в Mockarty:

  • Тип источника: MCP Server
  • URL: http://localhost:8931/mcp
  • Аутентификация: Нет

Обнаруженные инструменты: browser_navigate, browser_screenshot, browser_click, browser_fill, browser_evaluate и др.

Filesystem (Файловая система)

Чтение и запись файлов на сервере. Полезно для доступа к логам, конфигурациям, шаблонам отчётов или сохранения сгенерированных артефактов.

Развёртывание:

npx @anthropic/mcp-filesystem --port 8932 --root /path/to/allowed/directory

Подключение в Mockarty:

  • Тип источника: MCP Server
  • URL: http://localhost:8932/mcp
  • Аутентификация: Нет

Обнаруженные инструменты: read_file, write_file, list_directory, search_files и др.

Важно по безопасности: MCP-сервер файловой системы ограничивает доступ указанной корневой директорией. Всегда указывайте --root на конкретную директорию, а не на /.

GitHub

Поиск кода, issues, pull requests и файлов в ваших GitHub-репозиториях. ИИ-агент может находить реальные паттерны реализации для генерации точных моков.

Развёртывание:

npx @anthropic/mcp-github --port 8933

# Или через Docker
docker run -d --name github-mcp -p 8933:8933 \
  -e GITHUB_TOKEN=ghp_your_token_here \
  node:20-slim \
  npx @anthropic/mcp-github --port 8933

Подключение в Mockarty:

  • Тип источника: MCP Server
  • URL: http://localhost:8933/mcp
  • Аутентификация: Bearer Token → ваш персональный токен GitHub

Обнаруженные инструменты: search_code, get_file_contents, search_issues, list_repos и др.

Fetch (Веб-скрейпинг)

Загрузка веб-страниц и конвертация в Markdown. ИИ может читать страницы документации, API-референсы или любой веб-контент как контекст для своих задач.

Развёртывание:

npx @anthropic/mcp-fetch --port 8934

Подключение в Mockarty:

  • Тип источника: MCP Server
  • URL: http://localhost:8934/mcp
  • Аутентификация: Нет

Обнаруженные инструменты: fetch, fetch_raw_html

Подключение любого MCP-сервера

Любой MCP-сервер с поддержкой Streamable HTTP транспорта может быть подключён. Сервер должен отвечать на:

  • POST / (или ваш настроенный путь) с JSON-RPC 2.0 сообщениями
  • Метод initialize для настройки сессии
  • tools/list для обнаружения инструментов
  • tools/call для выполнения инструментов

Общие шаги:

  1. Запустите ваш MCP-сервер с HTTP-эндпоинтом
  2. В Mockarty выберите тип источника: MCP Server
  3. Введите URL (например, http://host:port/mcp)
  4. Настройте аутентификацию при необходимости
  5. Сохраните — Mockarty вызовет tools/list для обнаружения доступных инструментов

Интеграции OpenAPI / Swagger

Подключите любой REST API, имеющий OpenAPI (Swagger) спецификацию. Каждый эндпоинт API становится отдельно вызываемым инструментом.

Как это работает

  1. Mockarty загружает и парсит вашу OpenAPI-спецификацию (JSON или YAML)
  2. Каждый эндпоинт становится инструментом:
    • Имя инструмента = operationId или метод_путь (например, getUserById)
    • Описание = summary эндпоинта из спецификации
    • Параметры = path-параметры, query-параметры, заголовки, тело — всё типизировано
    • Тег = первый OpenAPI-тег (для группировки в UI)
  3. Когда ИИ вызывает инструмент, Mockarty делает реальный HTTP-запрос

Настройка

Подключение в Mockarty:

  • Тип источника: OpenAPI Spec
  • URL: Прямая ссылка на вашу спецификацию, например:
    • http://your-api:8080/openapi.json
    • http://your-api:8080/v3/api-docs (Spring Boot)
    • http://your-api:8080/swagger/doc.json (Go Swagger)
    • http://your-api:8080/swagger.yaml
  • Аутентификация: По требованиям вашего API (Bearer, API Key, Basic и др.)

Пример: Если ваша спецификация содержит GET /api/users/{id}, ИИ получает инструмент getUserById. Он вызывает getUserById({"id": "42"}), Mockarty делает HTTP-запрос, и ИИ видит реальную структуру ответа для генерации точного мока.

Советы

  • Используйте URL staging-окружения — пусть ИИ безопасно вызывает реальные эндпоинты
  • Аутентификация проходит транзитом — тот же токен, что для спецификации, используется для вызовов
  • Пользовательские переопределения заголовков — каждый пользователь может указать свой токен (см. Пользовательские заголовки ниже)

Интеграции gRPC

Подключите gRPC-сервис и сделайте его методы доступными как инструменты агента через серверную рефлексию.

Как это работает

  1. Mockarty подключается к вашему gRPC-серверу
  2. Использует gRPC server reflection для обнаружения сервисов и методов
  3. Каждый unary RPC-метод становится инструментом:
    • Имя инструмента = grpc_ServiceName_MethodName
    • Параметры = поля protobuf-сообщения как JSON-свойства
  4. Вызовы инструментов проксируются как реальные gRPC-запросы

Настройка

Предварительные требования: У вашего gRPC-сервера должна быть включена серверная рефлексия.

Подключение в Mockarty:

  • Тип источника: gRPC
  • URL: your-grpc-server:50051 (хост:порт, без префикса http://)
  • Аутентификация: Нет или Bearer-токен (добавляется как metadata authorization)

Пример: gRPC-сервис UserService с методом GetUser(GetUserRequest) становится инструментом grpc_UserService_GetUser с входными данными {"user_id": "42"}.

Включение рефлексии

// Go — добавьте в настройку gRPC-сервера
import "google.golang.org/grpc/reflection"
reflection.Register(grpcServer)

# Python
from grpc_reflection.v1alpha import reflection
reflection.enable_server_reflection(service_names, server)

// Java — добавьте зависимость grpc-services
Server server = ServerBuilder.forPort(50051)
    .addService(ProtoReflectionService.newInstance())
    .build();

Интеграции WSDL / SOAP

Подключите устаревшие SOAP веб-сервисы. Mockarty парсит WSDL и конвертирует SOAP-операции в JSON-инструменты — ИИ не работает с XML-конвертами напрямую.

Как это работает

  1. Mockarty загружает и парсит WSDL-документ
  2. Каждая SOAP-операция становится инструментом с префиксом soap_
  3. Входные данные инструмента — JSON-объекты, соответствующие частям сообщения операции
  4. Mockarty формирует SOAP XML-конверт и делает HTTP-запрос

Настройка

Подключение в Mockarty:

  • Тип источника: WSDL
  • URL: http://your-service/service?wsdl или прямая ссылка на .wsdl файл
  • Аутентификация: По требованиям (Basic Auth часто используется для SOAP-сервисов)

Пример: WSDL с операцией GetCustomerInfo становится инструментом soap_GetCustomerInfo. ИИ вызывает его с {"customerId": "C-123"}, Mockarty оборачивает в SOAP-конверт, отправляет запрос и возвращает разобранный ответ.

Интеграции A2A агентов

Подключите внешних ИИ-агентов по протоколу Agent-to-Agent (A2A). Ваш ИИ-агент может делегировать специализированные задачи другим агентам.

Как это работает

  1. Mockarty загружает карточку агента с {url}/.well-known/agent.json
  2. Объявленные навыки агента становятся доступными инструментами
  3. Вызовы инструментов проксируются к внешнему агенту как A2A task-запросы

Настройка

Подключение в Mockarty:

  • Тип источника: A2A Agent
  • URL: http://your-agent:8080 (базовый URL, Mockarty добавляет /.well-known/agent.json)
  • Аутентификация: По требованиям агента

Пример формата карточки агента:

{
  "name": "Code Review Agent",
  "description": "Специализированный агент для анализа кода",
  "skills": [
    {
      "name": "review_code",
      "description": "Анализ кода на баги, уязвимости и лучшие практики"
    }
  ]
}

Базы знаний (RAG)

Подключите внешние базы знаний, чтобы дать ИИ-агентам доступ к документации компании, API-спецификациям, стандартам кодирования и другим справочным материалам.

Mockarty поддерживает RAGFlow, AnythingLLM, Dify, R2R и любой пользовательский RAG API.

Подробные руководства по настройке, инструкции развёртывания Docker и конфигурация для каждого провайдера:

→ База знаний (RAG) — Полное руководство

Пользовательские заголовки и аутентификация

Аутентификация на уровне сервера (настраивается админом)

Тип аутентификации Что отправляется
Нет Без заголовков аутентификации
Bearer Token Authorization: Bearer <token>
API Key Пользовательский заголовок с ключом (напр., X-API-Key: <key>)
Basic Auth Authorization: Basic <base64>
Custom Headers Любые заголовки в формате JSON

Пользовательские переопределения

Разным пользователям могут потребоваться разные учётные данные для одного сервиса. В настройках ИИ (иконка шестерёнки) пользователи могут добавить переопределения заголовков для каждой интеграции:

  1. Нажмите иконку шестерёнки в любой ИИ-функции
  2. Найдите раздел MCP Tools
  3. Нажмите иконку ключа рядом с инструментом
  4. Добавьте пользовательские заголовки (например, ваш персональный API-токен)

Они объединяются поверх настроенной админом аутентификации — переопределения пользователя имеют приоритет.

Бюджет инструментов

Каждый включённый инструмент добавляется к токен-контексту, отправляемому в LLM. UI маркетплейса показывает индикатор бюджета:

  • Зелёный: в пределах лимитов
  • Жёлтый: приближение к бюджету
  • Красный: превышение бюджета — некоторые инструменты могут быть обрезаны

Советы:

  • Включайте только нужные инструменты для каждой функции
  • Используйте групповое включение/выключение (целые серверы за раз)
  • Инструменты с короткими описаниями потребляют меньше токенов

Устранение проблем

Подключение не удаётся / статус “offline”

  • Проверьте, работает ли сервер: curl http://your-server:port/health
  • Проверьте сеть: убедитесь, что Mockarty может достичь сервер (файрвол, Docker-сеть)
  • Для MCP-серверов: попробуйте curl -X POST http://server:port/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Инструменты не обнаруживаются

  • OpenAPI: Проверьте, что URL спецификации возвращает валидный JSON/YAML (curl напрямую)
  • gRPC: Убедитесь, что серверная рефлексия включена
  • WSDL: Проверьте, что URL возвращает валидный XML
  • Нажмите Refresh Tools для повторного обнаружения

Ошибки аутентификации

  • Перепроверьте токен/ключ в настройках сервера
  • Для Bearer-токенов НЕ включайте префикс Bearer — Mockarty добавляет его сам
  • Протестируйте вручную: curl -H "Authorization: Bearer <token>" http://your-server/endpoint

SSRF-защита блокирует внутренние URL

По умолчанию Mockarty блокирует запросы к приватным IP-диапазонам (10.x, 172.16-31.x, 192.168.x). Для разрешения внутренних сервисов установите переменную окружения:

ALLOW_PROXY_TO_PRIVATE_IPS=true

Высокое потребление токенов

  • Отключите ненужные инструменты для конкретных функций
  • Проверьте индикатор Tool Budget в маркетплейсе
  • Инструменты с большими input-схемами потребляют больше токенов – используйте более простые эндпоинты

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

  • Добавление префикса Bearer в поле токена. Mockarty добавляет префикс Bearer автоматически. Если ввести Bearer ghp_abc123, фактический заголовок будет Authorization: Bearer Bearer ghp_abc123 (двойной префикс), что приведёт к ошибке.
  • Использование http://localhost, когда Mockarty запущен в Docker. Внутри Docker-контейнера localhost указывает на сам контейнер, а не на хост-машину. Используйте http://host.docker.internal или реальное имя хоста сервиса в Docker-сети.
  • Включение слишком многих инструментов сразу. Описание и параметры каждого инструмента потребляют токены контекста LLM. Начните с 2-3 инструментов и добавляйте по мере необходимости. Проверяйте индикатор Tool Budget.
  • Ожидание работы инструментов без их включения. Добавление интеграции в маркетплейс только обнаруживает инструменты. Вы также должны включить конкретные инструменты в настройках AI (иконка шестерёнки) каждой функции, где хотите их использовать.

Связанная документация

  • ИИ-функции – полное руководство по всем ИИ-возможностям, системе агентов, пользовательским агентам и встроенным инструментам
  • База знаний (RAG) – подробная настройка RAGFlow, AnythingLLM, Dify, R2R и кастомных RAG-провайдеров
Предыдущая
Архитектура масштабирования