[번역] 나만의 MCP 서버 구축 방법

원문: https://www.builder.io/blog/mcp-server

저는 여러분과 마찬가지로 AI 모델(갑작스러운 Gemini 출시 같은 것)과 클라이언트(커서, 윈드서프, 다시 커서—아니, 잠깐!)를 자주 바꿔가며 사용하고 있습니다.

저를 가장 답답하게 하는 것은 컨텍스트의 손실입니다. 저는 AI에게 제 문제에 대해 알아야 할 것들을 계속 설명하고, AI가 "제 스타일"대로 작업하도록 노력합니다.

하지만 만약 이러한 컨텍스트가 이식 가능하다면 어떨까요? 클로드 데스크톱에서 질문하고 답변을 받은 다음, 나중에 커서에서 코딩할 때 그 대화를 다시 불러올 수 있다면 어떨까요?

이 글에서는 몇 가지 간단한 단계로 필요한 도구를 함께 만들어 바로 그렇게 해보겠습니다. 최종 결과물은 다음과 같습니다.

사진을 클릭하면 동영상 페이지로 이동합니다.

이 예제 프로젝트의 전체 코드는 여기에서 확인할 수 있으며 클론해서 따라해 보세요. 이 튜토리얼이 끝날 때쯤이면 여러분만의 작은 꿈의 서버를 만들 수 있게 되는 것이 목표입니다.

MCP가 왜 필요할까요?

위에 보이는 것은 아마도 이 글의 48px 제목과 경계선을 넘나드는 키워드 최적화에서 짐작하셨듯이, 모델 컨텍스트 프로토콜(MCP) 서버입니다.

MCP에 대해 이미 모두 알고 있고 바로 구축하고 싶다면, 이 섹션을 건너뛰고 "빠른 시작"으로 이동해도 좋습니다. 그렇지 않다면, 스톱워치를 설정하고 3분짜리 입문서를 읽어보세요.

1. MCP는 왜 존재할까요?

자율적인 AI 에이전트를 원한다면, 에이전트가 주변 세계를 보고 상호작용할 수 있게 해주는 도구가 필요합니다. 안타깝게도, AI 어시스턴트를 도구에 직접 연결하면 통합이 취약해지고 도구의 한쪽에서 AI 모델이나 API를 업데이트하면 코드가 깨질 수 있습니다.

그렇다면 어떻게 더 견고하고 재사용 가능한 AI 기능을 구축할 수 있을까요?

한 가지 방법은 앤트로픽의 모델 컨텍스트 프로토콜(MCP)을 이용하는 것입니다. 이는 AI 클라이언트(커서와 같은)가 MCP 서버가 제공하는 외부 기능을 발견하고 사용할 수 있게 해주는 표준화된 통신 계층(JSON-RPC 기반)입니다.

이러한 기능에는 영구 데이터 액세스(Resources), 외부 세계에서 다양한 작업 수행(Tools), 그리고 이러한 리소스와 도구를 사용하는 방법에 대한 특정 지침(Prompts) 기능들이 포함됩니다.

MCP의 목표, 아키텍처 및 잠재력에 대한 자세한 내용은 제 심층 분석에서 확인할 수 있습니다.

좋습니다...그런데..

2. MCP 서버를 사용하는 이유는 무엇인가요?

커서와 윈드서프 같은 클라이언트들은 이미 MCP 없이도 훌륭한 AI 에이전트를 보유하고 있습니다. 그렇다면 왜 더 많은 도구가 필요할까요?

간단히 말해서, 클라이언트 개발자들은 모든 기능을 구현할 수 없기 때문입니다. 이들은 새로운 모델이 출시될 때마다 웹 검색 기능을 최적화하는 데 개발 시간을 소모하길 원치 않으며, 자체적인 지라 통합 기능을 개발하려고 시도하지도 않습니다.

MCP를 사용하면 깃허브나 노션 같은 서비스 제공업체가 자체 AI 통합을 유지할 수 있으므로 더 높은 품질의 상호작용과 중복된 노력을 줄일 수 있습니다.

