MCP: MCP 이해와 개발 환경 세팅(vscode)

1. MCP 등장 이전의 기술들

ChatGPT, Gemini, Grok 같은 대규모 언어 모델(LLM)이 처음 등장했을 때, 이들은 마치 '세상 모든 책을 읽었지만 인터넷은 연결되지 않은 천재'와 같았습니다. 학습된 데이터 안에서는 완벽했지만, 실시간 정보나 사용자의 개인 데이터에는 접근할 수 없었죠. 이를 해결하기 위해 MCP 이전에 사용되었던 기술들은 다음과 같습니다.

 

1. RAG (Retrieval-Augmented Generation, 검색 증강 생성)

모델이 모르는 정보를 외부 문서(PDF, DB 등)에서 찾아 답변에 포함시키는 방식입니다. 하지만 RAG는 주로 '읽기 전용' 지식을 전달하는 데 특화되어 있어, 시스템을 직접 조작하거나 실시간으로 상호작용하는 데는 한계가 있었습니다.

 

2. Function Calling & Tool Use (함수 호출)

AI가 직접 외부 API를 호출하거나 코드를 실행할 수 있게 만든 기술입니다. 하지만 가장 큰 문제는 '표준의 부재'였습니다.

• OpenAI용 함수를 만들면 Anthropic 모델에서는 쓸 수 없고, Google Gemini를 쓰려면 또 새로 규격을 맞춰야 했습니다.
• 개발자는 모델마다, 도구마다 개별적인 '커스텀 연결선'을 일일이 설계해야 하는 이른바 'N x M의 늪*에 빠져 있었습니다.

3. 폐쇄적인 플러그인(Plugin) 생태계

초기 ChatGPT 플러그인처럼 특정 플랫폼 안에서만 작동하는 방식이었습니다. 이는 모델의 확장성을 제한했고, 데이터가 특정 서비스 안에 고립되는 결과를 낳았습니다.

1.1 왜 MCP가 이 패러다임을 바꾸는가?

MCP는 앞선 기술들이 가졌던 '파편화'라는 고질적인 문제를 해결하기 위해 등장했습니다.

• 표준화된 연결 (The USB-C for AI): 과거에 기기마다 충전기 모양이 달랐던 것처럼 AI 연동 기술도 제각각이었지만, MCP는 이를 하나로 통합하는 '표준 규격'을 제시합니다.
• 수동적 지식에서 능동적 컨텍스트로: 단순히 데이터를 전달받는(RAG) 수준을 넘어, 모델이 스스로 어떤 데이터(Resource)가 필요한지 판단하고 도구(Tool)를 꺼내 쓰는 유기적인 환경을 제공합니다.
• 재사용성의 극대화: 한 번 만든 MCP 서버는 클라이언트가 무엇이든(Claude Desktop, IDE, 커스텀 앱 등) 즉시 연결되어 작동합니다.

2. Claude Desktop의 MCP 정적 설정 방식 (file-based configuration)

Claude MCP는 다양한 프로그래밍 언어를 지원하여 개발자들이 선호는 환경에서 자유롭게 작업할 수 있습니다. Python, Java, TypeScript, Kotiln, C# 처럼 친숙한 언어를 지원하고 있습니다. 자세한 지원 언어 목록은 공식 홈페이지에서 한 눈에 살펴볼 수 있습니다.

Build an MCP client - Model Context Protocol

2.1 환경 구성

• 개발언어: Python 3.12 이상
• 개발환경: VSCode
• MCP PC: Claude PC

Python 설치와 VSCode 설치에 자세한 설명은 생략하겠습니다. Python 3.12 이상에서만 Claude MCP가 정상적으로 동작하고, VSCode는 공식 홈페이지에서 그대로 최신 버전을 설치하시면 됩니다. 각 설치에서 반드시 주의해야 할 점은, 현재 운영체제 환경과 동일한 설치 파일을 받고, 환경 변수(PATH) 설정 체크된 상태에서 설치하시면 됩니다.

Visual Studio Code - The open source AI code editor

 

