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

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

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

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

-developer on

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

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

Нет средств в списке

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

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

Средства, не запускающиеся из чата Copilot

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

Выбран неправильный инструмент

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

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

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

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

  • Для приложений MCP определение средства включает в себя _meta.ui.resourceUri зарегистрированный ресурс HTML с типом text/html;profile=mcp-appMIME .
  • Для приложений пакета SDK OpenAI определение средства включает в себя _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.
  • Для приложений пакета SDK OpenAI используйте window.openai.openExternal.

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

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

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

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

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

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

Устраните эту проблему, используя один из следующих вариантов:

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

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

Несоответствие идентификатора приложения между конфигурацией проверки подлинности и подключаемым модулем

Если в сведениях об отладке отображаются ошибки, карта примерно так:

OAuth authentication failed: The App ID used in the request does not match the App ID in the authentication configuration. (HTTP 404)

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

Базовый URL-адрес в конфигурации проверки подлинности не соответствует подключаемого модуля

Если в сведениях об отладке отображаются ошибки, карта примерно так:

OAuth authentication failed: The base URL in your authentication configuration does not match the server URL. (HTTP 401)

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

Идентификатор ссылки в манифесте подключаемого модуля неверен или отсутствует

Если в сведениях об отладке отображаются ошибки, карта примерно так:

OAuth authentication failed: No matching configuration found for referenceID in 'runtime.auth' section of the action manifest

Перейдите на портал разработчика Teams. Найдите клиент OAuth или клиент единого входа и убедитесь, что идентификатор в среде выполнения auth.reference_id сервера MCP соответствует идентификатору регистрации на портале разработчика.

Политика организации ограничивает доступ

Если в сведениях об отладке отображаются ошибки, карта примерно так:

OAuth authentication failed: Access is restricted by your organization's policy. (HTTP 404)

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

Кнопка входа неактивна или отображает общую ошибку

Если кнопка входа неактивна или отключена или ее нажатие выдает общую ошибку "Запрос не может быть обработан", это условие может указывать на временные проблемы с проверкой подлинности или сеансом. Повторите запрос. Если проблема не исчезнет, переустановите приложение или обратитесь к администраторам организации.

Не удается открыть всплывающее окно входа

Включите всплывающие окна для сайта в параметрах браузера и повторите попытку.

Всплывающее окно входа открывается, но зависает или никогда не закрывается

Если откроется всплывающее окно входа и пользователь завершает проверку подлинности, но всплывающее окно никогда не закрывается и Copilot не получает результат проверки подлинности, ссылка на всплывающее окно, скорее всего, была уничтожена window.opener во время цепочки перенаправления OAuth. Без window.openerэтого всплывающее окно не может передать результат проверки подлинности обратно в Copilot. Распространенный симптом заключается в том, что вход в систему в первый раз завершается сбоем, но при повторных попытках успешно выполняется, так как кэшированные учетные данные пропускают страницу, которая уничтожила window.opener.

Проверьте следующие элементы в цепочке перенаправления OAuth.

  • JavaScript, присвоив window.openerзначение NULL: некоторые страницы входа задаются window.opener = null в качестве комплексной меры безопасности для обратного табнаббинга. Если какая-либо страница в цепочке перенаправления проверки подлинности запускает этот код, всплывающее окно теряет подключение к Copilot. Область защиты табуляции только для навигации, инициированной пользователем, и не очищается window.opener во время перенаправлений во всплывающем окне.
  • Cross-Origin-Opener-Policy заголовок имеет значение same-origin. Если любая страница в цепочке перенаправления служит заголовком Cross-Origin-Opener-Policy: same-origin ответа, браузер окончательно отключает ссылку window.opener на навигацию между источниками. Убедитесь, что все страницы в цепочке перенаправления OAuth либо опускают Cross-Origin-Opener-Policy заголовок (который по умолчанию используется как unsafe-none), либо явно задайте для него значение unsafe-none.
  • Ссылки с помощью rel="noopener": привязка тегов с rel="noopener" полосой window.opener с целевой страницы. Не используйте rel="noopener" для навигации во всплывающем окне проверки подлинности.

Чтобы отладить эту проблему, откройте средства разработчика браузера во всплывающем окне и введите window.opener в консоли на каждом шаге цепочки перенаправления. Если window.opener возвращается null до окончательного перенаправления, определите, на какой странице оно было очищено. Вы также можете проверка заголовки ответов вкладки Сеть для Cross-Origin-Opener-Policy значений на каждой странице в цепочке.

Ошибка неверных учетных данных

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

URL-адрес входа не найден

Удалите и переустановите приложение, а затем повторите попытку входа.

Внутренняя ошибка сервера во время проверки подлинности

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

Если появится диалоговое окно согласия с запросом разрешений или бизнес-обоснованием, просмотрите запрошенные разрешения и при необходимости предоставьте бизнес-обоснование. Если вы не уверены или если диалоговое окно согласия запрашивает разрешения, для которых требуется согласие администратора, обратитесь к администраторам вашей организации.

Связанные материалы

  • Last updated on