Устранение неполадок с приложениями MCP в Microsoft 365 Copilot

В этом руководстве содержатся советы по устранению распространенных проблем, которые могут возникнуть при разработке приложения Model Context Protocol (MCP) для интеграции с декларативным агентом внутри Microsoft 365 Copilot.

Включить режим разработчика

Включение режима разработчика отображает журналы и ошибки в ответах агента. Эти сведения необходимы для отладки. Чтобы включить режим разработчика, введите следующую команду в Microsoft Copilot.

-developer on

Средства MCP, доступные вашему агенту, отображаются в разделе "Действия" на карте сведений об отладке. Подробности об карте сведений об отладке см. в статье "Использование режима разработчика в Microsoft 365 Copilot для тестирования и отладки агентов".

Проблемы обнаружения и входа

Инструменты не указаны

Если в разделе «Действия» карты сведений об отладке отсутствуют инструменты MCP, проведите проверку указанные ниже элементы.

  • Убедитесь, что сервер MCP работает и вы подключаетесь к правильной конечной точке MCP в манифесте подключаемого модуля.
  • Убедитесь, что проверка подлинности прошла успешно. Многие серверы MCP не возвращают инструменты, пока пользователь не выполнит вход в систему, поэтому сбой или пропуск входа в систему может привести к пустому списку инструментов.

Динамическое обнаружение инструментов

Если агент использует динамическое обнаружение средств (по умолчанию), средства разрешаются с сервера во время выполнения. Проверьте следующее.

  • Среда RemoteMCPServer выполнения задает run_for_functions значение и ["*"] массив верхнего уровня functions пуст.
  • Метод сервера tools/list возвращает инструменты. Вы можете проверить ответ с помощью такого инструмента, как MCP Inspector.
  • Недавно обнаруженное или измененное средство не скрывается при проверке во время выполнения. Проверьте сведения об отладке на наличие ошибок проверки.
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp"
    },
    "run_for_functions": [
      "*"
    ]
  }
]

Закрепленные инструменты

Если вы закрепили фиксированный набор инструментов, убедитесь, что среда выполнения сервера MCP, указанная runtimes в свойстве в манифесте подключаемого модуля:

  • Включает ожидаемые средства в свойстве верхнего уровня functions .
  • Ссылается на средства в свойстве mcp_tool_description одним из следующих способов:
    • Ссылка на файл JSON, который содержит описания инструментов в свойстве fileИЛИ
    • Перечисление описаний инструментов в свойстве tools
  • Включает имена инструментов в свойство run_for_functions .
"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "https://api.contoso.com/mcp",
      "mcp_tool_description": {
        "file": "mcp-tools.json"
      }
    },
    "run_for_functions": [
      "get_widget",
      "create_widget"
    ]
  }
]

Инструменты не запускаются из чата Copilot

  • Пересмотрите описания инструментов и параметров, чтобы убедиться, что они предоставляют достаточный контекст. Попробуйте переписать их с помощью фразы "Использовать эту функцию/параметр, если...". формулировки.
  • Длина описания не должна превышать 1024 символа. Текст более 1024 символов игнорируется.
  • Убедитесь, что видимость инструмента настроена правильно.
    • Для приложений _meta.ui.visibility MCP в число model
    • Для приложений meta["openai/visibility"] OpenAI SDK установлено значение public.

Выбран не тот инструмент

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

Проблемы с мини-приложением

Мини-приложение не отображается

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

  • Для приложений MCP определение инструмента включает _meta.ui.resourceUri в себя задание в зарегистрированный HTML-ресурс с типом text/html;profile=mcp-appMIME.
  • Для приложений OpenAI SDK определение инструмента включает в себя _meta["openai/outputTemplate"] задан зарегистрированный HTML-ресурс с типом text/html+skybridgeMIME .

Мини-приложение не загружается

  • Откройте средства разработчика браузера и проверка на наличие нарушений политики безопасности содержимого (CSP) в консоли. Убедитесь, что запросы с URL-адреса узла мини-приложения разрешены. Дополнительные сведения см. в разделе Требования к серверу MCP для приложений MCP.
  • Убедитесь, что мини-приложение компилирует все зависимости HTML и JavaScript в один файл без внешних неразрешенных ресурсов.

Мини-приложение загружается без данных

  • Проверьте структуру отклика средства.
    • content должна содержать только данные (модель).
    • structuredContent должен содержать как данные, так и мини-приложение.
    • _meta должен содержать только мини-приложение.
  • Найдите structuredContent или _meta включите необходимые данные.

Мини-приложение имеет двойную полосу прокрутки

В контейнере узла Copilot уже есть прокрутка с максимальной высотой. Отключите внутреннюю прокрутку в мини-приложении, задав overflow: hidden стили контейнеров.

Теги <a> привязки не работают для внешних ссылок в Copilot. Вместо этого используйте подходящие API платформы.

  • Для приложений MCP используйте app.openLink.
  • Для приложений OpenAI SDK используйте window.openai.openExternal.

Полноэкранный режим не работает в некоторых узлах Copilot

Полноэкранный режим поддерживается не на всех узлах Copilot. Рекомендуется всегда выполнять проверку возможностей узла и условно отображать элементы пользовательского интерфейса (например, кнопку "Во весь экран"). Дополнительные сведения см. в статье Проверка доступности API.

Проблемы с реагированием

Проблемы со сроком действия результатов средства

Убедитесь, что отклики инструментов отправлены content или structuredContent не имеют слишком большого размера. Если мини-приложению требуются расширенные метаданные, которые не полезны для модели, такие как URL-адреса аватаров или детали, относящиеся к пользовательскому интерфейсу, включите полные данные и _meta предоставьте краткую сводку в content. Такой подход гарантирует, что модель сохраняет ключевую информацию и поддерживает эффективное многооборотное взаимодействие.

Дублирование данных в мини-приложении и текстовом резюме

Эту проблему можно решить одним из следующих способов:

  • Оптимизация разделения данных: используйте _meta для данных, относящихся к мини-приложениям, и content для сводок, видимых для модели.
  • Управление форматированием: используйте инструкции в манифесте декларативного агента, чтобы управлять структурой и представлением ответов.

Проблемы с проверкой подлинности

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