따라서 MCP 서버를 사용하기로 선택하면 미래 대비와 이식성이라는 주요 이점을 얻을 수 있습니다. 표준을 구현하는 모든 채팅 창에 가져올 수 있는 플러그 앤 플레이 도구의 거대한 에코시스템을 이용할 수 있게 됩니다.

알겠습니다...그런데..

3. 자신만의 MCP 서버를 구축하는 이유는 무엇인가요?

자체 서비스 API를 MCP에 연결해야 하는 개발자가 아니더라도, 이 노하우를 갖는 것에는 많은 이점이 있습니다.

제 경우에는 서버 구축에 더 많은 시간을 할애할수록 입력 상자 사이에 엄청난 양의 텍스트를 복사/붙여넣기만 하는 일이 줄어든다는 것을 느꼈습니다. 저는 컨텍스트를 자동화하고 있으며, 이를 통해 AI 모델을 더 개인적으로 유용하게 활용할 수 있습니다.

또한, 끊임없이 변화하는 AI 환경에서 한 발짝 더 나갈 수 있는 방법이기도 합니다. 지금 구축한 도구는 새로운 모델, 클라이언트 및 서비스가 등장해도 계속 작동해야 합니다.

하지만 이제 시적인 이야기는 충분하고, 본격적으로 시작해 볼 시간입니다.

빠른 시작: 바이브 코딩?

솔직히 말씀드리자면, MCP 문서를 AI 에이전트에게 전달하고 원하는 기능을 알려주기만 하면 아마도 잘 작동할 것입니다. 이런 종류의 코드는 AI가 특히 능숙하게 처리할 수 있습니다.

진행하면서 MCP 인스펙터를 사용하면서 계속 오류를 AI에게 피드백하세요. 그리고 AI 에이전트를 최대한 활용하기 위해 커서 팁을 확인해보세요.

또한, 확장 가능한 AI 도구를 구축하기 위해 아키텍처가 어떻게 작동하는지 배우고 싶은 분들을 위한 분석이 여기 있습니다.

빠른 시작: 클론, 설치, 빌드

이 세 단계로 코드베이스를 준비해 보겠습니다. 아직은 API 키나 클라이언트 설정에 대해 걱정하지 않아도 됩니다.

1. 저장소 클론: 예제 코드를 로컬 머신에 가져옵니다.
2. 의존성 설치: MCP SDK와 몇 가지 다른 라이브러리가 필요합니다.
3. 코드 빌드: 타입스크립트 소스 코드를 실행 가능한 자바스크립트로 컴파일합니다.

이제 build/ 디렉토리에 컴파일된 코드가 있습니다.

OpenRouter API 키를 가져와서 "실제 클라이언트로 서버 실행하기"로 바로 이동하고 싶다면 그렇게 해도 좋습니다. 서버는 있는 그대로 작동할 것입니다.

핵심 루프: 첫 번째 서버 실행하기

CSS 튜터 예제의 구체적인 기능에 대해 자세히 알아보기 전에, 타입스크립트 SDK로 구축한 MCP 서버의 기본 구조를 확실히 이해하고 최소한의 버전을 실행해 봅시다.

핵심 구조 (src/index.ts)

메인 서버 파일인 src/index.ts를 열어보세요. 다음과 같은 주요 부분을 볼 수 있습니다.

• 임포트: 이 파일은 @modelcontextprotocol/sdk에서 McpServer(핵심 서버 클래스)와 StdioServerTransport(통신용)를 가져옵니다.
• 등록 임포트: src/ 디렉토리에 있는 다른 파일에서 registerPrompts, registerResources, registerTools를 가져옵니다. 추후 살펴 볼 이 함수들은 서버에게 우리가 제공하고자 하는 특정 기능을 알려주는 역할을 합니다.
• 서버 인스턴스화: 서버 이름과 버전을 설정하고 서버의 기능을 위한 빈 자리 플레이스 홀더를 초기화하여 서버 인스턴스를 생성합니다.
• 등록 함수 호출: 가져온 register* 함수들이 호출됩니다. 이러한 호출은 서버 인스턴스에 다른 곳에 정의된 실제 도구, 리소스 및 프롬프트를 채웁니다.
• main 함수: 이 비동기 함수는 통신 전송을 설정하고 서버를 연결합니다.
• 실행: 마지막으로, 기본 오류 처리와 함께 main()이 호출됩니다.

