도구 호환성 확보: 하나의 커스텀 MCP 도구를 작성하여 어디에나 배포하기

AI 코딩 환경 전반에서 진정한 도구 호환성 (Tool Parity)을 달성하는 것은 더 이상 이론적인 과제가 아닙니다. Model Context Protocol (MCP)을 통해 단 하나의 커스텀 도구 설정만으로 Claude Code, Cursor, Codex, Gemini CLI, Copilot, 그리고 Windsurf 내에서 원활하게 작동하도록 만드는 방법을 알아보세요. 이를 통해 중복된 설정을 제거하고 개발 워크플로우를 가속화할 수 있습니다.

파편화된 도구 환경의 문제점

오늘날의 개발 환경은 AI 도구 선택의 문제로 인해 파편화되어 있습니다. Cursor, Windsurf, GitHub Copilot과 같은 다양한 옵션이 있다는 것은 유익하지만, 이는 상당한 유지보수 부담을 초래합니다. 만약 여러분이 회사의 배포 API를 감싸는 래퍼(wrapper)와 같은 커스텀 내부 도구를 구축한다면, 종종 6개의 서로 다른 통합 스크립트, 설정 파일, 그리고 인증 흐름을 유지보수해야 하는 상황에 직면하게 됩니다. Claude Code용 하나, Gemini CLI용 하나, 그리고 Cursor 확장 프로그램용 별도의 하나가 필요하게 되는 식입니다. 이러한 **도구 호환성 (Tool Parity)**의 부재는 제품이 아닌 인프라 구축(plumbing)에 시간을 낭비하게 만듭니다.

핵심 문제는 각 "하네스 (harness)" 또는 AI 코딩 환경이 도구를 발견하고, 인증하고, 호출하는 각자만의 독자적인 방식을 가지고 있다는 점입니다. 그 결과, 하나의 강력한 유틸리티가 특정 에디터 안에 갇혀 다른 에디터에서는 사용할 수 없는 고립된 생태계가 만들어집니다. 개발자들에게 필요한 것은 보편적인 계약(universal contract), 즉 어떤 AI 하네스라도 수정 없이 이해하고 실행할 수 있는 도구 정의 표준입니다.

MCP의 장점: 보편적인 도구 계약

Model Context Protocol (MCP)은 바로 이러한 계약을 제공합니다. MCP 도구는 단일 에디터를 위한 플러그인이 아닙니다. 이는 타입이 지정된 인터페이스 (typed interface)를 노출하는 독립적인 서버입니다. 여러분의 도구는 단 하나의 설정 파일과 코드베이스 내에서 한 번만 정의됩니다. MCP를 지원하는 AI 하네스들은 클라이언트 역할을 수행하며, 이 공유된 계약을 바탕으로 여러분의 도구를 자동으로 발견하고 호출합니다.

이것을 AI 에이전트를 위한 REST API를 구축하는 것이라고 생각하면 됩니다. 여러분은 엔드포인트(도구의 함수들)와 그 스키마 (schema)를 정의합니다. 여러분의 IDE에서 실행되는 에이전트든 CLI 도구든, 규약을 준수하는 클라이언트라면 무엇이든 해당 엔드포인트를 호출할 수 있습니다. 이러한 아키텍처는 즉각적인 도구 일관성 (tool parity) 을 제공합니다. 여러분의 "스테이징 배포 (Deploy to Staging)" 도구를 위한 설정은 단 한 번만 작성하면 되며, 전체 생태계에서 동일하게 작동합니다.

첫 번째 범용 도구 구축하기: 실전 가이드

구체적인 예시를 만들어 보겠습니다. 공공 API를 사용하여 특정 위치의 악기상 경보를 가져오는 weather-alert라는 이름의 커스텀 MCP 도구를 구축해 보겠습니다. 이 도구는 수정 없이 여섯 가지 환경 모두에서 사용할 수 있습니다.

1단계: MCP 서버 생성. TypeScript와 공식 MCP SDK를 사용하겠습니다. 핵심은 명확한 도구 스키마 (tool schemas) 를 정의하고 로직을 구현하는 것입니다.

// weather-alert-server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
...

2단계: MCP 설정 선언. 이것이 마법의 파일입니다. 프로젝트 루트에 mcp.json 파일을 배치합니다. 이 단일 파일이 모든 하네스 (harness) 가 읽게 될 파일입니다.

