Cursor와 Claude에서 MCP 도구를 붙일 때 모델은 이름과 스키마만 보고 호출을 결정합니다. 설명이 모호하거나 파라미터가 느슨하면 인자가 빠지고 호출이 실패합니다. 도구를 지원하는 서버는 capabilities.tools를 선언해야 목록과 호출이 열립니다.
공식 스펙은 서버가 도구를 노출하고 각 도구가 고유 이름과 스키마 메타데이터를 갖는다고 명시합니다. 이 글은 MCP 툴 스키마 작성 순서를 Cursor MCP 연동과 Claude MCP 도구 기준으로 정리합니다. 이름 규칙과 파라미터 타입을 먼저 고정해야 연동이 안정됩니다.
MCP 툴 스키마가 뭔지, 왜 AI 도구 연동에서 핵심인가
MCP 도구는 이름으로 유일하게 식별되며 모델이 호출할 수 있도록 스키마 메타데이터를 함께 제공합니다. 클라이언트가 도구를 찾으려면 tools/list를 보내고 호출하려면 tools/call에 name과 arguments를 넣습니다. arguments는 항상 JSON 객체여야 스키마 검증이 가능합니다.
도구를 지원하는 서버는 capabilities.tools를 선언해야 합니다. 선언한 서버는 tools/list에 현재 도구 집합으로 응답해야 합니다. 스키마가 비어 있으면 모델이 인자를 추측하므로 Cursor MCP 연동과 Claude MCP 도구 모두에서 실패가 잦아집니다.
툴 호출이 실패하는 흔한 원인
이름이 서버 안에서 겹치거나 허용 문자 밖이면 클라이언트가 도구를 고르지 못합니다. 도구 이름은 1자에서 128자이고 대소문자를 구분합니다. 허용 문자는 A-Z, a-z, 0-9와 밑줄, 하이픈, 점뿐입니다.
공백과 쉼표 같은 특수문자는 쓰지 말고 서버 내에서 고유해야 합니다. inputSchema가 없거나 루트 type이 object가 아니면 arguments 객체를 검증하지 못해 호출이 거절됩니다. 파라미터 키가 스키마와 달라도 모델이 임의 필드를 넣어 tools/call이 실패합니다.
필수 필드와 타입: 이름·설명·파라미터를 실사용 기준으로 설계하기
(출처: 에쓰오비 SOB)
도구 정의의 핵심 필드는 name, description, inputSchema입니다. title, icons, outputSchema, annotations는 선택할 수 있으나 호출 계약의 중심은 앞의 세 필드입니다. name은 고유 ID로 쓰고 description은 기능과 사용 시점을 문장으로 적습니다.
inputSchema는 null이 아닌 유효한 JSON Schema 객체여야 합니다. $schema가 없으면 JSON Schema 2020-12가 기본 방언입니다. 도구 인자는 항상 JSON 객체이므로 루트 type은 object여야 합니다.
required와 enum으로 모델이 헷갈리지 않게 하기
파라미터가 없는 도구는 type이 object이고 additionalProperties가 false인 객체를 권장합니다. type만 object로 두면 임의 프로퍼티를 허용하므로 모델이 키를 지어 넣기 쉽습니다. 루트에서 추가 키를 막지 않으면 JSON Schema 도구 정의의 품질이 바로 떨어집니다.
필수 인자는 required 배열에 넣고 허용 값이 정해진 필드는 enum으로 닫습니다. description에는 언제 어떤 값을 넣는지 실사용 문장으로 적습니다. 범위를 이렇게 닫아야 Claude MCP 도구와 Cursor가 선택을 덜 헷갈립니다.
JSON Schema 도구 정의에서 루트 객체와 방언을 고정하는 방법
inputSchema 루트에 type object가 없으면 클라이언트는 인자 객체를 스키마와 맞추지 못합니다. 공식 정의도 루트 type을 object로 두라고 적습니다. null을 넣거나 배열 루트를 쓰면 검증이 성립하지 않습니다.
파라미터가 없는 경우에는 type object와 additionalProperties false 조합을 권장합니다. 같은 뜻으로 type만 적으면 추가 키를 허용합니다. AI 도구 파라미터 설계에서는 허용 키를 properties에만 남기고 나머지를 막아야 합니다. $schema를 둘 때도 2020-12와 맞춰 구 방언 키워드를 섞지 않습니다.
자주 나는 오류와 검증 체크리스트로 스키마 품질 올리기
스키마 품질은 이름 규칙과 루트 타입과 필수 키를 한 번에 맞춰야 올라갑니다. $schema를 생략하면 방언은 2020-12로 해석되므로 구 방언 키워드를 섞지 마십시오. 도구 목록이 바뀌었는데 tools/list 응답이 옛 집합이면 클라이언트는 없는 이름을 호출합니다.
| 점검 항목 | 통과 기준 |
|---|---|
| name | 1자에서 128자, 허용 문자만 사용, 서버 내 고유 |
| inputSchema | null이 아닌 JSON Schema 객체, 루트 type은 object |
| 무파라미터 도구 | additionalProperties를 false로 두는 형태를 권장 |
| 호출 경로 | tools/list로 찾고 tools/call의 arguments에 객체 전달 |
검증 때는 name 길이, 문자 집합, 서버 내 고유성, inputSchema의 object 루트, required와 enum 일치 여부를 순서대로 확인합니다. 표의 항목이 하나라도 빠지면 모델은 인자를 채우지 못하거나 임의 키를 넣습니다. MCP 툴 스키마는 이 점검을 통과해야 Cursor와 Claude에서 같은 방식으로 붙습니다.
Cursor MCP 연동과 Claude에서 목록과 호출 인자를 맞추는 방법
Cursor MCP 연동에서는 서버가 tools capability를 선언했는지부터 봅니다. 선언이 없으면 클라이언트가 도구 목록을 요청해도 지원하지 않는 서버로 취급합니다. Claude MCP 도구도 같은 목록 요청으로 현재 집합을 받습니다.
호출 단계에서는 params.name과 params.arguments를 스키마와 대조합니다. arguments 키가 properties 밖이면 additionalProperties가 false인 도구는 거절됩니다. 이름 대소문자가 다르면 다른 도구로 보이므로 tools/call 전에 문자열을 그대로 맞춰야 합니다.
실무 적용 정리: 바로 쓰는 MCP 툴 스키마 작성 순서
먼저 capabilities.tools를 선언하고 tools/list가 현재 집합을 돌려주는지 확인합니다. 이어서 name, description, inputSchema를 적고 루트 type을 object로 고정합니다. description은 기능만 나열하지 말고 언제 호출하는지를 문장으로 적습니다.
필수 키는 required에 넣고 선택 값은 enum으로 제한한 뒤, 파라미터가 없으면 additionalProperties를 false로 둡니다. 마지막으로 tools/call 인자 객체를 스키마와 대조해 Cursor와 Claude에서 같은 이름이 호출되는지 확인합니다. 이 순서를 지키면 MCP 툴 스키마 작성을 서버에 바로 적용할 수 있습니다.
