Перейти к содержанию

MCP Gateway

Начало работы

NEOMSA APIM предоставляет единую платформу для управления серверами MCP, позволяя преобразовывать API в инструменты, готовые к использованию в ИИ, и управлять их жизненным циклом. Благодаря централизованной панели управления вы можете эффективно создавать, обнаруживать и управлять серверами MCP, оптимизируя рабочие процессы как для разработчиков API, так и для создателей агентов ИИ.

Примечание:

В этом руководстве вы узнаете, как определить инструменты, развернуть и опубликовать MCP-сервер в NEOMSA APIM .

Быстрый старт (краткий обзор):

  1. Выберите путь создания (см. ниже).

  2. Определить/подтвердить схемы инструментов (входы/выходы, описания).

  3. Прикрепите политики (аутентификация, ограничение скорости запросов).

  4. Публикация и тестирование (запуск обнаружения, обращение к инструментам, анализ данных).

Важно:

Используйте минималистичные и строго типизированные входные схемы; LLM-модели работают лучше с краткими и однозначными контрактами.

Создайте MCP- сервер, импортировав определение OpenAPI

Этот путь создания используется, если у вас уже есть определение OpenAPI для вашего бэкенд-сервиса, и вы хотите быстро преобразовать его операции в инструменты MCP. Портал издателя импортирует определение, отобразит все доступные операции и позволит вам выбрать, какие из них следует предоставить в качестве инструментов. Затем вы можете настроить параметры вашего MCP-сервера — такие как имя, контекст, версия и конечная точка среды выполнения — перед публикацией через APIM.

Важно:

Качество импортируемых инструментов зависит от качества определения OpenAPI. Четкие идентификаторы операций, описания и схемы параметров приведут к созданию более удобных и информативных инструментов.

  1. Перейдите на портал издателя.

    • Перейдите в раздел «Серверы MCP» на портале издателя.

    • Если у вас уже есть серверы MCP, нажмите кнопку «Создать сервер MCP» . 

- Если это ваш первый сервер MCP, вы увидите страницу "Начнём!".


- В меню навигации нажмите **«Импорт определения API»** → **«Создать MCP-сервер из определения»** .

  1. Дайте определение.

    • Выберите URL-адрес OpenAPI и введите: https://petstore3.swagger.io/api/v3/openapi.json

    • Нажмите «Далее» .

  1. Выберите инструменты для импорта

    • Просмотрите все операции, выполняемые через OpenAPI.

    • Выберите операции, которые необходимо отобразить в качестве инструментов. Нажмите «Далее» .

  1. Введите данные сервера MCP.

Заполните поля ниже и нажмите «Создать» .

Примечание:

В поле Endpoint должен быть указан базовый URL-адрес бэкенда, к которому ваши инструменты будут обращаться во время выполнения, а не URL-адрес документа OpenAPI.

Поле Пример значения
Имя SwaggerPetstore-OpenAPI
Контекст /swaggerpetstore-openapi
Версия 1.0.0
Конечная точка https://petstore3.swagger.io/api/v3

Создание MCP-сервера с использованием существующего API

Этот способ создания идеально подходит, если API, который вы хотите сделать доступным в качестве инструментов MCP, уже развернут в NEOMSA APIM . Вместо того чтобы начинать с файла OpenAPI, вы можете напрямую выбрать API на портале издателя, указать, какие из его операций должны стать инструментами MCP, и настроить параметры сервера MCP.

Этот подход работает быстрее в следующих случаях:

  • У вас есть стабильный API в APIM, и вы хотите расширить его возможностями MCP.

  • Вы хотите повторно использовать существующие механизмы управления API (безопасность, ограничение скорости, аналитика), одновременно обеспечивая доступ в виде инструментов.

Кончик

