Microsoft 365 Copilot 플러그인은 지원되는 Microsoft 환경을 원격 MCP(Model Context Protocol) 서버에서 제공하는 도구에 연결합니다. 플러그 인 패키지에는 연결 구성이 포함되어 있으며 서버는 별도로 실행됩니다.
WIQD(Work IQ Dev 도구)를 사용하여 플러그 인을 만들고, 유효성을 검사하고, 패키징합니다. Work IQ Dev 도구를 사용하여 플러그인 빌드로 시작하세요.
다음 섹션에서는 매니페스트를 수동으로 편집해야 하는 개발자를 위한 기본 구성에 대해 설명합니다. Microsoft 365 앱 매니페스트의 배열에 agentConnectors 플러그인의 원격 MCP 서버를 등록합니다. 이 스키마 식별자는 설치 가능한 패키지를 플러그인이라고 하더라도 유지됩니다 agentConnectors .
중요
이 구성은 선언적 에이전트 작업에 사용되는 MCP 플러그인 매니페스트가 아닌 Microsoft 365 앱 매니페스트를 사용합니다. 또한 에이전트 365 CLI 등록 경로와도 별개입니다. 이러한 대안은 MCP 서버 빌드 또는 재사용을 참조하세요. MCP에 대한 지원만으로는 이 등록 모델에 대한 지원을 설정할 수 없습니다.
필수 구성 요소
시작하기 전에 다음이 있는지 확인하세요.
- 를 통해
agentConnectors구성된 플러그 인을 지원하는 테스트 테넌트 및 대상 Microsoft 환경입니다. - 공개적으로 액세스할 수 있는 HTTPS 엔드포인트, TLS 1.2 이상 및 대상 환경에서 지원하는 전송이 있는 작업 MCP 서버.
- 대상 환경 및 선택한 권한 부여 유형에서 지원하는 매니페스트 버전이 포함된 Microsoft 365 앱 패키지입니다.
- 서버에서 익명 액세스를 허용하지 않는 한, OAuth 구성 또는 API 키 구성과 같은 서버에 등록된 권한 부여 구성입니다.
WIQD 서버 요구 사항 및 Copilot Cowork 도구 설명 요구 사항은 Work IQ Dev 도구를 참조하세요.
앱 매니페스트에 MCP 서버 추가
앱 매니페스트의 루트 수준에 있는 agentConnectors 배열에서 MCP 서버를 선언합니다.
- Microsoft 365 앱 패키지에서 앱 매니페스트를 엽니다.
- 루트 수준
agentConnectors배열을 찾거나 만듭니다. - 원격 MCP 서버를 식별하는 고유한
id, adisplayName, adescription및 atoolSource가 있는 항목을 추가합니다.
다음 JSON은 전체 앱 매니페스트가 아니라 기존 앱 매니페스트에 병합할 조각입니다.
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.30/MicrosoftTeams.schema.json",
"manifestVersion": "1.30",
"agentConnectors": [
{
"id": "my-mcp-server",
"displayName": "My Automation Server",
"description": "Provides workflow automation and task management tools.",
"toolSource": {
"remoteMcpServer": {
"mcpServerUrl": "https://mcp.example.com/mcp",
"authorization": {
"type": "OAuthPluginVault",
"referenceId": "my-oauth-config"
},
"mcpToolDescription": {
"file": "toolDescription.json"
}
}
}
}
]
}
엔드포인트 및 권한 부여 참조를 서버 값으로 바꿉니다. 각 항목 id 은 내에서 고유 agentConnectors해야 합니다. 기존 파일에 다른 필수 앱 매니페스트 속성을 유지합니다.
서버 엔드포인트 구성
toolSource.remoteMcpServer.mcpServerUrl을 HTTPS 끝점으로 설정합니다. 대상 환경에서 서버에 연결할 수 있고 MCP 초기화 및 후속 프로토콜 요청에 응답하는지 확인합니다.
인증 구성
다음 범위 내에서 agentConnectors[].toolSource.remoteMcpServer설정 authorization 다음 표에는 권한 부여 유형과 해당 구성이 나열되어 있습니다. 스키마 세부 정보는 권한 부여 스키마를 참조하세요.
| 권한 부여 유형 | 구성 |
|---|---|
None |
인증이 필요하지 않습니다. 서버에서 익명 액세스를 허용하는 경우에만 사용합니다. |
OAuthPluginVault |
OAuth 구성은 Microsoft 자격 증명 모음에 저장되고 ID에서 참조됩니다. |
ApiKeyPluginVault |
자격 증명 모음에 저장되고 ID에서 참조하는 API 키 구성입니다. |
DynamicClientRegistration |
ID에서 참조하는 동적 OAuth 클라이언트 등록 구성입니다. |
AzureKeyVault |
ID에서 참조하는 Azure Key Vault 구성입니다. 호스트 지원이 필요합니다. |
ConnectionVault (개발자 미리 보기) |
ID에서 참조하는 연결 구성입니다. |
스키마 값은 대상 환경에서의 지원을 보장하지 않습니다. 방법을 선택하기 전에 인증 요구 사항을 확인하세요.
referenceId 매니페스트와 별도로 획득한 구성을 식별합니다. API 키, 액세스 토큰, 클라이언트 암호 또는 비밀 값을 이 필드나 앱 매니페스트의 다른 곳에 넣지 마세요.
OAuth 인증 사용
Microsoft 자격 증명 모음에 저장된 OAuth 2.0 토큰의 경우 다음 개체를 사용합니다.authorization
{
"type": "OAuthPluginVault",
"referenceId": "my-oauth-config"
}
개발자 포털에서 OAuth 구성을 등록하고 반환된 구성 ID를 referenceId. 자세한 내용은 개발자 포털에서 OAuth 구성을 참조하세요.
OAuth 공급자 등록의 허용된 리디렉션 URI에 다음 콜백 URL을 추가합니다.
https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect
API 키 인증 사용
자격 증명 모음에 저장된 API 키의 경우 다음 개체를 사용합니다.authorization
{
"type": "ApiKeyPluginVault",
"referenceId": "my-apikey"
}
개발자 포털에서 키를 등록한 다음 반환된 등록 ID로 바꿉니다my-apikey. 자세한 내용은 API 키 인증을 참조하세요.
동적 클라이언트 등록 사용
동적 클라이언트 등록을 사용하면 호스트가 RFC 7591을 사용하여 MCP 서버에 OAuth 클라이언트로 등록할 수 있습니다. 둘 다 등록 흐름을 지원해야 합니다. Microsoft Entra ID는 RFC 7591 등록 엔드포인트를 제공하지 않습니다. Entra 보호 서버에 정적 OAuth 등록을 사용합니다.
다음 개체를 사용합니다.authorization
{
"type": "DynamicClientRegistration",
"referenceId": "my-dcr-config"
}
개발자 포털에서 구성을 등록하고 참조 ID로 바꿉니다my-dcr-config. 구성은 클라이언트 자격 증명을 협상할 때 호스트가 사용하는 권한 부여 값을 제공합니다.
서버는 다음과 같아야 합니다.
- RFC 7591 클라이언트 등록 엔드포인트를 노출합니다.
- 호스트의 OAuth 흐름에 필요한 클라이언트 등록 정보를 반환합니다.
- 수명이 긴 세션에 필요한 경우 토큰 새로 고침을 지원합니다.
Azure Key Vault 인증 사용
AzureKeyVault 앱 매니페스트 스키마 1.29 및 1.30에 포함되어 있습니다. 대상 환경에서 Azure Key Vault 통합 및 구성 참조를 획득하는 프로세스를 문서화하는 경우에만 사용합니다.
다음 개체를 사용합니다.authorization
{
"type": "AzureKeyVault",
"referenceId": "my-keyvault-config"
}
해당 통합의 자격 증명 스토리지 및 액세스 요구 사항을 따르고 반환된 참조로 바꿉니다 my-keyvault-config . 매니페스트 선언만으로는 비밀에 대한 액세스 권한이 부여되지 않습니다.
연결 자격 증명 모음 인증 사용
참고
연결 자격 증명 모음 인증은 개발자 미리 보기에서 사용할 수 있습니다. 개발자 미리 보기 앱 매니페스트 스키마를 사용하여 구성 ConnectionVault합니다. 일반적으로 사용 가능한 앱 매니페스트 스키마에서는 사용할 수 없습니다.
지원되는 연결-자격 증명 모음 통합의 경우 다음 개체를 사용합니다.authorization
{
"type": "ConnectionVault",
"referenceId": "shared_example"
}
대상 통합에서 제공하는 연결 참조로 바꿉니다 shared_example .
인증 사용 안 함
서버가 익명 액세스를 authorization.type 허용하는 경우 호스트에서 허용하는 경우 설정 None 하거나 생략합니다 authorization .
프로덕션 및 엔터프라이즈 시나리오에는 인증된 액세스를 선호하고, 지원되는 경우 API 키보다 OAuth를 선호합니다.
도구 검색 정의
도구 집합이 수정된 경우 패키지된 도구 정의를 사용하고, 앱 매니페스트 버전과 대상 호스트가 모두 지원하는 경우 동적 검색을 사용합니다.
정적 도구 정의 사용
앱 패키지에 도구 설명 파일을 포함하고 remoteMcpServer. 경로는 앱 패키지를 기준으로 합니다. 각 도구의 이름, 설명 및 입력 스키마를 포함하여 서버 tools/list 결과의 도구 정의를 사용합니다. 예를 들어 최소 toolDescription.json 파일에는 다음이 포함될 수 있습니다.
{
"mcpToolDescription": {
"file": "toolDescription.json"
}
}
{
"tools": [
{
"name": "get_task",
"description": "Gets a task by its identifier.",
"inputSchema": {
"type": "object",
"properties": {
"taskId": {
"type": "string",
"description": "The identifier of the task."
}
},
"required": [
"taskId"
]
}
}
]
}
패키지된 정의를 서버와 일관되게 유지합니다.
동적 도구 검색 사용
동적 검색을 통해 호스트는 패키지된 정의에 의존하는 대신 런타임 tools/list 에 도구 목록을 가져올 수 있습니다.
앱 매니페스트 버전 1.29 이상에서는 mcpToolDescription을 생략할 수 있습니다. 이전 버전에는 파일이 필요합니다. Copilot Cowork에는 버전 1.29 이상에서도 도구 설명 파일이 여전히 필요합니다. WIQD를 사용하면 다음을 통해 --tool-description제공하세요. Work IQ Dev 도구를 참조하세요.
동적 검색을 지원하는 대상 환경의 경우 다음을 통해 tools/list정의를 검색할 수 있도록 생략합니다mcpToolDescription. 도구 이름, 설명 및 입력 스키마를 반환하고 도구 집합의 변경 내용이 새로 고쳐지는 방법을 테스트합니다.
플러그 인 유효성 검사 및 테스트
배포 전에 패키지의 유효성을 검사한 다음 대상 환경에서 테스트합니다.
- 선언된 스키마에 대해 전체 앱 매니페스트의 유효성을 검사하고 개발자 포털에서 앱 패키지 유효성 검사를 사용합니다.
- 엔드포인트가 MCP 초기화에 응답하고 패키지된 파일이
tools/list유효한 도구 정의를 제공하는지 확인합니다. - 대상 환경의 지원되는 프로세스를 통해 테스트 테넌트에 패키지를 배포합니다. 필요한 모든 관리자 승인 또는 액세스 구성을 완료합니다. 배포는 사용자 로그인, 동의 또는 원본 서비스의 권한을 대체하지 않습니다.
- "나에게 할당된 미해결 문제 검색" 또는 쓰기 도구가 있는 서버의 경우 "티켓 번호 123의 상태 업데이트"와 같이 서버가 노출하는 작업에 대한 테스트 프롬프트를 표시합니다.
- 의도한 도구를 사용할 수 있는지, 필요할 때 동의 프롬프트가 표시되는지, 도구 호출이 예상 결과를 반환하는지 확인합니다. 해당하는 경우 OAuth 토큰 새로 고침을 테스트합니다.
- 잘못된 입력, 사용할 수 없는 서비스, 권한 부여 오류, 시간 제한에 대한 실패를 점검하며, 재시도 동작을 포함합니다.
- 시나리오에 다중 테넌트 지원이 필요한 경우 테넌트 전체에서 테스트합니다.
일반적인 문제 해결
| 증상 | 수표 |
|---|---|
| 서버에 연결할 수 없음 | 엔드포인트 접근성, HTTPS, 전송 지원, 방화벽 설정 및 MCP 초기화입니다. |
| 도구가 표시되지 않음 | 패키지된 파일 경로 및 유효한 정의, 또는 생략된 동적 검색 mcpToolDescription 지원 및 작업 tools/list. |
| 인증 실패 | 등록, referenceId자격 증명 유효성, 권한, 동의 및 아웃바운드 권한 부여 헤더입니다. |
| 도구 호출이 실패하거나 시간이 초과됨 | 서버 로그, 입력 유효성 검사, MCP 응답 형식, 동시성, 시간 초과 및 재시도. |
다음 단계
통합이 준비되면 플러그인을 패키징 하고 지원되는 게시 또는 공유 방법을 따릅니다.