AI 개발

Claude Code, Codex 등 AI Coding Agent는 MCP Tools를 어떻게 부르나: JSON-RPC, Tool Schema, 실행 권한 (2026)

약 16분

프로토콜 글은 Schema와 Function Calling의 분담을 이미 썼다. 이 글은 Coding Agent에만 둔다: 모델이 인자를 채우고 호스트가 JSON-RPC를 보낸다. 연결, 목록, Schema, 권한은 네 걸음이지 MCP를 연결하라는 문장이 아니다.

읽기 전 한눈

걸음 무엇을 잠그나 누가 실행하나
설정 .mcp.json / config.toml stdio 또는 http. url에는 type이 필요
발견 tools/list + inputSchema 호스트가 나열. 모델은 전송을 보지 않음
호출 tools/call의 arguments 모델이 JSON을 채우고 호스트가 RPC를 보냄
권한 mcp__server__tool / enabled_tools 연결 ≠ 자동 실행

MCP는 호스트와 서버의 프로토콜. 모델이 보는 것은 도구 이름과 인자 Schema.

MCP를 부르는 것은 호스트이지 모델이 아니다

Claude Code, Codex, Cursor는 MCP 클라이언트다. 세션이 시작되면 호스트가 서버에 붙고 JSON-RPC 2.0 tools/list를 보내 각 도구의 inputSchema를 모델에 넘긴다. 모델이 내는 것은 인자 JSON뿐이다. tools/call을 보내고 부작용을 돌리는 것은 호스트다. 그 홉이 없으면 MCP는 설정 파일일 뿐이다.

  • 설정: 서버를 어떻게 켜나. stdio는 로컬 프로세스. http는 원격. 둘 다 객체이지 구두 약속이 아니다.
  • Schema: order_id는 inputSchema를 통과해야 한다. 넓은 object는 키 발명을 부른다.
  • 권한: Claude는 mcp__서버__도구로 규칙을 쓴다. Codex는 enabled_tools와 승인 모드. Cursor는 mcpAllowlist. 서버를 연결했다고 문이 열린 것은 아니다.

프로토콜 층의 Schema와 Function Calling은 MCP Tool Schema vs Function Calling. Coding Agent 자신의 도구 JSON은 AI Coding Agent와 JSON 도구 호출. Schema가 문인 이유는 AI에 JSON Schema가 필요한 이유. 이 글은 그 단어를 다시 정의하지 않는다. 호스트가 MCP를 돌리는 법만 쓴다.

첫 객체: 서버 설정

Claude Code의 프로젝트 설정은 저장소 루트의 .mcp.json이다. 버전 관리에 넣을 수 있다. 로컬 전용은 ~/.claude.json. url에는 type이 필요하다. http(streamable-http는 별칭) 또는 sse / ws. url만 있고 type이 없으면 공식은 깨진 stdio로 보고 건너뛴다. 가상 주문 서비스. 실제 비밀은 붙이지 마라:

{
  "mcpServers": {
    "orders": {
      "type": "stdio",
      "command": "node",
      "args": ["./servers/orders-mcp.js"]
    }
  }
}

Codex는 같은 사실을 ~/.codex/config.toml 또는 신뢰한 프로젝트의 .codex/config.toml에 쓴다. 표는 [mcp_servers.orders]. stdio는 command / args. 원격은 url. Cursor는 .cursor/mcp.json 또는 사용자 파일. 편집기와 CLI가 공유한다. 프로젝트에 새로 나타난 서버는 Claude Code에서 승인 대기로 멈춘다. 자동으로 붙지 않는다.

둘째 객체: tools/list와 inputSchema

붙은 뒤 호스트는 먼저 도구를 묻는다. 이것은 JSON-RPC이지 모델이 직접 보내는 HTTP가 아니다:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