Хорошо структурированные API-ресурсы с четкими названиями и описаниями приведут к созданию более интуитивно понятных инструментов MCP.

  1. Перейдите на портал издателя.

    • Перейдите в раздел «Серверы MCP» на портале издателя.

    • Если у вас уже есть серверы MCP, нажмите кнопку «Создать сервер MCP» . 

- Если это ваш первый сервер MCP, вы увидите страницу "Начнём!".


- В меню навигации нажмите **«Начать с существующего API»** → **«Создать MCP-сервер с существующего API»** .

  1. Выберите исходный API

    • Из списка доступных API выберите тот, с помощью которого будете создавать инструменты.

    • Нажмите «Далее» .

  1. Выберите ресурсы, которые станут инструментами.

    • Выберите, какие операции API должны стать инструментами.

    • Нажмите «Далее» .

  1. Введите данные сервера MCP.

Укажите необходимые данные и нажмите «Создать» .

Поле Пример значения
Имя Petstore
Контекст /petstore
Версия 1.0.6

Создайте MCP-сервер, используя прокси-сервер существующего MCP-сервера

Используйте этот путь, если у вас уже запущен соответствующий стандартам MCP-сервер , и вы хотите предоставить к нему доступ через APIM для управления и привлечения разработчиков. APIM не генерирует здесь инструменты; он обнаруживает инструменты вышестоящего сервера и перенаправляет методы MCP (например, initialize, tools/list, tools/call).

В издательском портале вы сможете:

  • Укажите основные сведения (имя, контекст, версия) и конечную точку MCP .

  • Настройте параметры исходящего трафика и любые политики APIM (аутентификация, ограничение скорости, аналитика).

  • Опубликуйте это, чтобы сделать инструменты MCP, работающие через прокси-сервер, доступными для потребителей через APIM.

  • Перейдите на портал издателя.

    • Перейдите в раздел «Серверы MCP» на портале издателя.

    • Если у вас уже есть серверы MCP, нажмите кнопку «Создать сервер MCP» . 

- Если это ваш первый сервер MCP, вы увидите страницу "Начнём!".


- В меню навигации нажмите **«Проксировать существующий сервер MCP»** → **«Проксировать существующий сервер MCP»** .

  1. Дайте определение.

    • Выберите URL-адрес сервера MCP и введите: https://db720294-98fd-40f4-85a1-cc6a3b65bc9a-prod.e1-us-east-azure.choreoapis.dev/godzilla/mcp-everything-server/v1.0

  2. Выберите инструменты для импорта

    • Выберите инструменты, которые будут доступны через сервер MCP в APIM. Нажмите «Далее» .

  1. Введите данные сервера MCP.

Заполните поля ниже и нажмите «Создать» .

Примечание

В поле Endpoint должен быть указан базовый URL-адрес бэкенда, к которому ваши инструменты будут обращаться во время выполнения, а не URL-адрес документа OpenAPI.

Поле Пример значения
Имя EverythingMCP
Контекст /все
Версия 1.0.0
Конечная точка https://db720294-98fd-40f4-85a1-cc6a3b65bc9a-prod.e1-us-east-azure.choreoapis.dev/godzilla/mcp-everything-server/v1.0

Обновление инструментов и развертывание сервера MCP

После создания MCP-сервера на основе существующего API может потребоваться доработка сгенерированных инструментов, проверка их работы и развертывание в соответствующей среде. Это гарантирует их интуитивно понятный интерфейс для пользователей и корректную работу перед публикацией.

1. Изменение или добавление инструментов

После создания сервера MCP в разделе «Инструменты» вы можете настроить существующие инструменты или добавить новые.

Переход к разделу «Инструменты»

  1. В левом навигационном меню перейдите в раздел «Конфигурации API» → «Инструменты» . В этом разделе отображаются все инструменты, автоматически сгенерированные из ресурсов API.

