M5-3. MCP 커넥터 — 요구사항·인증·파일 전달·승인 주석

한 줄 요약 — 커넥터 = 원격 MCP 서버. HTTPS·JSON-RPC 2.0이 기본이고, mcpToolDescription은 필수, 인증은 OAuth를 권장하며, 승인 여부는 도구 주석으로 정해집니다.

커넥터 아키텍처 — Cowork ↔ MCP 서버 ↔ 외부 시스템

1. 서버 요구사항

항목	요구
전송	Streamable HTTP (HTTPS·TLS 1.2+)
프로토콜	JSON-RPC 2.0 · `tools/list`(권장)·`tools/call`
응답 시간	도구 호출당 30초 미만
가용성	스토어 게시 앱은 99.9% SLA 권장

2. manifest의 커넥터 정의

"agentConnectors": [{
  "id": "contoso-legal-api",
  "displayName": "Contoso Legal Database",
  "description": "…",
  "toolSource": { "remoteMcpServer": {
    "mcpServerUrl": "https://api.contoso.com/legal/mcp",
    "mcpToolDescription": { "file": "./tools/contoso-legal-tools.json" },
    "authorization": { "type": "OAuthPluginVault", "referenceId": "…" }
  }}
}]

mcpToolDescription 필수 — 빠지면 HTTP 400으로 거부. 참조 JSON은 ZIP 안에 포함
패키지당 커넥터 최대 10개 · id는 중복 불가 · plugin 또는 remoteMcpServer 중 정확히 하나

3. 인증 3종

커넥터 인증 선택 — None·OAuth·DCR

타입	용도	비고
`None`	공개·내부 API	referenceId 넣으면 오류
`OAuthPluginVault`	OAuth 2.0 (프로덕션 권장)	referenceId = Agents Toolkit OAuth 등록 ID · Any Microsoft 365 Organization으로 등록
`ApiKeyPluginVault`	API 키	⚠️ Cowork 미지원 (현재) — OAuth·DCR로 대체

DCR(Dynamic Client Registration) 을 지원하는 서버는 authorization을 생략해도 됨 — Cowork가 OAuth 클라이언트를 자동으로 만듦. 자격 증명은 Enterprise Token Store에 저장 — manifest·스킬에 시크릿 없음.

4. 도구 설계 지침

작은 API(작업 15개 미만): 작업마다 도구 1개 (search_case_law, get_ruling)
큰 API(작업 50개 이상): search_actions + execute_action 패턴 사용
파라미터마다 description 작성 — 에이전트가 읽는 문서입니다 · 결과는 구조화된 JSON으로 반환

5. 파일 전달 (`contentEncoding: base64`)

파일 전달 — 모델 컨텍스트 비소모 구조

파일을 받는 도구는 파라미터에 contentEncoding: base64를 선언합니다 — 모델은 파일 경로만 다루고, Cowork가 파일을 base64로 변환해 서버에 보냅니다 (파일 내용이 모델 컨텍스트를 차지하지 않음). 한도: 호출당 8파일 · 파일당/호출당 150MiB · 배열 파일 파라미터는 도구당 1개 · 최상위 파라미터만.

6. 승인 주석 (annotations)

필드	효과
`readOnlyHint: false`	실행 전 확인 필요
`destructiveHint: true`	실행 전 확인 필요
`title`	확인 대화상자에 표시할 라벨

주석이 없는 도구는 파괴적(destructive) 도구로 보고 항상 확인을 요구합니다 — 주석을 정확히 선언하세요.

출처

출처: Build plugins — Add a connector·MCP annotation (MS Learn) · Configure authentication for MCP and API plugins (MS Learn)