MCP outputSchema 및 structuredContent: 검증 가능한 에이전트용 출력 계약

MCP는 더 이상 도구(tools)의 결과를 자유 형식의 텍스트로 취급해서는 안 됩니다. outputSchema와 structuredContent를 통해 검증 가능한 계약(contracts)을 정의함으로써, 취약한 파싱(parsing)을 줄이고 에이전트를 위한 더 나은 가드레일(guardrails)을 구축할 수 있습니다.

Model Context Protocol의 2025-06-18 업데이트는 OAuth만큼 눈에 띄지는 않지만, 에이전트를 구축하는 팀에게 매우 실용적인 요소를 추가했습니다. 바로 도구 결과물을 위한 outputSchema와 structuredContent입니다. MCP 서버는 모델이 나중에 해석해야 하는 단순 텍스트만을 반환하는 대신, 출력의 형태를 선언하고 검증 가능한 JSON을 반환할 수 있습니다.

중요한 신호

이것이 모델의 판단 기준을 없애거나 보안 제어를 대체하는 것은 아닙니다. 다만, 흔히 발생하는 오류 유형을 줄여줍니다. 즉, 모호한 문단을 반환하는 도구, 데이터와 섞여 있는 에러 메시지, 파싱이 불가능한 리스트, 또는 업스트림(upstream) 실패 시 형식이 변해버리는 응답과 같은 문제들입니다.

운영상의 핵심 논리는 간단합니다. 만약 MCP 도구가 의사 결정, PR(Pull Requests), RAG(Retrieval-Augmented Generation), 보고(reporting), 비용(cost), 또는 권한이 있는 작업(actions)에 영향을 미친다면, 그 출력은 반드시 하나의 계약(contract)이어야 합니다. 자유 형식의 텍스트는 인간을 위한 설명용으로 남겨두고, structuredContent는 자동화용으로 사용해야 합니다.

MCP에서 변경된 사항

도구(tools) 사양은 매개변수를 위한 inputSchema와 예상되는 출력을 위한 선택적 JSON Schema인 outputSchema를 정의합니다. 도구가 structuredContent를 반환할 때, 서버는 사양을 선언했다면 이를 준수해야 하며, 클라이언트는 이를 모델이나 워크플로(workflow)의 다른 계층으로 전달하기 전에 검증해야 합니다.

동일한 페이지에서 하위 호환성(backward compatibility)도 유지합니다. 구조화된 콘텐츠를 반환하는 도구는 TextContent 내에 직렬화된 버전도 포함해야 합니다. 이는 모든 MCP 클라이언트가 동일한 속도로 업데이트되지 않기 때문에 중요하며, 새로운 형식만 사용하는 서버는 오래된 소비자(consumers)를 망가뜨릴 수 있기 때문입니다.

이 변화는 많은 MCP 통합을 진정한 API로 변모시킵니다. 도구의 설명(description)은 모델이 언제 도구를 사용할지 결정하는 데 계속 도움을 주며, 스키마(schema)는 런타임(runtime)이 결과물이 유효한지 확인하는 데 도움을 줍니다.

좋은 프롬프팅(prompting)만으로는 충분하지 않은 이유

프롬프트로 "유효한 JSON을 반환해줘"라고 요청할 수는 있지만, 이는 강력한 계약(contract)이 아닙니다. 모델이나 도구(tool)가 추가 텍스트를 포함하거나, 필드를 누락하거나, 이름을 변경하거나, 혹은 소비자가 데이터로 해석하는 필드에 오류를 섞어 넣을 수 있습니다. 데모에서는 작동할지 몰라도, 프로덕션(production) 환경에서는 잘못된 실행 경로를 만들어냅니다.

outputSchema는 이러한 기대를 도구의 경계(edge)로 이동시킵니다. 만약 search_docs가 id, title, url, score, snippet을 포함하는 문서 목록을 약속한다면, 클라이언트는 불완전한 응답을 거부하거나, 실행 상태를 저하(degraded)된 것으로 표시하거나, 계속 진행하기 전에 인간의 승인을 요청할 수 있습니다.

코드 에이전트(code agent)에게 이 차이는 구체적입니다. "중요한 파일 3개를 찾았습니다"라는 문장을 읽는 것과, 경로(path), 범위(range), 해시(hash), 사유(reason)가 검증된 배열(array)을 받는 것은 전혀 다릅니다. 후자는 취약한 파싱(parsing)에 의존하지 않고도 디프(diff), 리뷰 또는 메트릭(metric)의 입력값으로 사용할 수 있습니다.

유용한 스키마(schema) 설계

