MCP 및 API 플러그 인은 Microsoft 365 Copilot의 선언적 에이전트가 OpenAPI 설명이 있는 MCP(모델 컨텍스트 프로토콜) 서버 또는 REST API와 상호 작용할 수 있도록 하는 사용자 지정 작업입니다. 이러한 플러그인 중 하나를 사용하여 사용자는 선언적 에이전트에게 MCP 서버 또는 REST API에 정보를 쿼리하고 지원되는 경우 자연어 프롬프트를 통해 데이터와 개체를 생성, 업데이트 및 삭제하도록 요청할 수 있습니다.
이 문서에서는 선언적 에이전트에서 사용하는 기술 MCP 또는 API 사용자 지정 작업에 플러그인 을 사용합니다. 고객 대면 플러그 인 제품, 패키지, 레지스트리 및 수명 주기에 대해서는 Microsoft 365 Copilot용 플러그 인을 참조하세요.
빌드 또는 재사용하는 동안 이 문서를 사용하여 MCP 또는 API 작업을 선택하고 오케스트레이터가 이를 호출하는 방법을 이해합니다. 이를 구현하기 위한 기술 작업 모델 및 제품 절차로 마무리합니다. 그 결과 조치는 별도의 공개 배포 약속이 아닌 에이전트의 종속성입니다.
중요
MCP 및 API 플러그인은 선언적 에이전트 내에서 작업을 제공합니다. 독립형 설치 가능한 플러그인 패키지가 아닙니다. 포함된 에이전트만 해당 기능과 도구에 액세스할 수 있습니다. 패키지와 작업 매니페스트 관계에 대한 자세한 내용은 플러그 인 및 선언적 에이전트 작업을 참조하세요.
API 또는 MCP 플러그 인은 Copilot이 에이전트에서 사용할 수 있는 API 또는 MCP 서버에 대해 알아보기 위해 읽는 플러그 인 매니페스트를 사용합니다. 그런 다음 Copilot은 에이전트가 해당 통합을 사용하여 프롬프트에 응답해야 하는 시기를 결정할 수 있습니다. 이 매니페스트에 대한 자세한 내용은 API 및 MCP 플러그인 매니페스트 스키마를 참조하세요. 설치 가능한 패키지는 별도의 Microsoft 365 앱 매니페스트를 사용합니다.
Copilot이 MCP 서버 도구를 검색하는 방법
MCP 서버를 기반으로 하는 플러그 인의 경우 Copilot은 기본적으로 런타임에 MCP 서버에서 직접 플러그 인의 도구를 동적으로 확인합니다. 동적 도구 검색은 에이전트가 다시 패키지되고 다시 게시될 때까지 기다리지 않고 MCP 서버가 노출하는 최신 도구를 얻는 것을 의미합니다. 에이전트를 빌드할 때 개발자는 필요에 따라 플러그 인 매니페스트에 고정된 도구 집합을 고정할 수 있습니다. REST API 플러그인은 항상 플러그인 매니페스트에 정의된 도구를 사용합니다. 자세한 내용은 Microsoft 365 Copilot용 MCP 서버에서 플러그 인 빌드 및 Microsoft 365 Copilot의 MCP 플러그 인용 동적 도구 검색을 참조하세요.
이 기본값은 선언적 에이전트 작업으로 사용되는 MCP 플러그인에 적용됩니다. Microsoft 365 앱 매니페스트를 통해 agentConnectors 원격 MCP 서버를 참조하는 플러그 인의 경우 동적 도구 검색에는 앱 매니페스트 버전 1.29 이상 과 이를 허용하는 호스트가 필요합니다. 자세한 내용은 Microsoft 365 Copilot 플러그 인에 대한 원격 MCP 서버 구성을 참조하세요.
플러그 인 예제
예산을 쿼리 및 만들거나, 비용을 청구하거나, 기존 예산에 자금을 추가할 수 있는 예산 MCP 서버를 고려하세요. "Contoso 출장 예산에 남은 금액"이라는 프롬프트는 도구를 호출하는 예산 플러그 인을 트리거할 수 있습니다 get-budgets .
POST /mcp
Content-Type: application/json
{
"method": "tools/call",
"params": {
"name": "get-budgets",
"arguments": {
"budgetName": "contoso travel"
}
}
}
Copilot은 도구 결과의 응답을 사용하여 다음과 같은 응답을 생성합니다. "Contoso 출장 예산에는 현재 사용 가능한 자금이 5,000달러입니다. 특정 카테고리에 자금을 할당하거나 비용을 추적해야 하는 경우에도 도와드릴 수 있습니다. 제가 어떻게 도울 수 있는지 알려주세요!"
"Megan의 항공권에 대해 Contoso 여행 예산에 $500 청구" 프롬프트는 다음 MCP 도구 호출로 변환될 수 있습니다.
POST /mcp
Content-Type: application/json
{
"method": "tools/call",
"params": {
"name": "charge-budget",
"arguments": {
"budgetName": "contoso travel",
"amount": 500,
"description": "Megan's airline ticket"
}
}
}
Copilot은 반환된 정보를 사용하여 사용자에게 응답합니다. "Megan의 항공권 요금 $500가 성공적으로 처리되었습니다. Contoso 출장 예산에는 현재 사용 가능한 자금이 4,500달러가 남아 있습니다. 더 많은 거래가 필요하거나 예산에 대한 추가 지원이 필요한 경우 알려주세요!"
플러그인 작동 방식
사용자는 에이전트에게 "Fourth Coffee 로비 리노베이션 예산이 얼마나 남아 있습니까?"라고 묻습니다.
동적 도구 검색을 사용하는 MCP 플러그 인의 경우 에이전트는 런타임에 플러그 인의 MCP 서버에서 현재 도구 정의를 가져오고 사용하기 전에 새 도구나 변경된 도구의 유효성을 검사합니다. 고정된 도구 집합이 있는 플러그 인 또는 REST API 플러그 인의 경우 에이전트는 플러그 인 매니페스트에 정의된 도구를 대신 사용합니다.
에이전트는 예산 세부 정보를 가져오기 위한 MCP 서버 도구 또는 API
GetBudget가 있는 사용 가능한 플러그 인에서 예산 관련 플러그 인을 식별합니다. 매핑하는 도구는 사용자 질문의 일부를 함수의 매개 변수에 매핑합니다.budgetName=""에이전트는 사용자에게 플러그 인으로 보낼
Fourth Coffee lobby renovation수 있도록 허용하도록 요청합니다.사용자는 플러그 인과 데이터를 한 번 공유하도록 허용하거나 이 기능을 위해 데이터를 항상 공유하도록 허용하도록 선택합니다.
플러그 인의 MCP 서버 또는 API에 인증이 필요한 경우 플러그 인은 토큰 스토어에서 토큰 또는 API 키를 요청합니다.
토큰 저장소는 토큰 또는 키를 반환합니다. 필요한 경우 토큰 저장소는 에이전트가 사용자에게 로그인하라는 메시지를 표시하도록 합니다.
에이전트는 Microsoft 365 외부에서 호스트되는 플러그 인의 MCP 서버 또는 API에 요청을 보냅니다.
MCP 서버 또는 API가 응답을 반환합니다.
{ "name": "Fourth Coffee lobby renovation", "availableFunds": 5000.00 }에이전트는 MCP 서버 또는 API 응답을 기반으로 응답을 생성합니다.
에이전트는 "Fourth Coffee 로비 리노베이션 예산에 남아 있는 사용 가능한 자금은 $5,000입니다"라는 응답을 보냅니다.
작업 확인
Copilot은 플러그 인에 처음으로 데이터를 보내기 전에 사용자에게 묻습니다.
사용자가 연결을 확인한 후 데이터를 검색하는 MCP 서버 도구와 API는 확인이 필요하지 않지만, 데이터를 수정하는 도구 및 API는 확인이 필요합니다. 플러그인 개발자는 이러한 기본값을 재정의할 수 있습니다. 자세한 내용은 Microsoft 365 Copilot용 MCP 및 API 플러그 인에 대한 확인 프롬프트를 참조하세요.
응답 프레젠테이션 사용자 지정
Copilot은 MCP 서버 또는 API 응답의 데이터를 사용하여 대화형 응답을 생성합니다. 플러그인은 이 데이터가 표시되는 방식을 사용자 지정할 수 있으며 메커니즘은 플러그인 유형에 따라 다릅니다.
MCP 플러그인은 MCP 서버가 런타임 시 도구 결과와 함께 반환하는 UI 위젯인 MCP 앱을 사용하여 풍부한 대화형 응답을 제공할 수 있습니다. 위젯은 매니페스트에 정의되지 않고 도구 응답과 함께 제공되므로 플러그 인이 고정된 도구 세트를 사용하든 동적 도구 검색을 사용하든 관계없이 MCP 앱이 작동합니다.
API 플러그인은 플러그인 매니페스트에 적응형 카드 템플릿을 제공하여 데이터를 구조화된 방식으로 표시할 수 있습니다. 템플릿은 매니페스트에 선언된 작업에 대해 정의되므로 이 방법은 고정된 도구 세트를 사용하는 API 플러그인 및 MCP 플러그인에 적용됩니다.
모든 플러그 인 유형에 대한 원본 연결 인용의 경우 Copilot은 응답 의미 체계를 사용하고 도구 또는 API 응답에서 인용 메타데이터를 자동으로 유추할 수 있습니다. 자동 유추는 도구가 런타임에 확인되고 구성할 매니페스트 도구 정의가 없는 동적 도구 검색을 사용하는 MCP 플러그 인에 특히 유용합니다. 자세한 내용은 응답 의미 체계와 함께 인용 표시를 참조하세요.
응답의 URL 처리
Microsoft 365 Copilot 채팅 환경은 MCP 플러그 인, API 플러그 인, 커넥터 또는 흐름에서 작업 응답의 일부로 반환된 URL을 클릭 가능한 링크로 렌더링할 수 있습니다. Copilot 런타임은 이 동작을 제어하고 플러그 인이 선언하는 도메인(예: servers API 플러그 인의 OpenAPI 설명 섹션)에 대해 평가하지 않습니다.
플랫폼 보안, 신뢰 및 정책 규칙은 작업 응답에 대한 URL 렌더링 동작을 관리하며 시간이 지남에 따라 변경될 수 있습니다. 프로덕션 중요 시나리오에 대한 클릭 가능한 URL 실행 중 응답에 의존하지 마세요.
Copilot 오케스트레이터가 에이전트의 작업을 선택할 수 있도록 지원
오케스트레이터가 사용자의 요청에 적합한 작업을 선택할 수 있도록 API 또는 MCP 통합, 해당 기능 또는 도구, 입력을 정확하게 설명합니다. 이러한 설명은 외부 플러그인 패키지의 이름이나 스토어 설명이 아닌 에이전트의 작업과 관련이 있습니다.
| 작업 통합 | 설명할 위치 | 자세한 정보 |
|---|---|---|
| API 플러그인 | 플러그인 매니페스트 및 OpenAPI 작업 및 매개 변수 설명 | 효과적인 OpenAPI 설명 만들기 |
| MCP 플러그인 | 플러그인 매니페스트 및 MCP 도구 설명; 도구 정의는 런타임 시 서버에서 가져오거나 매니페스트에 고정됩니다. | 동적 도구 검색 및 고정된 도구 |
함수 및 MCP 도구는 기술에서 플러그 인 기능으로 설명하는 재사용 가능한 명령 파일과 동일하지 않습니다.
API 또는 MCP 작업을 사용하여 선언적 에이전트 빌드
전문성 개발을 위해 Work IQ Dev 도구로 시작하세요. 먼저 문서화된 환경을 선택한 다음, 프로젝트 생성 또는 통합 기능이 필요한 경우 다음 목록에서 도구를 추가합니다.
-
Work IQ Dev Tools 는 권장되는 도구입니다. 지원되는 OpenAPI 또는 원격 MCP 작업을 선언적 에이전트 프로젝트에 추가하는 데 사용합니다
wiqd agent add action. - MCP 서버, OpenAPI 설명 또는 새 REST API에 대해 기존 도구 키트 기반 연습을 계속 사용할 수 있습니다. 도구 키트 프로젝트로 작업할 때는 이러한 절차를 따릅니다.
- Kiota 는 기존 OpenAPI 설명에서 API 플러그인 매니페스트를 생성할 수 있습니다.
API 또는 MCP 플러그인 매니페스트는 에이전트의 작업 통합을 구성합니다. 지원되는 앱 패키지 경로를 통해 포함하는 에이전트를 패키지하고 배포합니다. 작업 매니페스트는 독립적으로 설치할 수 있는 플러그인 패키지가 아닙니다.
팁
Work IQ Dev Tools 가 일반 공급됩니다.
wiqd agent add action 선언적 에이전트 프로젝트에 작업을 추가하고 wiqd agent validate --mode source 저장된 에이전트 소스에서 오프라인 검사를 실행합니다. 소스 검사에 통과한다고 해서 런타임 또는 OpenAPI 엔드포인트 연결성, 인증 정확성 또는 최종 패키지 승인이 설정되지는 않습니다. 를 생 --mode략하면 유효성 검사는 기본적으로 package, 기존 ZIP의 복사본을 업로드하며 로그인이 필요할 수 있습니다. 유효성 검사 모드 및 적용 범위는 WIQD 명령 참조 및 유효성 검사 및 MVL을 참조하세요.
제한 사항
이러한 제한은 설치 가능한 플러그인 패키지의 기술, 에이전트 또는 커넥터 수가 아니라 선언적 에이전트 작업으로 사용되는 API 및 MCP 플러그인과 관련이 있습니다.
선언적 에이전트에 선언 적 에이전트 매니페스트에 정의된 최대 5개의 플러그인이 포함된 경우 에이전트는 항상 프롬프트에 플러그인을 삽입합니다. 에이전트에 플러그인이 5개 이상 포함되어 있으면 의미 체계 일치를 사용합니다. 의미 체계 일치는 플러그 인 자체 내의 개별 기능이나 도구가 아닌 플러그 인의 설명을 기반으로 합니다.
플러그인에는 무제한의 함수 또는 MCP 도구가 포함될 수 있습니다. 하나만 일치하는 경우에도 일치하는 플러그인의 모든 함수나 도구가 반환됩니다. 동적 도구 검색을 사용하는 MCP 플러그 인의 경우 런타임 시 MCP 서버에서 확인된 도구가 이 총계에 포함됩니다. 토큰 기간 제한으로 인해 10개 이상의 함수 또는 도구가 포함된 경우 응답의 품질이 저하될 수 있습니다.
플러그 인에 대한 입력 및 출력에 대한 토큰 창은 큰 콘텐츠를 잘라냅니다. 기능 제한은 모델이 개선되고 시스템 오버헤드에 따라 변경될 수 있습니다. 작은 토큰 길이에 최적화하거나 필요한 경우 대용량 콘텐츠를 스트리밍할 수 있는 확장성 옵션을 선택합니다.
다음 단계
선택한 MCP 작업 또는 API 작업을 구현합니다. 구성 요소가 개별적으로 작동하면 패키지 & 테스트 에 통합 및 구성 요소를 테스트합니다.
관련 콘텐츠
- Microsoft 365 Copilot용 MCP 서버에서 플러그 인 빌드
- Microsoft 365 Copilot의 선언적 에이전트에 MCP 앱 추가
- Microsoft 365 Copilot의 MCP 플러그 인에 대한 동적 도구 검색
- 기존 API에서 Microsoft 365 Copilot용 API 플러그 인 빌드
- 새 API를 사용하여 Microsoft 365 Copilot용 API 플러그 인 빌드
- Microsoft 365 Copilot용 API 및 MCP 플러그 인 매니페스트 스키마
- API 플러그 인을 사용하여 선언적 에이전트에 대한 효과적인 지침 작성