서버는 표를 되돌린다. 각 행은 이름, 설명, JSON Schema. 규격은 tools 능력 선언을 요구한다. 목록은 인가에 따라 바뀔 수 있다. 연결마다 흔들리면 안 된다. Coding Agent는 그 표를 모델이 보는 도구로 바꾼다. Claude Code의 호출 이름은 mcp__orders__lookup_order. 플러그인 서버는 플러그인 이름도 끼운다. 도구가 많으면 공식 클라이언트는 지연 로드하고 검색으로 펼친다. 표 전체를 기본으로 문맥에 넣지 마라.

{
  "name": "lookup_order",
  "description": "Look up an order by ID. Confirm before any refund.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string", "pattern": "^[A-Z]-\\d{4}$" }
    },
    "required": ["order_id"],
    "additionalProperties": false
  }
}

셋째 객체: 모델이 채우고 호스트가 tools/call

모델이 보는 것은 호스트가 공개한 이름이다. Claude Code 세션에서 호출은 이렇게 보인다:

{
  "type": "tool_use",
  "id": "call_3c91",
  "name": "mcp__orders__lookup_order",
  "input": { "order_id": "A-1042" }
}

호스트는 input을 inputSchema에 맞춘 뒤 서버로 보낼 RPC로 옮긴다. 선의 이름은 등록명 lookup_order이지 mcp__ 접두가 아니다:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "lookup_order",
    "arguments": { "order_id": "A-1042" }
  }
}

성공이면 content를 되돌린다. 실패면 isError를 참으로 두고 이유를 객체로 쓴다. 산문 한 줄만 버리지 마라. 모델이 읽는 것은 되돌림이지 소켓이 아니다.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{\"order_id\":\"A-1042\",\"status\":\"paid\"}" }
    ],
    "isError": false
  }
}

넷째 객체: 실행 권한

MCP 규격은 도구 호출을 거절할 수 있어야 한다고 쓴다. Coding Agent는 그 거절을 규칙으로 쓰지 프롬프트로 쓰지 않는다. Claude Code는 전체 호출 이름을 쓴다:

{
  "permissions": {
    "allow": ["mcp__orders__lookup_order"],
    "ask": ["mcp__orders__create_note"],
    "deny": ["mcp__orders__refund_order"]
  }
}

공식 순서는 여전히 deny, ask, allow. 맨 mcp__* deny는 MCP를 문맥에서 뺀다. Codex는 enabled_tools를 허용 목록, disabled_tools를 뒤이은 거부 목록으로 쓰고 기본 승인은 auto / prompt / approve이며 도구마다 덮을 수 있다. Cursor는 기본으로 매번 묻는다. permissions.json의 mcpAllowlist는 orders:lookup_order로 쓴다. Shell / Git / 파일 세 문은 Coding Agent 권한 모델. MCP는 넷째 표이지 그 세 문의 대체가 아니다.

MCP를 객체로 담는 다섯 걸음

MCP를 연결하라는 문장에서 시작하지 마라. 객체를 쓴다:

  1. 먼저 서버 설정을 쓴다. stdio 또는 http를 고른다. url에 type. 비밀은 환경 변수. 저장소에 넣지 마라.
  2. 직접 tools/list를 돌린다. 이름과 required를 적는다. Schema 없는 도구는 모델에 주지 마라.
  3. inputSchema를 조인다. pattern, enum, additionalProperties: false. 조회에 환불 키를 늘리지 마라.
  4. 도구마다 권한을 쓴다. 읽기 조회는 allow. 쓰기는 ask. 환불은 deny. Codex는 먼저 enabled_tools로 표를 자른다.
  5. 성공한 한 번을 JSON 세 줄로 남긴다: tool_use, tools/call, result. 맞으면 통했다.

Schema를 문으로 쓰는 이야기는 Agents API + JSON Schema. 이 글이 요구하는 것은 Coding Agent에서 MCP의 각 걸음이 객체이고 호스트가 보낸다는 것이다.

MCP 이탈을 되짚으려면 JSON 세 줄을 펼친다