업스트림(upstream) API가 아니라 소비자(consumer)부터 시작하십시오. 만약 에이전트가 PR(Pull Request)을 생성할지 결정해야 한다면, 스키마에는 confidence, changedFiles, testsRun, riskLevel, requiresHumanReview와 같은 필드가 포함되어야 합니다. 도구가 문서를 조회한다면 sourceUrl, retrievedAt, quote 또는 summary를 포함하고, 증거(evidence)와 해석(interpretation)을 명확히 분리하십시오.

거대한 스키마는 피하십시오. 제공자의 전체 응답을 복제하는 outputSchema는 컨텍스트(context)를 소모하며 모델이 무관한 필드를 살펴보게 만듭니다. 에이전트가 행동하는 데 필요한 최소한의 정보만 노출하고, 리소스 링크(resource links)나 복구 가능한 아티팩트(artifacts)와 같은 방대한 세부 사항은 남겨두십시오.

명시적인 상태(state)를 포함하십시오: ok, partial, rate_limited, not_found, permission_denied. 모델이 문장을 통해 실패를 추론하게 만들지 마십시오. 프로덕션 환경에서의 MCP에 대한 연구는 구조화된 오류 의미론(structured error semantics)의 부재를 프로토콜과 실제 운영 사이의 격차로 정확히 지적하고 있습니다.

리소스 링크(Resource links) 대 블롭(blobs)

MCP는 도구(tool)가 클라이언트가 나중에 가져오거나 구독할 수 있는 리소스를 가리키는 resource_link를 반환할 수 있도록 허용합니다. 이는 결과에 항상 긴 블롭(blobs)을 포함하는 것보다 더 나은 방식입니다. 에이전트는 URI, 이름, 설명, MIME 타입 및 어노테이션(annotations)이 포함된 참조를 받고, 더 많은 컨텍스트를 로드할 필요가 있는지 결정합니다.

리포지토리(repositories)의 경우, 이는 후보 파일, CI 로그, 트레이스(traces), 검색된 문서 또는 생성된 보고서와 같은 결과와 잘 맞습니다. 구조화된 결과(structured result)는 랭킹(ranking)과 메타데이터를 포함할 수 있으며, 리소스 링크(resource link)는 초기 컨텍스트를 가득 채우지 않으면서 전체 아티팩트(artifact)를 보존합니다.

건강한 패턴은 인덱스(index)를 먼저 반환하고 콘텐츠(content)를 나중에 반환하는 것입니다. 에이전트에게 전체가 필요하다면 요청할 것입니다. 만약 다음 단계를 결정하는 데만 필요하다면, 사용되지 않는 자료에 대해 토큰(tokens) 비용을 지불할 필요가 없습니다.

클라이언트 측 검증 (Validation in the client)

명세(specification)에 따르면 서버는 자신의 스키마(schema)를 준수해야 하며, 클라이언트는 구조화된 결과(structured results)를 검증해야 합니다. 진지한 아키텍처에서는 양측 모두 각자의 역할을 수행합니다. 즉, 서버는 응답하기 전에 검증하고, 클라이언트는 신뢰하기 전에 검증합니다.

확인해야 할 사항

검증 없이 structuredContent를 작업을 실행하는 파이프라인(pipeline)에 직접 전달하지 마세요. 타입(type), 필수 필드(required fields), 길이(lengths), 열거형(enumerations) 및 숫자 제한(numerical limits)을 검증하십시오. TypeScript를 사용하는 경우, 파서(parser)나 타입 가드(type guard)를 통과할 때까지 해당 값을 unknown으로 취급하십시오. Python을 사용하는 경우, 결정을 내리기 전에 JSON Schema 또는 타입이 지정된 모델(typed models)로 검증하십시오.

검증은 비용도 제한해야 합니다: 최대 아이템 수, 스니펫(snippets)의 최대 크기, 허용된 URL, 허용된 MIME 타입 및 도구(tool)별 타임아웃(timeout) 등이 포함됩니다. 올바르지만 너무 거대한 스키마는 잘못된 응답만큼이나 에이전트에게 해로울 수 있습니다.

제어 데이터로서의 오류 (Errors as control data)

사양(specification)은 isError: true를 통해 JSON-RPC 프로토콜 오류와 도구(tool) 실행 오류를 구분합니다. 이 구분은 매우 중요합니다. 알 수 없는 도구 이름이나 잘못된 인자(arguments)는 프로토콜 문제이지만, 업스트림(upstream)의 429 오류, 만료된 자격 증명, 또는 검색 결과 없음은 에이전트가 처리할 수 있는 운영 상태(operational states)입니다.

구조화된 방식으로 복구 가능한 오류를 설계하십시오: code, retryAfterSeconds, safeToRetry, userActionRequired, detailsForLog 및 messageForModel을 포함합니다. 모델이 전체 스택 트레이스(stack trace)를 볼 필요는 없지만, 재시도해야 하는지, 권한을 요청해야 하는지, 범위를 축소해야 하는지, 아니면 중단해야 하는지는 알아야 합니다.