// mcp.json
{
  "servers": {
...

도구 개발은 이것으로 끝입니다. 이 설정은 weather-alerts라는 이름의 서버, 서버를 시작하는 방법, 그리고 필요한 환경 변수 (environment variables) 를 선언합니다. 도구 자체인 getSevereAlerts는 클라이언트가 연결될 때 동적으로 발견됩니다.

여섯 가지 하네스 전체에 걸친 통합: 설정 변경 제로

이제 이 단일 mcp.json 파일이 어떻게 여러분의 도구에 전체 환경에 걸친 일관성을 부여하는지 살펴보겠습니다. 다음 통합 과정들은 여러분의 도구 설정을 변경할 필요가 없으며, 각 하네스의 설정에서 단 한 번의 활성화만 필요합니다.

1. Claude Code: 프로젝트 루트에서 mcp.json을 자동으로 읽습니다. 여러분이 Claude에게 "텍사스의 심각한 기상 상황을 확인해줘"라고 프롬프트를 입력하면, Claude는 사용 가능한 도구 목록에서 getSevereAlerts 도구를 확인하고 이를 직접 호출합니다. 환경 변수를 통한 인증은 세션에서 처리됩니다.

2. Cursor: MCP를 네이티브로 지원합니다. Settings > Features > Model Context Protocol에서 프로젝트 루트를 지정하세요. 이제 Cursor의 AI 사이드바와 인라인 완성(inline completions) 기능은 weather-alerts 서버를 마치 내장 확장 기능인 것처럼 활용할 수 있습니다. 도구의 도움말 텍스트와 스키마(schema)는 인라인 제안에 사용됩니다.

3. Codex (OpenAI): Codex CLI와 그 생태계는 mcp.json을 가리키는 --mcp-config 플래그를 사용하여 클라이언트를 시작함으로써 MCP 도구를 활용할 수 있습니다. 이 도구는 Codex 모델의 함수 호출 (function-calling) 어휘의 일부가 됩니다.

4. Gemini CLI: Google의 CLI 도구는 설정에 정의된 MCP 서버를 지원합니다. mcp.json에 대한 참조를 추가하거나 서버 정의를 복사함으로써 Gemini 에이전트가 접근 권한을 얻게 됩니다. 여러분은 "플로리다의 모든 'extreme' 경보를 가져와줘"라고 요청할 수 있으며, 에이전트는 여러분의 도구를 사용하게 됩니다.

5. GitHub Copilot: Copilot Extensions API를 통해 MCP 서버를 확장 기능으로 등록할 수 있습니다. 조직(organization) 설정에 등록되면, VS Code나 github.com을 사용하는 모든 Copilot 사용자가 채팅창의 자연어를 통해 여러분의 도구와 상호작용할 수 있습니다.

6. Windsurf: Windsurf의 Cascade AI는 깊이 있는 MCP 지원을 바탕으로 구축되었습니다. 열려 있는 워크스페이스의 mcp.json을 자동으로 파싱합니다. weather-alerts 도구는 계획된 배포 전에 날씨를 자동으로 확인하는 것과 같은 에이전트 워크플로 (agentic workflows)에서 Cascade가 즉시 사용할 수 있게 됩니다.

프로덕션급 동등성을 위한 고급 고려 사항

도구가 모든 환경에서 견고하게 작동하도록 하려면, 다음과 같은 프로덕션 패턴 (production patterns)을 고려하십시오. 첫째, **버전 관리 (versioning)**가 매우 중요합니다. 도구의 스키마 (schema)에 version 필드를 포함하십시오. Cursor와 같은 클라이언트들은 이를 사용하여 스키마를 캐싱 (caching)하고 중대한 변경 사항 (breaking changes)을 방지할 것입니다. 둘째, **견고한 에러 핸들링 (robust error handling)**은 타협할 수 없는 필수 사항입니다. MCP 서버에서 명확하고 구조화된 에러를 반환하십시오. 하네스 (harnesses)는 이를 파싱 (parse)하여, Claude Code에서의 401 Unauthorized이든 Gemini CLI에서의 연결 시간 초과 (connection timeout)이든 상관없이 사용자에게 일관된 방식으로 제시할 것입니다.

마지막으로, **보안 (security)**은 균일해야 합니다. 우리의 mcp.json에 있는 ${NOAA_API_KEY} 변수는 참조용입니다. 각 하네스는 비밀 정보 (secrets)를 안전하게 주입하기 위한 자체적인 메커니즘(예: Cursor의 .env, Claude Code의 셸 환경)을 가지고 있습니다. 귀하의 도구 설정은 중립적으로 유지되며, 비밀 정보는 하네스 수준에서 관리되어 보안과 동등성 (parity)을 모두 유지합니다.

동일한 도구를 여섯 가지 버전으로 작성하는 일을 멈추십시오. 진정한, 노력이 필요 없는 도구 동등성을 달성하기 위해 Model Context Protocol을 수용하십시오. 오늘 바로 https://tormentnexus.site에서 첫 번째 범용 MCP 도구 구축을 시작하세요.

원문 게시지: tormentnexus.site