MCP 입력 기본값 검수: default와 실제 인자는 다릅니다
MCP 도구의 default 선언과 실제 입력 보정을 구분합니다. required 누락과 null·숫자 문자열을 같은 조건으로 비교하고, 보정 주체와 실행 인자를 대조하는 인수표를 제안합니다.
이 글을 쓴 알파카랩스카카오·네이버·쿠팡 출신, 재하청 0%, 대기업·공공기관 등 18개사+ 레퍼런스
MCP 입력의 default는 값 보정 실행을 보장하지 않습니다. 2026-10-31 기준, 보정 기능을 켠 구현은 실제 전달값까지 검수합니다.
조회 도구의 입력 스키마에 기본값을 적어 두었는데 새 호스트에서는 요청이 거부된다면 어디를 봐야 할까요? 원래 보낸 값과 중간 계층이 채운 값을 나누면 같은 스키마가 다른 동작으로 이어진 이유를 좁힐 수 있습니다. 이 글은 입력 보정 책임과 실행 인자를 연결하는 인수표를 제안합니다.
입력 기본값 검수에서 먼저 고정할 조건은 무엇인가요?#
같은 도구·입력 스키마·호스트·SDK·검증기 버전과 옵션을 고정합니다. 비교하려는 계층만 바꾸고 원본 전송 JSON부터 남기세요. 스키마 파일의 동일성만으로 실제 실행값이 같다고 판단하지 않습니다.
도구 제공자는 필수 입력과 허용 범위를 정하고, 연결 담당자는 어떤 계층이 값을 채우는지 확인합니다. 업무 책임자는 누락·명시적 빈 값·오류를 각각 어떻게 처리할지 정합니다. 전체 도구 제공 범위는 MCP 서버 구축의 도구·운영 계약에서 먼저 정리할 수 있습니다.
아래 조회 도구와 입력은 가상 표본입니다. 특정 고객의 장애나 특정 MCP 제품의 기본 설정을 설명하지 않습니다. 반환 결과의 스키마와 자연어가 맞는지는 MCP 도구 출력 일치 검수에서 다루며, 여기서는 호출 전 입력 경계에 집중합니다.
default를 선언하면 required도 자동으로 해결되나요?#
보정 없는 검증에서 필수 속성 누락은 그대로 실패합니다. JSON Schema의 default는 기본값을 설명하는 annotation이며, 검증 과정에서 값을 채우는 명령이 아닙니다. 값을 넣는 코드나 옵션이 있다면 그 동작을 별도로 확인합니다.
| 선언 | 확인하는 내용 | 선언만으로 실행되지 않는 것 |
|---|---|---|
| default | 속성에 연결된 기본 JSON 값 설명 | 누락 입력의 자동 대입 |
| required | 속성의 존재 요구 | 기본값 생성·권한 부여 |
| type·minimum·maximum | 값의 형식과 허용 숫자 범위 | 오류 값을 임의의 정상 값으로 교체 |
JSON Schema 공식 annotation 설명은 default가 검증 중 누락 값을 채우지 않는다고 명시합니다. 공식 required 설명도 properties에 나열한 속성이 자동으로 필수인 것은 아니라고 구분합니다. 두 설명의 개별 게시일은 미표기이며 확인일은 2026-10-31입니다.
JSON Schema 2020-12의 default 정의는 메타데이터 어휘에 있습니다. 규격명은 2020-12, 이 문서의 게시일은 2022-06-16이며 Internet-Draft입니다. 오늘 추가된 기능이나 RFC로 소개하지 않습니다.
MCP Tools의 입력 스키마 계약은 inputSchema를 입력용 JSON Schema로 정의하며, $schema를 생략하면 2020-12를 사용합니다. 같은 문서의 서버 요구사항에는 모든 도구 입력 검증이 포함됩니다. 고정판은 2026-07-28, 개별 게시일은 미표기이며 확인일은 2026-10-31입니다.
같은 입력에서 보정 옵션만 바꾸면 어떻게 달라지나요?#
필수 limit가 없는 입력은 보정 여부에 따라 거부되거나 값이 채워질 수 있습니다. 아래는 limit를 정수 1~50, 기본값 20으로 정한 가상 조회 입력 스키마입니다. 이 숫자는 실험용 설정이며 MCP의 공통 기본값이나 실제 업무의 권장 조회량이 아닙니다.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 20
}
},
"required": ["limit"],
"additionalProperties": false
}표는 2026-10-31 알파카랩스가 Ajv2020 8.20.0으로 실행한 제한된 로컬 합성 실험입니다. 각 원본 입력을 새로 복제하고 같은 스키마에서 useDefaults만 false와 true로 바꿨습니다. coerceTypes와 removeAdditional은 모두 false로 고정했습니다.
| 독립 원본 입력 | useDefaults=false: 보정 후·검증 | useDefaults=true: 보정 후·검증 |
|---|---|---|
| {} | limit 없음·실패 | limit:20·통과 |
| limit:null | null 유지·실패 | null 유지·실패 |
| limit:0 | 0 유지·실패 | 0 유지·실패 |
| limit:10 | 10 유지·통과 | 10 유지·통과 |
| limit:문자열 10 | 문자열 유지·실패 | 문자열 유지·실패 |
| limit:빈 문자열 | 빈 문자열 유지·실패 | 빈 문자열 유지·실패 |
첫 행을 제외한 표기는 JSON 속성의 발췌입니다. 실제 도구 호출이나 MCP 메시지 전체를 재현한 표가 아닙니다. 이 실험은 검증기 안의 값과 판정만 확인했으며, 실제 호스트·SDK·서버·API·고객 데이터는 실행하지 않았습니다. 핸들러 전달 여부와 업무 결과는 별도 검수가 필요합니다.
보정 기능이 이미 있다면 무엇을 더 확인하나요?#
보정 주체와 빈 값의 정의, 적용 시점을 확인합니다. 폼·SDK·서버 코드가 값을 채울 수 있으므로 모든 구현이 기본값을 무시한다고 단정하지 않습니다. 원본 입력과 보정 후 값을 구분해야 동작 변경을 발견할 수 있습니다.
Ajv 공식 기본값 대입 설명에서 useDefaults는 누락 속성 등에 값을 대입하는 옵션입니다. 옵션을 "empty"로 설정하면 null과 빈 문자열도 누락으로 취급합니다. 같은 로컬 표본의 이 모드에서는 명시적 null과 빈 문자열이 limit:20으로 바뀌어 통과했습니다. 0과 숫자 문자열은 여전히 거부됐습니다.
Ajv의 데이터 변경 주의사항은 이 기능을 비표준이며 다른 JSON Schema 검증기로 옮길 때 보장되지 않는다고 설명합니다. 문서의 개별 게시일은 미표기, 확인일은 2026-10-31입니다. 실험의 옵션 차이를 모든 MCP 호스트의 동작으로 확대하지 않습니다.
기본값으로 채운 결과가 유효하더라도 사용자가 의도한 조회 조건인지 확인하세요. 명시적 null을 누락으로 바꾸는 정책, 형 변환, 서버의 최대 조회량과 권한을 따로 합의합니다. 데이터 변경 요청에서 null이 삭제를 뜻하는 문제는 SCM 부분 수정의 패치 형식 검수와 구별합니다.
실제 실행 인자까지 어떤 증거를 남기나요?#
같은 표본에 원본 입력·보정 주체·보정값·검증 결과·핸들러 인자를 연결합니다. 거부할 표본은 핸들러에 도달하지 않는지도 확인하세요. 다음 표는 2026-10-31 작성한 자사 인수 제안입니다.
| 경계 | 남길 비식별 증거 | 인수 판단 |
|---|---|---|
| 입력 생성·전송 | 원래 arguments와 속성 존재·값·형 | 모델/화면이 만든 값과 실제 전송값 구분 |
| 입력 보정 | 보정 계층·규칙/옵션·적용 전후 값 | 누락·null·빈 문자열의 합의한 처리 재현 |
| 스키마 검증 | 스키마/검증기 버전·옵션·판정 | 필수 누락·형식·범위 오류의 거부 재현 |
| 핸들러 진입 | 실제 받은 인자와 표본 ID | 검증된 값과 전달값 일치·거부 표본 미실행 |
| 업무·권한 검사 | 서버 허용 범위와 거절 결과 | 형식 통과를 데이터 접근 허가로 해석하지 않음 |
| 호스트·SDK 교체 | 같은 원본 표본의 경계별 재실행 | 보정 책임·최종 인자·거절 조건 차이 발견 |
입력 보정 담당자가 여러 계층에 있으면 어떤 규칙을 기준으로 삼을지 정하고, 한 곳에서 거부한 값을 다른 곳이 조용히 정상 값으로 덮는 경로를 확인합니다. 로그에는 실제 민감 입력을 복사하기보다 비식별 표본 ID와 규칙 버전, 변경 필드와 판정 사유를 남깁니다.
서버는 형식 검증 뒤에도 요청 주체의 데이터 접근 범위와 업무 제약을 확인해야 합니다. 읽기·실행 권한의 전체 경계는 온톨로지 MCP의 조회·실행 설계에서 별도로 다룹니다. default 대입이 조회 권한이나 업무 승인을 부여하지 않습니다.
연동을 의뢰할 때 어떤 자료를 준비하나요?#
비식별 입력 스키마와 같은 표본의 원래 JSON, 기대 실행값과 거부 조건을 준비합니다. 호스트·SDK·검증기 버전과 보정 옵션도 함께 적으세요. 이 자료로 보정 주체와 책임, 인수표 초안을 협의할 수 있습니다.
알파카랩스의 공개 온톨로지·AI 조회 구축 범위는 원천 매핑·출처·권한과 AI·MCP 조회, 검수·운영 인수를 협의한다고 설명합니다. 이는 2026-10-31 확인한 회사 자기표기이며 모든 SDK의 기본값 지원이나 이번 보정 기능의 기본 제공·성과를 보장하지 않습니다. 비용·일정은 자료와 접근 범위를 확인한 뒤 합의합니다.
다음 검토일은 2026-11-30입니다. MCP 규격, 스키마·기본값 정책, 보정 계층·옵션 또는 호스트·SDK가 바뀌면 같은 표본을 먼저 재검수합니다.
MCP 입력 기본값에서 자주 묻는 질문은 무엇인가요?#
- MCP inputSchema에 default를 적으면 누락 입력이 자동으로 채워지나요?
- JSON Schema의 default 선언만으로 누락 값이 자동 대입되지는 않습니다. 폼·SDK·검증기·서버 코드가 따로 보정할 수 있으므로 실제 보정 주체와 설정을 확인하세요. 원본 arguments와 핸들러가 받은 값을 함께 대조합니다.
- required와 default를 함께 쓰면 누락도 검증을 통과하나요?
- 보정 없는 검증에서 required 속성이 빠지면 실패합니다. 기본값을 먼저 채우는 구현에서는 보정한 값이 제약을 만족해 통과할 수 있습니다. default가 required를 해제했다고 해석하지 않습니다.
- null이나 빈 문자열에도 기본값을 적용해도 되나요?
- 명시적 null·빈 문자열과 필드 누락을 같은 뜻으로 취급할지는 업무 계약으로 정합니다. Ajv의 useDefaults=true와 empty 설정도 이 처리에서 다릅니다. 값이 바뀌는 조건과 거부해야 할 입력을 인수표에 남기세요.
- default가 있으면 범위를 벗어난 숫자도 기본값으로 바뀌나요?
- default를 유효성 오류의 만능 대체값으로 해석하면 안 됩니다. 이 글의 정수·최소값 제약과 Ajv 설정에서는 0을 기본값으로 바꾸지 않고 거부합니다. 숫자 문자열의 형 변환도 별도 설정이므로 실제 옵션을 확인하세요.
- 클라이언트가 바뀌어도 스키마 파일만 같으면 되나요?
- 같은 스키마라도 입력 생성·보정 계층이나 검증기 옵션이 달라질 수 있습니다. 같은 비식별 입력으로 원본 값·보정값·거부 결과·실행 인자를 비교하세요. 형식 검증과 데이터 접근 권한·업무 상한도 따로 확인합니다.