MCP 도구 호출 결과 구조: content와 structuredContent

MCP 도구 호출 결과는 세 가지 주요 부분으로 이뤄진 JSON 객체입니다. 항목(텍스트, 이미지, 오디오, 리소스 링크, 임베디드 리소스)의 배열인 content, 기계가 읽을 데이터를 담는 선택 필드 structuredContent, 그리고 도구 자체가 실패했을 때 true가 되는 isError입니다. 이미지와 오디오는 mimeType과 함께 base64 data로 전달되며, 구조화된 데이터를 반환하는 도구는 그 데이터를 직렬화한 JSON으로 텍스트 항목에도 넣어야 합니다.

구조는 MCP 2025-11-25의 도구 페이지와 스키마 레퍼런스에서, 변경 사항은 2026-07-28의 도구 페이지와 변경 로그에서 가져왔으며, 모두 2026-09-28에 확인했습니다. 예시로 든 Sume 호스팅 MCP 서버 내용은 서버의 현재 코드에서 가져왔습니다. Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명합니다.

도구 호출 결과에는 어떤 필드가 있나요?

결과는 JSON-RPC 응답의 result에 들어갑니다. 명세의 날씨 예시는 같은 데이터를 텍스트와 structuredContent로 두 번 반환합니다.

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      { "type": "text", "text": "{\"temperature\": 22.5, \"conditions\": \"Partly cloudy\", \"humidity\": 65}" }
    ],
    "structuredContent": { "temperature": 22.5, "conditions": "Partly cloudy", "humidity": 65 }
  }
}

MCP 도구에서 이미지는 어떻게 반환하나요?

content에 이미지 항목을 추가하세요. "type": "image", base64로 인코딩한 이미지를 담은 data, 그리고 image/png 같은 mimeType으로 이뤄집니다. 스키마는 제공자마다 지원하는 이미지 형식이 다를 수 있다고 적고 있습니다. 모든 콘텐츠 유형에는 대상(audience), 우선순위, 수정 시각에 대한 선택적 어노테이션도 붙일 수 있습니다. 나머지 항목 유형은 다음과 같습니다.

• text: text 문자열입니다.
• audio: base64 data와 audio/wav 같은 mimeType입니다.
• resource_link: 클라이언트가 구독하거나 가져올 수 있는 uri와 name, description, mimeType입니다. 링크된 리소스가 resources/list에 나온다는 보장은 없습니다.
• resource: uri, mimeType, 내용을 담은 임베디드 리소스입니다. 리소스를 임베드하는 서버는 resources 기능(capability)을 구현해야 합니다(SHOULD).

structuredContent와 outputSchema는 언제 쓰나요?

모델뿐 아니라 프로그램도 결과를 읽을 때 structuredContent를 쓰세요. 하위 호환성을 위해, 이를 반환하는 도구는 직렬화한 JSON도 텍스트 블록에 담아 반환해야 합니다(SHOULD). 명세는 이것을 서버가 만든 결과 데이터라고 부르며, 스키마로 제약된 모델 생성을 뜻하는 LLM의 구조화된 출력(structured outputs)과는 관계가 없다고 설명합니다.

도구는 outputSchema도 선언할 수 있습니다. 선언했다면 서버는 반드시 그 스키마를 따르는 구조화된 결과를 반환해야 하고(MUST), 클라이언트는 결과를 검증해야 합니다(SHOULD). 명세에 따르면 이렇게 하면 엄격한 스키마 검증이 가능해지고, 프로그래밍 언어와 더 잘 연동할 수 있도록 타입 정보가 제공됩니다. 2025-11-25에서는 스키마의 루트가 type: "object"로 제한되며, 2026-07-28 개정판은 inputSchema와 outputSchema에 어떤 JSON Schema 2020-12 키워드든 쓸 수 있도록 제한을 풉니다.

도구는 결과 안에서 오류를 어떻게 알리나요?

isError: true와, 무엇이 잘못됐는지 설명하는 content 항목으로 알립니다. 스키마에 따르면 도구에서 비롯된 오류는 프로토콜 수준 오류가 아니라 결과 안에서 보고해야 합니다(SHOULD). 그렇지 않으면 모델이 오류를 보고 스스로 바로잡을 수 없습니다. 도구를 찾는 과정의 오류나 그 밖의 예외 상황은 대신 MCP 오류 응답으로 보내야 합니다. 이 번호들은 MCP 오류 코드에서 다룹니다.

Sume MCP 서버는 무엇을 반환하나요?

현재 코드 기준으로 텍스트 항목 하나입니다. 성공하면 Sume 호스팅 서버는 JSON 객체를 담은 text 항목 하나를 isError: false와 함께 반환하며, structuredContent는 없습니다. 나열되는 도구에는 name, title, description, inputSchema, annotations가 있고 outputSchema는 없습니다.

• 실패는 JSON에 code와 message가 담긴 text 항목 하나이며, isError: true가 함께 옵니다.
• 256KB를 넘는 결과는 코드가 mcp_output_too_large인 isError: true 결과로 대체됩니다. 메시지는 이것이 Job 실패가 아니라 출력 한도라고 설명하므로, 유료 create를 절대 다시 제출하지 마세요.
• 이미지나 오디오 항목은 없습니다. 생성 도구는 Job id로 응답하고, 완료된 Job의 아티팩트에는 media.sume.com URL이 있으며, jobs_result가 이를 그 JSON 안에 담아 반환합니다.