이 구조는 서버의 핵심입니다. 초기화하고, 기능을 등록하고, 통신을 위해 연결합니다.

최소한의 서버 만들기 (임시 변경)

외부 API나 복잡한 로직 없이도 이 핵심 루프가 작동하는지 확인하기 위해, src/index.ts를 임시로 수정해 보겠습니다.

1. 기능 등록 호출을 주석 처리합니다.
2. main 함수 정의 바로 앞에 간단한 "hello" 도구를 추가합니다.
3. 코드를 다시 빌드합니다.

이렇게 src/index.ts를 변경하는 것만으로, 이제 하나의 기본 도구만 제공하는 실행 가능한 MCP 서버가 생겼습니다. 아직은 Empire Strikes Back 스포일러를 제공하는 것 외에는 별다른 기능이 없지만, 핵심 구조와 통신 설정이 제대로 작동하는지 확인할 수 있습니다.

MCP 인스펙터로 디버깅하기

이제 실행 가능한 최소한의 서버가 있으니, 실제로 서버가 MCP를 올바르게 사용하고 있는지 어떻게 확인할 수 있을까요? 앤트로픽의 MCP 인스펙터를 사용하면 됩니다.

사진을 클릭하면 동영상 페이지로 이동합니다.

이 커멘드라인 유틸리티는 기본 MCP 클라이언트 역할을 합니다. 서버 프로세스를 시작하고, 표준 I/O를 통해 연결하며(클로드 데스크톱이나 커서처럼), 교환되는 JSON-RPC 메시지를 보여줍니다.

인스펙터 실행하기

프로젝트의 루트 디렉토리에서 다음 명령어를 실행하세요.

npx @modelcontextprotocol/inspector node ./build/index.js

• npx ...inspector: 인스펙터 패키지를 다운로드하고 실행합니다.
• node: 서버를 실행하는 명령입니다.
• ./build/index.js: 컴파일된 서버 진입점의 경로입니다.

표시되는 내용

인스펙터가 시작되고, 서버에 연결되며 메시지 교환을 시작합니다. 로컬 호스트 URL로 이동하면 다음과 같이 해당 서버와 상호작용할 수 있습니다.

1. 연결: 연결을 확인하는 initialize 메시지가 표시됩니다.
2. 도구 목록: 인스펙터의 인터페이스를 사용하여 서버가 제공하는 도구를 물어봅니다. hello_world 도구만 나열되어 있어야 합니다.
3. 리소스/프롬프트 목록: 만약 리소스나 프롬프트 탭으로 이동하려고 하면, 등록을 주석 처리했기 때문에 클릭할 수 없을 것입니다.
4. 도구 호출: 인스펙터를 사용하여 hello_world 도구를 호출합니다. 서버가 우리의 사용자 정의 메시지로 응답하는 것을 볼 수 있습니다.

MCP 인스펙터는 개발 중에 가장 좋은 친구입니다. 기능(도구, 리소스 또는 프롬프트)을 추가하거나 수정하는 각 단계 후에, 서버가 올바르게 등록되고 예상대로 응답하는지 확인하세요. 인스펙터를 사용하면 전체 AI 클라이언트를 사용하지 않고도 서버 기능을 테스트할 수 있습니다.

버디 시스템을 사용하세요. 어디를 가든, MCP 인스펙터가 함께합니다.

(^ 여러분과 MCP 인스펙터의 실시간 장면입니다.)

실제 기능 구축하기

이제 기본 서버를 실행하고 인스펙터로 디버깅하는 방법을 알았으니, 이제 간식을 가져오고, 본격적으로 실제 CSS 튜터 기능을 점진적으로 추가해 봅시다.

진행하면서 기능을 자유롭게 조정해 보세요. 모든 코딩 기술을 환영합니다!

1단계: "업데이트 가져오기" 도구 (get_latest_updates)

먼저, 외부 정보를 가져오는 도구를 활성화하고 이해해 봅시다.

도구 등록 활성화

src/index.ts에서 앞서 추가한 더미 hello_world 도구 정의를 제거하고 registerTools(); 줄의 주석 처리를 해제합니다. 이 줄은 모든 도구를 등록하는 src/tools/index.ts의 함수를 호출합니다.

