만약 공식 레지스트리에 MCP(Model Context Protocol) 서버를 게시했거나 게시하려고 시도했다면, 여러분은 server.json과 그것에 의해 조용히 거부당하는 유효성 검사를 경험했을 것입니다. 스키마 자체는 작지만, 소수의 실수가 대부분의 실패 원인을 차지합니다. 현재 레지스트리 스키마(2025-12-11)를 기준으로 확인한 오류들은 다음과 같습니다.
사람들이 실제로 실수하는 부분들
설명(description)이 너무 깁니다. description 필드는 100자로 제한됩니다. 마케팅 문단 전체가 가장 흔한 거절 사유입니다. 간결한 한 문장으로 작성하세요.
최상위 레벨에 version이 없습니다. 최상위(top-level)의 version 필드는 필수이며, 이는 패키지의 버전과는 별개입니다. 패키지 버전을 설정하고 서버 버전을 잊어버리기 쉽습니다.
transport가 없는 패키지 항목. packages 배열의 모든 항목에는 transport가 필요합니다. 로컬 stdio 서버를 사용하는 경우에도 마찬가지입니다:
{ "registryType": "npm", "identifier": "@you/server", "transport": { "type": "stdio" } }
사람들은 HTTP 원격(remote)을 위해 이 필드를 추가하지만, stdio 패키지에는 빠뜨리는 경우가 있습니다.
version이 "latest" 또는 범위로 되어 있습니다. 패키지 버전은 구체적이어야 합니다. "latest"는 명시적으로 거부되며, ^1.2.3와 같은 범위(range)도 권장되지 않습니다. 버전을 고정(pin)하세요.
name의 형식이 잘못되었습니다. 이름은 정확히 슬래시(/) 하나를 포함해야 하며, 역방향 DNS 스타일이어야 합니다: io.github.you/my-server. my-server나 슬래시가 두 개인 형식은 안 됩니다.
type과 url 둘 다 없는 원격(remote) 항목. remotes 배열의 각 항목에는 type(streamable-http 또는 sse)과 url이 모두 필요합니다.
snake_case 필드 사용. 스키마는 이제 camelCase를 사용해야 합니다. 즉, registry_type가 아니라 registryType을 사용해야 하며, websiteUrl, packageArguments, environmentVariables도 마찬가지입니다. 또한 status 필드는 더 이상 존재하지 않습니다. 오래된 예시를 복사했다면 이 필드를 삭제하세요.
최소한의 유효한 server.json
최상위 레벨에서는 name, description, 그리고 version만 필수입니다:
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
"name": "io.github.you/weather",
...
}
좋은 점은 스키마가 *관대하다(permissive)*는 것입니다. additionalProperties: false 설정이 없기 때문에 추가하는 필드는 괜찮고 유효성 검사에 실패하지 않습니다.
게시 전에 확인하기
스키마를 직접 읽는 대신, 저는 무료 server.json validator를 만들었습니다. 여기에 본인의 파일을 붙여넣으면 (아무것도 업로드되지 않음), 공식 레지스트리 스키마와 브라우저에서 바로 유효성 검사를 수행하며, 수정해야 할 항목을 일반 영어로 목록화하여 보여줍니다. 이것은 MCP 서버 디렉토리인 Serverdex의 일부입니다.
server.json이 유효하고 레지스트리에 게시한 후에는, 사람들이 찾을 수 있도록 서버를 Serverdex에 등록(list)할 수도 있습니다.