Редактирование существующих инструментов

  • Переименуйте инструмент . Используйте короткие, понятные и описательные названия, отражающие его назначение. Это поможет пользователям быстро найти нужный инструмент, если доступно несколько вариантов.

  • Отредактируйте описание. Добавьте четкие пояснения к контексту. Описания должны:

  • Объясните , что делает этот инструмент .

  • Предоставьте подсказки по правильному использованию (например, «Используйте этот инструмент для получения списка активных заказов, отфильтрованных по дате»).

  • Укажите любые важные ограничения или ожидаемые форматы входных данных.

Добавление новых инструментов

  1. Нажмите «Добавить новый инструмент» .

  2. Заполните обязательные поля:

  3. Операция – Выберите ресурс API (в сценарии MCP Server Proxy это становится ИНСТРУМЕНТОМ), на основе которого будет создан инструмент (например, конкретная конечная точка GET или POST).

  4. Описание – Предоставьте достаточно контекста, чтобы магистранты могли понять возможности инструмента.

  5. Название инструмента — должно быть уникальным и в идеале соответствовать единой системе именования.

  6. Сохраните изменения.

Передовые методы

  • Избегайте слишком общих названий инструментов, таких как «GetData» .

  • Описания должны быть краткими, но информативными.

  • Группируйте связанные инструменты с использованием согласованных префиксов (например, orders_list, orders_create, orders_cancel).

Примечание

Переименование инструментов и улучшение их описаний значительно повышают доступность и удобство использования клиентских приложений и программ магистратуры.

2. Развертывание сервера MCP

Прежде чем вы сможете протестировать или использовать свой MCP-сервер, его необходимо развернуть на конкретном шлюзе.

Этапы развертывания

  1. В левом меню перейдите в раздел Развертывание → Развертывания .

  2. Выберите шлюз , на котором вы хотите развернуть сервер MCP. Совет: выберите шлюз, расположенный ближе всего к вашей целевой аудитории, чтобы уменьшить задержку.

  3. Нажмите «Развернуть» .

  4. Дождитесь сообщения с подтверждением развертывания.

Советы по развертыванию

  • Убедитесь, что среда Gateway (разработка, тестирование, производство) соответствует вашему плану тестирования.

  • Если вы используете несколько сред, сначала проведите тестирование в более слабой среде.

  • Просматривайте журналы развертывания на наличие ошибок или предупреждений.

3. Тестирование с помощью MCP Playground

В разделе MCP Playground на портале издателя вы можете тестировать инструменты, не публикуя их.

Этапы тестирования

  1. В левом меню перейдите в раздел Тест → MCP Playground .

  2. Нажмите «Подключиться» , чтобы установить соединение с сервером MCP.

  3. Взаимодействуйте с доступными инструментами:

    • Приведите примеры входных данных.

    • Проверьте, соответствует ли результат ожиданиям.

    • Убедитесь, что описания помогают правильно использовать материал.

  1. Отметьте все выявленные проблемы и при необходимости обновите конфигурацию инструмента.

Почему это важно

Тестирование на этом этапе гарантирует, что инструменты будут работать должным образом, прежде чем они станут доступны внешним пользователям. Этот шаг может предотвратить ошибки интеграции и путаницу среди пользователей.

4. Публикация сервера MCP

После тестирования и проверки сервера MCP и его инструментов вы можете опубликовать его, чтобы сделать доступным на портале разработчиков.

Этапы публикации

  1. В левом меню перейдите в раздел «Опубликовать» → «Жизненный цикл» .

  2. Проверьте сведения о сервере MCP, чтобы убедиться в следующем:

  3. Названия и описания инструментов окончательно утверждены.

  4. Все необходимые развертывания активны.

  5. Нажмите «Опубликовать» .

Вопросы публикации

  • Опубликованные серверы MCP становятся доступными для разработчиков приложений.

  • Публикуйте только тогда, когда вы уверены как в функциональности, так и в документации.

  • После публикации рекомендуется добавить примеры использования API на портал для разработчиков для повышения уровня внедрения.

Подпишитесь на сервер MCP

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