export const server = new McpServer({
  name: "css-tutor",
  version: "0.0.1",
  capabilities: {
    prompts: {},
    resources: {},
    tools: {},
  },
});

// registerPrompts();
// registerResources();
registerTools();

// dummy tool 제거

async function main(); // 나머지 코드

도구 코드 이해하기

이제 src/tools/index.ts를 열고 registerGetLatestUpdatesTool 함수를 찾습니다. 여기에서 get_latest_updates 도구가 정의되고 서버에 등록됩니다.

이 파일 안에는 몇 가지 중요한 일이 일어나고 있습니다.

1. 구성 및 안전 점검: dotenv를 사용해 환경 변수를 로드하며, 특히 OPENROUTER_API_KEY를 찾습니다. 키가 누락된 경우, 경고를 기록하고 등록을 건너뛰어 서버가 작동하지 않는 도구를 제공하지 못하게 합니다.
2. 도구 등록: server.tool()을 사용하여 get_latest_updates 도구를 등록합니다. 여기에는 이름, AI 클라이언트에 대한 설명, 입력 스키마(이 경우 인수를 받지 않으므로 {})를 정의하는 것이 포함됩니다.
3. 핵심 로직 (핸들러): 핵심 로직은 server.tool()에 전달되는 비동기 핸들러 함수에 있습니다. 이 핸들러는 다음을 담당합니다.
4. 활성화: 마지막으로, 파일 하단에 있는 기본 registerTools 함수는 서버가 시작될 때 registerGetLatestUpdatesTool()이 호출되도록 합니다.

빌드

변경 사항을 컴파일하세요.

npm run build

테스트를 위한 API 키 구성

인스펙터로 이 도구를 테스트하려면 서버 프로세스에 API 키가 필요합니다. 인스펙터 명령 앞에 접두사를 붙입니다.

# Linux/macOS에서의 예시
OPENROUTER_API_KEY="sk-or-..." npx @modelcontextprotocol/인스펙터 node ./build/index.js

(Windows 예제는 프로젝트의 README.md를 참조하세요).

디버그

MCP 인스펙터를 실행합니다. tools/list를 사용합니다. 이제 get_latest_updates가 등록된 것을 볼 수 있습니다. 인스펙터를 통해 도구를 호출해 보세요. 최신 CSS 뉴스를 반환해야 합니다! (오픈라우터 크레딧이 $0.04 이상 남아 있는 경우에만 가능합니다.)

2단계: 메모리 리소스 및 관련 도구 (css_knowledge_memory, read/write_from_memory)

이제 서버가 상호 작용을 통해 정보를 기억할 수 있는 구성 요소인 css_knowledge_memory 리소스와 상호 작용하는 도구를 활성화해 보겠습니다.

리소스 등록 활성화

메인 파일(src/index.ts)에서 registerResources(); 줄의 주석 처리를 해제합니다.

리소스 코드 이해

src/resources/index.ts를 열고 registerCssKnowledgeMemoryResource 함수를 찾습니다.

