팁
권장: 지원되는 프로 코드 선언적 에이전트 및 플러그인 시나리오에 대한 Work IQ Dev 도구 로 시작하십시오. WIQD 빠른 시작을 참조하세요. 도구 키트 기반 지침은 이를 필요로 하는 기존 프로젝트 및 워크플로에 계속 사용할 수 있습니다. 도구를 선택하기 전에 기능 및 대상 환경 지원을 확인하세요. WIQD는 사용자 지정 엔진 에이전트를 대상으로 하지 않습니다.
MCP 앱은 MCP(모델 컨텍스트 프로토콜) 서버에서 제공하는 Microsoft 365 Copilot 내에서 실행되는 대화형 UI 위젯입니다. 이를 통해 선언적 에이전트는 텍스트 응답을 넘어 Copilot 채팅에서 직접 풍부하고 실행 가능한 환경을 제공할 수 있습니다. 도구가 대화형 UI를 반환하는 MCP 서버 기반 플러그인 을 추가하여 선언적 에이전트에 MCP 앱을 추가할 수 있습니다. Microsoft 365 Copilot은 다음 메서드를 사용하여 만든 UI 위젯을 지원합니다.
- MCP 앱 - MCP 서버가 호스트에 대화형 사용자 인터페이스를 제공할 수 있도록 하는 MCP의 확장입니다.
- OpenAI Apps SDK - 추가 ChatGPT 기능이 있는 MCP 앱 표준을 기반으로 ChatGPT 앱을 빌드하는 도구입니다.
예를 들어 MCP 서버 플러그 인은 GitHub의 Microsoft 365 Copilot용 MCP 기반 대화형 UI 샘플을 참조하세요.
지원되는 MCP 앱 또는 OpenAI 앱 SDK 기능에 대한 자세한 내용은 Copilot에서 지원되는 MCP 앱 기능을 참조하세요.
MCP 앱의 필수 구성 요소
- Copilot 확장성 옵션 요구 사항에 지정된 요구 사항
- UI 위젯을 제공하거나 UI 위젯을 구현하도록 수정할 수 있는 원격 MCP 서버
- MCP Inspector와 같은 MCP 서버 응답을 보는 도구입니다.
- Visual Studio Code
- Microsoft 365 Agents Toolkit (버전 6.12.0 이상)
MCP 앱에 대한 MCP 서버 요구 사항
- 인증 - Copilot은 OAuth 2.1 및 Microsoft Entra SSO(Single Sign-On)를 지원합니다. 개발 목적을 위해 Copilot은 에이전트 도구 키트의 없음 옵션을 사용하여 익명 인증을 지원합니다. 인증에 대한 자세한 내용은 에이전트에서 API 플러그인에 대한 인증 구성을 참조하세요.
-
허용되는 URL - MCP 서버와 ID 공급자 모두 다음 URL을 허용해야 합니다.
- CORS용 위젯 호스트 URL - Copilot은 다음 URL
{hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com을 사용하여 MCP 서버별 호스트 아래에 위젯 UI를 렌더링합니다. 여기서{hashed-mcp-domain}는 MCP 서버 도메인의 SHA-256 해시입니다. 위젯 호스트 URL 생성기를 사용하여 MCP 서버 URL을 기반으로 호스트 URL을 생성할 수 있습니다. - OAuth 2.1 리디렉션 URI:
-
https://teams.microsoft.com/api/platform/v1.0/oAuthRedirectfor Copilot -
https://vscode.dev/redirect에이전트 도구 키트를 사용하여 도구를 가져오는 Visual Studio Code용
-
- Microsoft Entra SSO 리디렉션 URI:
-
https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirectfor Copilot - Visual Studio Code는 현재 도구 가져오기에 대한 SSO를 지원하지 않습니다
-
- CORS용 위젯 호스트 URL - Copilot은 다음 URL
- UI 위젯 - MCP 앱 또는 OpenAI 앱 SDK 요구 사항에 따라 UI 위젯을 구현합니다.
Copilot의 MCP 앱 모범 사례
사용자 환경 디자인
UX 디자인 모범 사례에 대한 자세한 내용은 Microsoft 365 Copilot용 선언적 에이전트의 MCP 앱에 대한 사용자 환경 지침을 참조하세요.
API 가용성 확인
일부 window.openai.* API를 모든 플랫폼이나 호스트에서 사용할 수 있는 것은 아닙니다. 지원되지 않는 API는 undefined. 항상 API 가용성을 검사하고 API를 사용할 수 없는 경우 대체를 제공합니다.
예제
이 간단한 패턴은 API를 호출하기 전에 확인하여 런타임 오류를 방지합니다.
if (window.openai.callTool) {
const result = await window.openai.callTool({ name: 'myTool', params: {} });
} else {
// Handle unsupported case — show fallback UI, skip the feature, etc.
}
이 예제에서 전체 화면 모드로 전환하는 버튼은 호스트가 API를 지원하는 경우에만 렌더링됩니다.requestDisplayMode
function FullScreenButton() {
// Don't render the button if the host doesn't support it
if (!window.openai.requestDisplayMode) {
return null;
}
return (
<button onClick={() => window.openai.requestDisplayMode({ mode: 'fullscreen' })}>
Enter Fullscreen
</button>
);
}
또는 위젯이 시작 시 사용하는 모든 API의 가용성을 검사하고 그에 따라 기능을 사용하거나 사용하지 않도록 설정할 수 있습니다.
interface PlatformCapabilities {
canCallTools: boolean;
canChangeDisplayMode: boolean;
canSendMessages: boolean;
}
function detectCapabilities(): PlatformCapabilities {
return {
canCallTools: !!window.openai.callTool,
canChangeDisplayMode: !!window.openai.requestDisplayMode,
canSendMessages: !!window.openai.sendMessage,
};
}
// Use at widget startup
const capabilities = detectCapabilities();
if (!capabilities.canCallTools) {
// Show a reduced-functionality experience
}
에이전트 만들기 및 사이드로드
MCP 서버에서 선언적 에이전트를 생성하고, 인증을 구성하고, 사이드로드하는 것은 서버가 UI 위젯을 반환하는지 여부에 관계없이 동일합니다. 전체 안내는 MCP 서버에서 선언적 에이전트용 플러그 인 빌드를 참조하세요.
연습을 수행할 때 다음 MCP 앱 고려 사항을 염두에 두세요.
- MCP 서버는 MCP 앱 또는 OpenAI 앱 SDK 요구 사항에 따라 UI 위젯을 반환해야 합니다. MCP 앱에 대한 MCP 서버 요구 사항을 참조하세요.
- 기본적으로 에이전트는 동적 도구 검색 을 사용하고 런타임에 UI 위젯을 반환하는 도구를 포함하여 서버의 도구를 확인하므로 수동으로 도구를 추가할 필요가 없습니다. 대신 고정된 도구 집합을 고정하는 경우 UI 위젯을 반환하는 도구를 하나 이상 포함해야 합니다.
- MCP 서버가 아직 개발 중이고 인증을 구현하지 않는 경우 인증 유형으로 없음 을 선택합니다. 프로덕션 환경에 배포하기 전에 인증을 추가합니다.
에이전트 테스트
- 브라우저를 열고 다음으로 이동합니다.https://m365.cloud.microsoft/chat
- 왼쪽 사이드바에서 에이전트를 선택합니다. 에이전트가 보이지 않으면 모든 에이전트를 선택합니다.
- 에이전트에게 MCP 서버를 호출하는 작업을 수행하도록 요청합니다.
- 메시지가 표시되면 에이전트가 MCP 서버에 연결할 수 있도록 허용합니다.
- 에이전트가 UI 위젯을 렌더링하는지 확인합니다.
위젯이 예상대로 나타나지 않거나 동작하지 않으면 Microsoft 365 Copilot에서 MCP 앱 문제 해결을 참조하세요.
Copilot에서 지원되는 MCP 앱 기능
Microsoft 365 Copilot은 다음 기능을 지원합니다.
구성 요소 브리지
| OpenAI 앱 SDK | MCP 앱 동가 | 지원 여부 |
|---|---|---|
window.openai.toolInput |
app.ontoolinput |
✅ |
window.openai.toolOutput |
app.ontoolresult |
✅ |
window.openai.toolResponseMetadata |
app.ontoolresult → params._meta |
✅ |
window.openai.widgetState |
— | ✅ |
window.openai.setWidgetState(state) |
직접 사용할 수 없습니다. 다음을 포함한 대체 메커니즘을 사용합니다. app.updateModelContext() |
✅ |
window.openai.callTool(name, args) |
app.callServerTool({ name, arguments }) |
✅ |
window.openai.sendFollowUpMessage({ prompt }) |
app.sendMessage({ ... }) |
✅ |
window.openai.uploadFile(file) |
— | ❌ |
window.openai.getFileDownloadUrl({ fileId }) |
— | ❌ |
window.openai.requestDisplayMode(...) |
app.requestDisplayMode({ mode }) |
✅ (전체 화면 전용) |
window.openai.requestModal(...) |
— | ❌ |
window.openai.notifyIntrinsicHeight(...) |
app.sendSizeChanged({ width, height }) |
✅ |
window.openai.openExternal({ href }) |
app.openLink({ url }) |
✅ |
window.openai.setOpenInAppUrl({ href }) |
— | ✅ |
window.openai.theme |
app.getHostContext()?.theme |
✅ |
window.openai.displayMode |
app.getHostContext()?.displayMode |
✅ |
window.openai.maxHeight |
app.getHostContext()?.viewport?.maxHeight |
✅ |
window.openai.safeArea |
app.getHostContext()?.safeAreaInsets |
✅ |
window.openai.view |
— | ✅ |
window.openai.userAgent |
app.getHostContext()?.userAgent |
✅ |
window.openai.locale |
app.getHostContext()?.locale |
✅ |
| — | app.ontoolinputpartial |
❌ |
| — | app.ontoolcancelled |
❌ |
| — | app.getHostContext()?.availableDisplayModes |
❌ |
| — | app.getHostContext()?.toolInfo |
❌ |
| — | app.onhostcontextchanged |
❌ |
| — | app.onteardown |
❌ |
| — | app.sendLog({ level, data }) |
❌ |
| — | app.getHostVersion() |
❌ |
| — | app.getHostCapabilities() |
✅ |
도구 설명자 _meta 필드
| OpenAI 앱 SDK | MCP 앱 동가 | 지원 여부 |
|---|---|---|
_meta["openai/outputTemplate"] |
_meta.ui.resourceUri |
✅ |
_meta["openai/widgetAccessible"] |
_meta.ui.visibility (문자열[]) |
❌ |
_meta["openai/visibility"] |
_meta.ui.visibility (문자열[]) |
✅ |
_meta["openai/toolInvocation/invoking"] |
— | ❌ |
_meta["openai/toolInvocation/invoked"] |
— | ❌ |
_meta["openai/fileParams"] |
— | ❌ |
_meta["securitySchemes"] |
— | ❌ |
도구 설명자 주석
| OpenAI 앱 SDK | MCP 앱 동가 | 지원 여부 |
|---|---|---|
readOnlyHint |
readOnlyHint |
✅ |
destructiveHint |
destructiveHint |
❌ |
openWorldHint |
openWorldHint |
❌ |
idempotentHint |
idempotentHint |
❌ |
구성 요소 리소스 _meta 필드
| OpenAI 앱 SDK | MCP 앱 동가 | 지원 여부 |
|---|---|---|
_meta["openai/widgetDescription"] |
— | ❌ |
_meta["openai/widgetPrefersBorder"] |
_meta.ui.prefersBorder |
❌ |
_meta["openai/widgetCSP"] |
_meta.ui.csp |
✅ |
_meta["openai/widgetDomain"] |
_meta.ui.domain |
❌ |
| — | _meta.ui.permissions |
❌ |
CSP 개체의 속성
| OpenAI 앱 SDK | MCP 앱 동가 | 지원 여부 |
|---|---|---|
connect_domains |
connectDomains |
✅ |
resource_domains |
resourceDomains |
✅ |
frame_domains |
frameDomains |
❌ |
redirect_domains |
— | ❌ |
| — | baseUriDomains |
❌ |
호스트 제공 도구 결과 _meta 필드
| OpenAI 앱 SDK | MCP 앱 동가 | 지원 여부 |
|---|---|---|
_meta["openai/widgetSessionId"] |
— | ❌ |
클라이언트 제공 _meta 필드
| OpenAI 앱 SDK | MCP 앱 동가 | 지원 여부 |
|---|---|---|
_meta["openai/locale"] |
_meta["openai/locale"] |
✅ |
_meta["openai/userAgent"] |
_meta["openai/userAgent"] |
✅ |
_meta["openai/userLocation"] |
_meta["openai/userLocation"] |
✅ |
_meta["openai/subject"] |
— | ❌ |
Copilot의 MCP 앱에 대한 질문과 대답
MCP 앱이란?
MCP 앱은 Microsoft 365 Copilot 내에서 직접 렌더링하는 MCP 서버에서 제공하는 대화형 UI 위젯입니다. 선언적 에이전트를 텍스트 전용 응답을 넘어 확장하여 데이터 시각화, 양식 및 작업 관리 인터페이스와 같은 풍부한 환경을 가능하게 합니다.
MCP Apps와 OpenAI Apps SDK의 차이점은 무엇입니까?
MCP Apps 는 MCP 서버가 호환되는 모든 호스트에 대화형 UI를 제공할 수 있도록 하는 MCP 표준에 대한 공개 확장입니다. OpenAI 앱 SDK는 MCP 앱 표준을 기반으로 하며 ChatGPT와 관련된 추가 기능을 추가합니다. Microsoft 365 Copilot은 모든 기능을 사용할 수 있는 것은 아니지만 두 가지를 모두 지원합니다. 자세한 내용은 Copilot에서 지원되는 MCP 앱 기능을 참조하세요.
개발 중에 인증 없이 MCP 앱을 사용할 수 있나요?
예. 개발 목적을 위해 익명 인증이 지원됩니다. 그러나 프로덕션 환경에 배포하기 전에 인증을 추가해야 합니다. OAuth 2.1 및 Microsoft Entra SSO(Single Sign-On)는 지원되는 인증 방법입니다. 자세한 내용은 에이전트에서 API 플러그인에 대한 인증 구성을 참조하세요.