В приведенных здесь примерах используется Petstore сервер MCP, который создается и публикуется на портале разработчиков в NEOMSA APIM .

Подписаться на приложение

Если у вас уже есть приложение, следуйте инструкциям ниже, чтобы подписаться на сервер MCP с помощью этого приложения.

  1. Войдите в портал разработчика ( https://<hostname>:<port>/devportal) и щелкните по MCP-серверу (например, Petstore), чтобы перейти к обзору MCP-сервера.

  1. Нажмите ПОДПИСАТЬСЯ НА ПРИЛОЖЕНИЕ.

  1. Выберите приложение, политику регулирования и нажмите «Подписаться».

Список подписок можно посмотреть в разделе «Подписки».

Если у вас нет существующего приложения, вы можете создать его, а затем подписаться на сервер MCP. Подробные инструкции см. в разделе «Подписка на API» , поскольку процесс аналогичен.

Используйте серверы MCP из MCP Hub

NEOMSA APIM может выступать в качестве MCP Hub, обеспечивая централизованное обнаружение, управление и повторное использование серверов MCP в разных командах и средах. При работе в режиме MCP Hub портал разработчиков API Manager работает исключительно с серверами MCP — в этом режиме API недоступны.

Настройте портал разработчиков APIM в качестве центра MCP

Для настройки портала разработчика на работу только в режиме MCP добавьте или обновите файлы deployment.toml и перезапустите сервер:

[apim.devportal]

Other existing configurations

mode = "MCP_ONLY"

Важно:

В зависимости от ваших потребностей вы можете запускать портал разработчиков API Manager в различных режимах:

  • MCP_ONLY — работает только с серверами MCP (чистый MCP Hub).

  • ГИБРИДНЫЙ — поддержка как API, так и MCP-серверов.

  • API_ONLY — работать только с API.

Протестируйте серверы MCP, используя интегрированную среду тестирования MCP Playground

Интегрированная среда разработки MCP Playground — это визуальный интерфейс тестирования на портале разработчика, позволяющий изучать схему сервера MCP и напрямую вызывать его инструменты.

Следуйте приведенным ниже инструкциям, чтобы использовать MCP Playground для тестирования сервера MCP:

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

  • Для подключения приложения к серверу MCP необходимо выполнить соответствующую подписку. Дополнительную информацию см. в разделе «Подписка на сервер MCP» .

  • Получите токен доступа для приложения. Вы можете использовать конечную точку токена для получения JWT-токена. Для получения дополнительной информации см. раздел « Генерация токена доступа» .

В приведенных здесь примерах используется Petstore сервер MCP, созданный в разделе « Создание сервера MCP из определения OpenAPI» .

  1. Войдите в портал разработчиков APIM ( https://<hostname>:9443/devportal).

  2. Нажмите «Серверы MCP» и выберите сервер MCP, который вам нужно вызвать.

  3. В разделе «Обзор сервера MCP» нажмите «Протестировать» и перейдите в меню «Тест» → «Игровая площадка MCP».

Появляется пользовательский интерфейс MCP Playground для тестирования сервера Petstore MCP.

  1. Введите скопированный токен доступа в поле «Токен» или нажмите Configuration кнопку на панели MCP Playground, и если тестовый ключ не отображается, нажмите кнопку «ПОЛУЧИТЬ ТЕСТОВЫЙ КЛЮЧ» .

  1. Нажмите «Подключиться» , чтобы установить соединение с развернутым сервером MCP.

После подключения вы можете нажать кнопку «Список инструментов» , чтобы увидеть доступные инструменты сервера MCP. При необходимости вы можете выбрать и вызвать отдельные инструменты, указав необходимые параметры.

  1. Разверните метод и введите значения для тестирования. Нажмите кнопку «Выполнить», чтобы запустить инструмент.

Обратите внимание на успешный ответ на вызов инструмента.

Вы успешно запустили инструмент MCP Server с помощью MCP Playground.