• 등록: 이 함수는 server.resource()를 사용하여 css_knowledge_memory 리소스를 정의합니다. 이렇게 하면 이름, 고유 URI(memory://...), 읽기/쓰기 권한, 비동기 핸들러 함수가 부여됩니다.
• 핵심 로직(핸들러 및 헬퍼): 핸들러 함수는 클라이언트가 리소스의 현재 상태를 읽으려 할 때 호출됩니다. 이 파일에는 실제 파일 시스템 작업인 읽기, 구문 분석, 유효성 검사(Zod 사용), 문자열화, data/memory.json 파일에 데이터 쓰기 등을 처리하는 헬퍼 함수(이 파일에 정의된 readMemory, writeMemory도 사용)가 사용됩니다. 이 파일은 영구 메모리 저장소 역할을 합니다.
• 활성화: 파일 하단에 있는 기본 registerResources 함수는 서버가 시작될 때 registerCssKnowledgeMemoryResource()가 호출되도록 합니다.

메모리 도구 코드 이해

다음으로, src/tools/index.ts로 이동하여 src/tools/index.ts 내의 registerReadFromMemoryTool 및 registerWriteToMemoryTool 함수를 살펴보세요. 이 함수는 클라이언트가 메모리 리소스와 관련하여 수행할 수 있는 작업을 제공합니다.

• 등록: 두 도구 모두 server.tool()을 사용하여 등록됩니다. read_from_memory에는 특정 입력 스키마가 없는 반면, write_to_memory는 Zod({ concept: z.string(), known: z.boolean() })를 사용하여 입력 스키마를 정의하여 클라이언트가 업데이트를 위해 올바른 데이터 형식을 보내도록 합니다.
• 핵심 로직(핸들러): read_from_memory 도구의 핸들러는 src/resources/index.ts에서 가져온 readMemory() 헬퍼를 호출하고 현재 상태를 반환하기만 하면 됩니다. write_to_memory 도구의 핸들러는 유효성 검사된 인수({ concept, known })를 받은 다음 readMemory() 및 writeMemory() 헬퍼를 모두 사용하여 현재 상태를 로드하고 입력에 따라 업데이트한 다음 수정된 상태를 data/memory.json에 다시 저장합니다.
• 활성화: 메인 registerTools 함수는 이러한 도구 등록 함수가 호출되도록 합니다.

빌드

변경 사항을 컴파일하세요.

npm run build

디버그

MCP 인스펙터를 실행합니다.

• 이제 리소스 탭에 css_knowledge_memory가 등록된 것을 볼 수 있습니다.
• 도구 탭에 1단계의 get_latest_updates와 새로운 read_from_memory 및 write_from_memory 도구가 표시되어야 합니다.
• 상태 확인: 인스펙터를 사용하여 read_from_memory를 호출한 다음 몇 가지 테스트 데이터(예: { "concept": "Grid", "known": true })를 사용하여 write_to_memory를 호출하고 마지막으로 read_from_memory를 다시 호출합니다. 두 번째 읽기에서 반환된 데이터가 작성한 변경 내용을 반영하는지 확인하고, data/memory.json 파일을 직접 확인하여 지속된 업데이트를 확인합니다.

3단계: 프롬프트 (css-tutor-guidance)

마지막 단계! 이제 AI 모델에 제공한 도구와 리소스를 사용하는 방법을 알려줄 차례입니다.

프롬프트 등록 활성화

src/index.ts에서 마지막 주석 처리된 줄인 registerPrompts(); 의 주석을 제거합니다.

프롬프트 코드 이해하기

src/prompts/index.ts를 엽니다.

• 등록: registerCssTutorPrompt 함수는 server.prompt()를 사용하여 클라이언트에 대한 이름과 설명을 제공하는 css-tutor-guidance 프롬프트를 정의합니다. 이 프롬프트를 호출할 때 클라이언트의 인수가 필요하지 않으므로 입력 스키마({})를 지정하지 않습니다. (여기에 동적 데이터를 전달할 수 있는데, 이는 꽤 복잡해질 수 있습니다.)
• 핵심 로직(핸들러 및 콘텐츠): 이 프롬프트의 핸들러는 매우 간단합니다. 사용 가능한 도구와 메모리를 사용하여 CSS 튜터처럼 동작하는 방법에 대한 자세한 지침이 포함된 cssTutorPromptText 상수같은 파일에 정의된 내용을 반환하기만 하면 됩니다.
• 활성화: 파일 하단에 있는 기본 registerPrompts 함수는 서버가 시작될 때 registerCssTutorPrompt()가 호출되도록 합니다.

빌드

변경 사항을 컴파일 하세요.

npm run build

디버그

MCP 인스펙터를 실행하세요.

• 프롬프트 탭에 이제 css-tutor-guidance가 등록된 것을 볼 수 있습니다.
• 인스펙터에서 프롬프트를 호출해 보세요. cssTutorPromptText에 정의된 전체 안내 텍스트가 표시되어야 합니다.

꽤 멋지지 않나요? 문제는 이제 서버가 MCP를 통해 프롬프트를 제공하지만 대부분의 클라이언트는 자동으로 MCP 프롬프트를 사용할 수 없다는 점입니다. 클로드는 사용자가 수동으로 선택해야 하며, 커서는 아직 MCP 프롬프트에 액세스할 수도 없습니다.

따라서 현재로서는 특정 MCP 서버를 사용하는 방법에 대한 지침을 제공하는 Cursor 룰과 같은 기능에 의존하고 있습니다. 조만간 더 많은 MCP가 채택되기를 바랍니다.

실제 클라이언트로 서버 실행하기

인스펙터를 사용하여 서버를 완전히 빌드하고 디버깅했으니 이제 실제 AI 클라이언트에 연결할 차례입니다.

클로드 데스크톱 설정

클로드 데스크톱 애플리케이션을 사용하는 경우에 대한 내용입니다.

1. Settings로 이동합니다. 프로필 근처의 설정이 아니라(어떤 이유에서인지?) 상단 도구 모음에 있는 실제 앱으로 이동합니다.
2. "Developer" → "Edit Config"로 이동합니다.
3. css-tutor 서버에 대한 항목을 추가합니다.
4. 절대 경로(상대 경로가 아님!)와 API 키를 실제 값으로 바꿉니다.
5. 클로드 테스크톱을 다시 시작하고 css-tutor 서버에 연결합니다. (누르는 위치는 상단의 동영상을 참조하세요.)

커서 설정

커서 에디터를 사용하는 경우에 대한 내용입니다.

1. Cursor Settings > MCP > Add new global MCP server로 이동합니다.
2. 위의 클로드 단계와 동일하게 서버를 구성합니다.
3. 프롬프트 규칙 생성: 커서는 서버의 MCP 프롬프트를 자동으로 사용하지 않으므로 규칙을 만들려면 Cursor Settings > Rules로 이동하여 서버에서 붙여넣은 프롬프트로 새 프로젝트 규칙을 추가합니다.
4. 규칙 활성화: 이 프로젝트 내에서 커서에서 채팅하거나 코드(예: Cmd+K)를 생성할 때 규칙을 @멘션하면 커서의 상담원이 추가 안내 없이도 의도한 대로 서버를 사용할 수 있습니다.

완성!

이제 데모 비디오 시나리오를 재현하여 한 클라이언트와 채팅을 하다가 원할 때마다 다른 클라이언트로 이동할 수 있어야 합니다.

다음 단계

먼저, 스스로를 칭찬해 주세요. 새로운 기술은 멋진 것입니다.

둘째, 그 의미를 생각해 보세요.

이 CSS 튜터 예제는 가능한 한 빨리 MCP의 기능을 익힐 수 있도록 단순하게 설계되었지만, 실제 도구를 사용하면 무엇을 할 수 있을지 상상해 보세요.

이런 것들도 할 수 있습니다.

• 보다 정교한 상태: 다중 사용자 지원 또는 더 큰 데이터 집합을 위해 JSON 파일을 적절한 데이터베이스(예: SQLite 또는 PostgreSQL)로 교체하세요.
• 추가 도구: 특정 문서 사이트(예: MDN)를 검색하거나 코드펜에서 CSS 예제를 가져오거나 사용자의 로컬 CSS 파일을 분석할 수 있는 도구를 추가하세요.
• 동적 프롬프트: 정적인 프롬프트 대신 리소스에 저장된 사용자의 알려진 개념에 따라 안내가 조정되도록 설정하세요.
• 오류 처리 및 경로 재지정: 특히 외부 API 호출에 대해 보다 세분화된 오류 처리를 추가하고, 한 서비스가 다운되었을 때 로직을 다시 라우팅하세요.
• 다양한 전송: 네트워크 기반 통신(예: 스트리밍을 위한 서버 전송 이벤트(SSE))이 필요한 경우 StdioServerTransport 외에 다른 전송 옵션을 살펴보세요.

MCP는 원하는 것은 무엇이든 만들 수 있는 매우 강력한 프레임워크를 제공합니다. MCP 서버를 구축하면 프로토콜을 사용하는 모든 새 어시스턴트에 연결되는 맞춤형, 상태 저장형, 미래 지향적인 통합을 만들 수 있습니다.

행복한 구축하세요!

🚀 한국어로 된 프런트엔드 아티클을 빠르게 받아보고 싶다면 Korean FE Article을 구독해주세요!