Microsoft 365 Copilot에서 MCP 앱 문제 해결

이 가이드에서는 Microsoft 365 Copilot 내부의 선언적 에이전트와 통합하기 위해 MCP(모델 컨텍스트 프로토콜) 앱을 개발할 때 발생할 수 있는 일반적인 문제에 대한 문제 해결 지침을 제공합니다.

개발자 모드 사용

개발자 모드를 사용하도록 설정하면 에이전트 응답에 로그 및 오류가 표시됩니다. 이 정보는 디버깅에 필수적입니다. 개발자 모드를 사용하도록 설정하려면 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": [
      "*"
    ]
  }
]

고정된 도구

고정된 도구 집합을 고정한 경우 플러그인 매니페스트의 속성에 runtimes 지정된 MCP 서버 런타임이 있는지 확인합니다.

  • 최상위 functions 속성에 필요한 도구를 포함합니다.
  • 다음 중 하나를 통해 속성의 mcp_tool_description 도구를 참조합니다.
    • 속성에 file 도구 설명이 포함된 JSON 파일 참조 또는
    • 속성에 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 채팅에서 트리거되지 않음

  • 도구 및 매개 변수 설명을 다시 확인하여 충분한 컨텍스트를 제공하는지 확인합니다. "이 함수/매개 변수를 사용할 때..."를 사용하여 다시 작성하는 것이 좋습니다. 문구.
  • 설명은 1,024자 미만으로 유지하세요. 1,024자를 초과하는 텍스트는 무시됩니다.
  • 도구 가시성이 올바르게 설정되었는지 확인합니다.
    • MCP 앱의 _meta.ui.visibility 경우 다음을 포함 model합니다.
    • OpenAI SDK 앱 meta["openai/visibility"] 의 경우 로 설정 public됩니다.

잘못된 도구가 선택되었습니다.

  • 이름이 비슷하거나 설명이 겹치는 도구를 사용하지 마세요.
  • 각 도구를 사용해야 하는 시기를 설명하는 명확한 차별화 요소를 설명합니다.

위젯 문제

위젯이 렌더링되지 않음

올바른 MCP 도구가 호출되었지만 UI 위젯이 응답에서 렌더링되지 않는 경우 MCP 서버는 UI 구성 요소 없이 구조화된 콘텐츠만 반환할 수 있습니다. UI 바인딩이 올바르게 구성되었는지 확인합니다.

  • MCP 앱의 경우 도구 정의는 MIME 유형text/html;profile=mcp-app으로 등록된 HTML 리소스로 설정된 것을 포함합니다_meta.ui.resourceUri.
  • OpenAI SDK 앱의 경우 도구 정의는 MIME 형식text/html+skybridge의 등록된 HTML 리소스로 설정되는 것을 포함합니다_meta["openai/outputTemplate"].

위젯을 로드하지 못함

  • 브라우저의 개발자 도구를 열고 콘솔에서 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 호스트에서 지원되지 않습니다. 항상 호스트 기능을 검사하고 조건부에 따라 UI 요소(예: 전체 화면 단추)를 표시하는 것이 좋습니다. 자세한 내용은 API 가용성 확인을 참조하세요.

응답 문제

도구 결과 만료 문제

도구 응답이 전송되거나 contentstructuredContent 너무 크지 않은지 확인합니다. 위젯에 아바타 URL 또는 UI별 세부 정보와 같이 모델에 유용하지 않은 풍부한 메타데이터가 필요한 경우 에 전체 데이터를 _meta 포함하고 에 간결한 요약을 제공합니다.content 이 접근 방식을 사용하면 모델이 주요 정보를 유지하면서 효과적인 다중 회전 환경을 지원할 수 있습니다.

위젯 및 텍스트 요약의 중복 데이터

다음 옵션 중 하나를 사용하여 이 문제를 해결합니다.

  • 데이터 분리 최적화: 위젯별 데이터 및 content 모델에 표시되는 요약에 사용합니다_meta.
  • 서식 조정: 선언적 에이전트 매니페스트의 지침을 사용하여 응답을 구성하고 표시하는 방법을 안내합니다.

인증 문제

로그인 실패, 토큰 오류, 동의 프롬프트 및 인증 구성 불일치와 같은 인증 문제는 MCP 및 API 플러그인 인증 문제 해결을 참조하세요.