실패한 호출의 대부분은 이름, Schema, 권한이 어긋난 것이다. 모델이 MCP를 못 부르는 것이 아니다.

  • inputSchema와 arguments를 포맷하고 빠진 칸과 여분 키를 본다.
  • JSONPath 추출로 $.params.name과 $.input.order_id를 뽑는다.
  • 통과한 호출과 거절된 호출을 JSON Diff. 규칙과 Schema를 먼저 고치고 프롬프트는 나중.
  • 호스트 이름 mcp__orders__lookup_order와 RPC 이름 lookup_order를 맞춘다. 플러그인 서버는 플러그인 구간도 필요하다.
  • 설정, 토큰, 세션 로그를 공개 포맷터에 붙이지 마라. JSONSort는 브라우저에서 로컬로 돈다.

세 궤적이 Schema로 다시 세워져야 MCP를 모은 것이다. 아니면 연결을 눌렀다를 모은 것이다.

흔한 함정

  • 연결되면 호출된다고 본다. 연결은 프로세스나 HTTP가 통했다는 뜻이다. list, Schema, 권한이 없으면 모델은 아직 부르지 못한다.
  • MCP를 Function Calling으로 본다. 모델에게는 둘 다 JSON을 채우는 일이다. 호스트에게는 MCP가 JSON-RPC 홉을 하나 더한다. 프로토콜 글이 단어를 나눴다. 여기서는 그 홉만 보면 된다.
  • url에 type을 안 쓴다. Claude Code는 깨진 stdio로 건너뛴다. 원격 서버가 사라진다.
  • 서버만 넣고 도구를 자르지 않는다. 큰 표가 문맥에 들어간다. 공식 지연 로드와 enabled_tools가 있는 이유다.
  • 모든 MCP를 자동 승인하라는 문장을 기본으로 둔다. Cursor의 일괄 승인, Claude bypass, Codex 전부 auto는 격리 환경용이다. 일상은 도구마다 쓴다.
  • 프로젝트 .mcp.json을 로컬 비밀로 본다. 버전 관리에 들어간다. 다른 사람은 승인 대기를 본다. 비밀은 사용자 범위 설정에 둔다.

FAQ

Coding Agent가 스스로 JSON-RPC를 보내나?

아니다. 모델은 도구 이름과 arguments만 채운다. id, method, params는 호스트가 만든다. 로그의 tools/call은 클라이언트이지 모델이 아니다.

inputSchema와 권한 중 어느 것이 먼저인가?

모양이 먼저, 실행이 나중. Schema가 실패하면 RPC를 보내지 않는다. 통과해도 ask나 deny는 날 수 있다. 잠그는 것이 다르다.

stdio와 http 중 무엇을 고르나?

로컬 파일이나 프로세스면 stdio. 호스팅 서비스면 http. Claude Code는 원격에 http를 권한다. SSE는 옛것이다. WebSocket은 서버가 사건을 밀어 줄 때 맞다.

도구가 너무 많으면?

Claude Code는 MCP 도구를 미뤘다가 검색으로 펼 수 있다. Codex는 enabled_tools로 표를 자른다. 쉰 개를 한 세션에 넣지 마라.

Subagent가 이 MCP를 쓰나?

제품마다 다르다. Claude Code의 권한과 allowed-tools는 전체 호출 이름이 필요하다. Agents API 하위 에이전트는 MCP를 이어받고 function은 이어받지 않는다. 한 표가 모든 자식 세션에 복사된다고 가정하지 마라.

결론

Coding Agent의 MCP 호출은 모델이 서버를 치는 것이 아니다. 호스트가 도구를 나열하고 모델이 JSON을 채운 뒤 호스트가 tools/call한다. Schema와 권한은 두 문이다.

A-1042가 어느 도구 이름, 어느 Schema, 어느 권한 규칙을 지나는지를 먼저 쓴다. 객체 셋을 가리킬 수 있으면 MCP는 통했다. 모델은 바뀐다. 셋을 먼저 안정시킨다.

더 읽기

변경 기록: 최초 게시