Download Python

 

Windows 11 / 인텔 CPU 사용자 기준

2.2 Claude PC 설치

Claude Desktop 설치를 위해 공식 다운로드 홈페이지에서 운영체제와 동일한 설치 파일을 선택합니다.

Download Claude | Claude

Windows 11 / 인텔 CPU 사용자 기준

 

설정에서 개발자를 선택한 후 설정 편집 버튼을 클릭합니다.

파일 > 설정 > 개발자 > 구성 편집

 

다음과 같이 Claude 폴더 안에서 Claude_desktop_config.json 파일을 확인할 수 있습니다. 
해당 파일을 메모장에서 편집을 클릭 또는 원하는 편집 도구로 열면 `{}` 중괄호만 있는 상태입니다. 그대로 열어 둡니다.

 

 

2.3 MCP 모듈 설치

C:\ 안에 test라는 새 폴더를 만들고 VSCode로 해당 폴더를 열어 줍니다.

VSCode로 열린 test 폴더 안에 hello.py, tutorial_1.py 빈 파일을 생성합니다.

C:\test 폴더 생성 후, tutorial_1.py, hello.py 파일 생성

 

Ctrl + `(키보드 숫자 1 옆에 있는 백틱 기호)를 누르면 VSCode 터미널 창이 열립니다.

아래 명령어로 mcp 모듈을 설치합니다.

PS C:\test> pip install mcp

2.4 Claude에 코드 실행 권한 부여

tutorial_1.py 파일에다가 이제 Claude가 사용할 수 있는 함수를 직접 작성하도록 합니다.

`@mcp.tool` 데코레이터를 추가하면 Claude가 프롬프트를 통해 내가 작성한 함수에 접근합니다.

from mcp.server.fastmcp import FastMCP

# MCP 서버 생성하기
mcp = FastMCP(name="tutorial_1")


@mcp.tool()
def echo(message: str) -> str:
    """
    입력받는 메시지를 그대로 반환하는 도구입니다.
    """
    return message + " 라는 메시지가 입력되었습니다. 안 찍어 볼 수 없죠! hello world!"


# 서버 실행하기
if __name__ == "__main__":
    mcp.run()

echo와 같은 함수 이름은 기능을 명확히 설명하는 단어로 작성해야 Claude가 사용자의 요청에 맞는 함수를 정확히 찾아 실행할 수 있습니다.

 

그리고 타입 힌트와 독스트링을 잘 작성해야 Claude가 함수를 제대로 실행할 확률이 높습니다. 모든 경우에 우리가 작성한 코드를 항상 잘 실행할 수 있으리라 기대해서는 안 됩니다. 함수가 몇 개 안될 때는 Claude가 독스트링 없이도 함수를 잘 찾아내지만, 함수가 수십 개만 되어도 제대로 실행하지 못하는 경우가 생깁니다. 타입 힌트와 독스트링으로 최대한 친절하게 해당 코드의 용도를 설명해야 Claude가 수백 개가 넘는 함수 목록에서도 원하는 기능을 수행할 수 있습니다.

2.5 설정 파일 작성하기

설정에서 메모장으로 열었던 Claude_desktop_config.json 파일을 다음처럼 수정합니다.

해당 파일의 위치는 C:\Users\사용자이름\AppData\Roaming 폴더 안에 있습니다.

{
	"mcpServers": {
		"tutorial_1": {
			"command": "python",
			"args": ["C:/test/tutorial_1.py"]
		}
	}
}

 

Claude의 설정 파일이 있는 AppData 폴더는 숨김 폴더입니다. 직접 접근하고 싶다면 숨김 폴더를 볼 수 있게 설정해야 합니다. 가장 간단한 방법은 `window` 키를 누르고 '실행'이라고 입력한 후 다음과 같이 실행 창이 뜨면 `%appdata%`를 입력해 주세요. 폴더 하나가 열리게 되는데, 여기서 Claude 폴더를 선택하면 됩니다.

 

2.6 Claude 재실행 및 프롬프트 입력

Claude는 작성된 함수를 동적으로 불러오지 않습니다. 따라서 재실행하려면 반드시 Claude Desktop을 완전 종료해야 합니다.

Claude가 다시 실행되었다면, 검색창의 검색 및 도구에서 커넥터를 확인하면 현재 연동된 MCP 서버 목록을 확인할 수 있습니다.

MCP 서버 목록을 통해 활성화 또는 비활성화 여부를 선택할 수 있습니다.

 

 

Claude에 다음과 같이 입력해서 실행해 보겠습니다.

이때 Claude가 해당 도구를 허용할 것인지 물어봅니다. 항상 허용 또는 한 번만 허용 버튼을 클릭합니다.

입력받은 메시지를 그대로 반환하는 도구가 있지? 그것을 사용해서 hello world를 입력해 줘.

 

항상 허용 버튼을 클릭하면 현재 대화(채팅 세션) 내에서 tutorial_1 서버 도구(echo 함수)를 계속 사용할 수 있도록 허용합니다. 한 번만 허용 버튼을 클릭하면 오직 이번 한 번만 도구 사용을 허용하며, 같은 대화 내에서 동일한 도구를 다시 사용하려고 할 때는 다시 권한을 요청하는 대화 상자가 표시됩니다.

 

해당 함수가 실행되어 다음과 같은 실행 결과를 확인할 수 있습니다.

만약 프롬프트로 후속 작업으로 무엇을 할 것인지 입력한다면 여기에 이어 연쇄적으로 작업을 수행합니다.

3. 자원에 안정적으로 접근하는 방법

`@mcp.resource(주소)` 는 주소(URI)를 통해 필요한 정보 또는 데이터를 가져오는 기능입니다. HTTP Method의 GET과 비슷한 기능을 제공합니다. 다른 함수 안에서도 해당 주소를 통해 필요한 정보 또는 데이터에 접근할 수 있습니다. 

from mcp.server.fastmcp import FastMCP

# MCP 서버 설정하기
mcp = FastMCP("tutorial_2")


@mcp.tool()
def add(a: int, b: int) -> int:
    """두 숫자를 더하는 함수"""
    return a + b


@mcp.resource("greeting://hello")
def get_greeting() -> str:
    """인사말을 제공하는 함수"""
    return f"Hello, world!"


# 서버 실행하기
if __name__ == "__main__":
    mcp.run()

 

`@mcp.resource("greeting://hello)`는 해당 자원을 지정된 주소(여기에서는 "greeting://hello")로 접근합니다.
마치 GET 요청과 비슷하다고 생각하면 이해하기 쉽습니다. 

• `@mcp.resource()`: 읽고 참고할 수 있는 외부 데이터나 콘텐츠(Data)를 제공
• `@mcp.tool() `: Cluade가 능동적으로 함수를 호출하여 외부 시스템에서 작업을 수행(Action)하는 함수

지금처럼 작성한 코드 전체 흐름은 앞의 흐름과 마찬가지로 동일한 과정을 수행합니다.

.py 생성 → 함수 정의 → claude_desktop_config.json 수정 →  Claude 종료 후 재시작 

{
  "mcpServers": {
    "tutorial_1": {
      "command": "python",
      "args": [ "C:/test/tutorial_1.py" ]
    },
    "tutorial_2": {
      "command": "python",
      "args": [ "C:/test/tutorial_2.py" ]
    }
  },
  "preferences": {
    "coworkScheduledTasksEnabled": false,
    "sidebarMode": "chat"
  }
}

claude_desktop_config.json 파일에서 mcpServers 항목은 Claude가 실행할 서버들의 목록입니다. 

현재 코드에서 `tutorial_1`, `tutorial_2`  두 개의 서버를 정의했습니다. 각 서버마다 실행할 명령어(command)와 그 명령어에 전달할 인자(args)를 지정할 수 있습니다. 이렇게 설정 파일을 구성하면 필요에 따라 여러 개의 서버를 추가하고 관리할 수 있어 편리합니다.

 

다시 Claude Desktop을 종료하고 재시작하여 아래 문구를 입력합니다. 이전과 동일하게 허용 여부를 묻는 창이 등장한다면 "한 번만 허용" 버튼을 클릭합니다. 잠시 기다리면 다음과 같이 40으로 출력되는 것을 확인할 수 있습니다.

add라는 함수를 이용해서 a=10, b=30을 더해 줘.

 

만약, `@mcp.resource()`로 구현된 함수를 직접 호출하면 Cluade는 해당 함수를 실행할 수 없다는 안내와 함께 대신 호출 가능한 다른 MCP 도구 목록을 응답합니다. 그 이유는 `@mcp.resource()` 가 함수 호출 방식이 아니라 주소 기반 접근 방식을 사용했기 때문입니다.

resource에 접근하는 올바른 방법은 다음와 같습니다.

 

1. 대화창의 `+` 기호 클릭

2. 표시된 메뉴에서 tutorial_2에서 추가를 클릭

3. 등록된 resource 목록에서 get_greeting을 선택 

 

대화창에 `@mcp.resource()` 함수가 파일 형태로 대화창에 첨부됩니다. 이것이 바로 resource와 tool 사용의 핵심적인 차이점입니다. 대화창에 첨부된 get_greeting을 클릭하면 다음과 같이 "Hello, world!" 메시지가 담겨 있습니다. 이 파일은 방금 실행으로 return한 값을 가지고 있습니다.

MCP(Model Context Protocol) 환경에서 @map.resource()의 역할은 생각보다 훨씬 강력합니다. 많은 이들이 이를 단순히 사용자 인터페이스(UI)를 통해 데이터를 보여주는 ‘출력창’ 정도로 생각하지만, 실제 핵심은 이 리소스가 AI 모델과 함수들 사이의 ‘동적인 컨텍스트(Context)’ 역할을 수행한다는 점에 있습니다.

 

1. UI를 넘어 AI의 ‘직접 참조’가 가능해집니다

`@map.resource()`로 정의된 데이터는 단순히 사람만 읽는 것이 아닙니다. 우리가 작성한 다양한 MCP 함수(Tools) 안에서도 이 리소스에 직접 접근하여 데이터를 가져오거나 특정 작업을 수행할 수 있습니다. 즉, 리소스는 사람이 보는 ‘문서’인 동시에 AI가 읽고 쓰는 ‘공유 데이터베이스’가 됩니다.

 

2. 컨텍스트 중심의 복잡한 자동화 구현

리소스가 ‘컨텍스트’로 기능하게 되면, 여러 개의 MCP 함수가 파편화되지 않고 유기적으로 연결됩니다. 예를 들어, 한 함수가 시스템의 실시간 상태 정보를 리소스로 업데이트하면, 다른 함수들이 그 리소스를 참조하여 후속 판단을 내리는 식의 설계가 가능해집니다. 이는 단순한 일회성 도구 호출을 넘어, 시스템 전체를 관통하는 정교하고 강력한 자동화 시나리오를 가능케 합니다.

 

3. 왜 리소스 기반의 접근이 더 강력한가?

기존 방식에서는 함수를 실행할 때마다 매번 방대한 데이터를 인자로 넘겨야 했습니다. 하지만 리소스를 활용하면 AI 모델은 필요한 시점에 필요한 데이터만 리소스에서 ‘풀(Pull)’ 방식으로 가져올 수 있습니다. 결과적으로 토큰 소모를 줄이면서도 정보의 일관성을 유지할 수 있으며, 시스템의 상태를 실시간으로 반영하는 지능형 워크플로우를 구축할 수 있게 됩니다.

 

결국 @map.resource()를 제대로 활용한다는 것은, AI에게 단순한 도구를 쥐어주는 것을 넘어 ‘현재 상황을 이해할 수 있는 지식 베이스’를 제공하는 것과 같습니다. 이 컨텍스트 개념을 깊이 이해하고 설계에 반영한다면, 훨씬 더 고도화된 MCP 기반 자동화 시스템을 완성할 수 있을 것입니다.