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)