permission_denied와 not_found를 구분하는 에이전트는 더 나은 결정을 내립니다. 단순히

스키마 (schemas) 또한 토큰 (tokens) 비용을 발생시킵니다. 에이전틱 RAG (agentic RAG)에 관한 최근 논문에 따르면, 많은 도구 (tools) 정의가 정보를 검색하기 위해 사용 가능한 컨텍스트 (context)와 경쟁할 수 있음을 보여줍니다. 구체적인 결과는 모델과 예산에 따라 달라질 수 있지만, 교훈은 명확합니다: 도구의 각 필드는 그 존재를 정당화할 수 있어야 합니다.

중복되는 설명을 압축하고, 일관된 이름을 사용하며, 스키마 (schema) 내에 전체 문서를 포함하는 것을 피하십시오. 규모가 큰 도구 카탈로그의 경우, 기능을 흐름별로 그룹화하고 작업에 필요한 것만 활성화하십시오. 타입이 완벽하게 지정되었더라도 항상 로드되는 도구는 에이전트 (agent)의 성능을 저하시킬 수 있습니다.

목표는 모델에게 시스템의 모든 것을 설명하는 것이 아닙니다. 모델에게 진행하기에 충분하면서도 작고, 검증 가능하며, 명확한 계약 (contracts)을 제공하는 것입니다.

구현 체크리스트 (Checklist)

자동화를 지원하는 모든 도구 (tool)에 outputSchema를 선언하십시오.
호환성을 위해 structuredContent와 직렬화된 TextContent를 반환하십시오.
응답하기 전에 서버에서 출력을 검증하십시오.
모델로 전달하거나 작업을 실행하기 전에 클라이언트에서 출력을 검증하십시오.
데이터, 복구 가능한 오류, 프로토콜 오류를 분리하십시오.
결과에 블롭 (blobs)을 넣는 대신 큰 아티팩트 (artifacts)에는 resource_link를 사용하십시오.
아이템 수, 크기, URL 및 MIME 타입을 제한하십시오.
검증되지 않은 서버로부터 오는 도구 어노테이션 (tool annotations)을 신뢰하지 마십시오.
스키마 및 활성화된 도구에 의해 소비되는 토큰을 측정하십시오.
어떤 필드가 증거이고 어떤 필드가 해석인지 문서화하십시오.

사고 실험 예시

테스트를 수정하는 에이전트를 위한 inspect_ci_failure 도구를 상상해 보십시오. 형편없는 출력은 요약된 로그가 포함된 텍스트 블록일 것입니다. 유용한 출력은 failingJobs, firstFailingCommand, suspectedFiles, confidence, reproCommand, logResourceLinks 및 requiresSecretAccess를 포함할 것입니다. 이를 통해 에이전트는 메가바이트 단위의 로그를 읽지 않고도 테스트, 코드 또는 설정을 수정할지 여부를 결정할 수 있습니다.

인간 리뷰어 또한 이득을 얻습니다. "이 변경 사항이 어디서 왔나요?"라고 묻는 대신, 에이전트가 어떤 구조화된 증거 (structured evidence)를 사용했는지, 어떤 로그를 참조했는지, 그리고 어떤 위험 수준을 선언했는지 확인할 수 있습니다.

이것이 structuredContent의 진정한 가치입니다. 모델을 더 깔끔해 보이게 만드는 것이 아니라, 다른 시스템이나 사람이 검증할 수 있는 기술적 흔적을 남기는 것입니다.

결론

MCP는 에이전트를 위한 통합 계층 (integration layer)으로서 성장하고 있지만, 신뢰성은 단순히 더 많은 서버를 설치한다고 해서 생겨나지 않습니다. 신뢰성은 각 도구 (tool)가 작고, 검증 가능하며, 감사 가능한 (auditable) 계약을 가질 때 생겨납니다.

오늘 MCP 서버를 구축하고 있다면, 조만간 outputSchema를 추가하십시오. 만약 MCP 서버를 사용하고 있다면, structuredContent를 검증하고 자유 형식의 텍스트 (free text)는 API가 아닌 설명으로 취급하십시오. 에이전트가 세 개의 도구를 체인(chain)으로 연결하고 모호한 응답이 잘못된 PR, 잘못된 지표, 또는 권한이 부여된 동작으로 이어지기 전까지는 그 차이가 작아 보일 수 있습니다.

원문은 devaisemanal.com에 게시되었습니다.

개발자를 위한 AI 도구 주간 뉴스레터 받기 → — 매주 화요일: Claude Code, Cursor, Copilot, MCP, 에이전트 및 새로운 도구들을 전달합니다. 스페인어로, 불필요한 정보 없이 깔끔하게 제공됩니다.