MCP 쉽게 사용해보기 (with Claude Desktop, VS Code)

 

MCP는 Model Context Protocol의 준말로, 최근 가장 핫한 Agent 개발에 있어서 표준으로 자리매김한 프로토콜이다.

Agent는 모델이 기존에 학습한 정보만으로 답할 수 없는 부분을 보완하기 위해, 다양한 API Tool들을 활용할 수 있도록 확장되어 사용자의 질의에 더 정확하게 대답할 수 있다.

Agent가 사용할 수 있도록 Tool들을 서버에 등록시켜줘야 하는데, MCP는 각기 다른 규격의 Tool들을 처리해야하는 수고를 덜어주어 간편하게 등록할 수 있게 해준다.

MCP는 다양한 프로그램 환경 (Client)에서 사용 가능하나, 가장 보편적으로 사용되는 Claude Desktop과 Visual Studio Code에서 진행해본다.

서버를 원격으로 배포하는 방법도 있지만 이 포스팅에서는 로컬 서버만을 사용한다.

(참고로, 운영체제는 MacOS이다.)

 

---

1. Claude Desktop에서 로컬 MCP 서버 연결하기

 

1-1. Claude Desktop 설치

https://claude.ai/download 링크에서, 사용하는 운영체제에 맞게 파일을 다운로드해 설치한다.

 

1-2. MCP Server 사용을 위한 설치

터미널에서 아래 명령어를 실행한다.

git clone https://github.com/modelcontextprotocol/servers.git
cd servers/src/filesystem
npm install
npm run build

 

1-3. 사용할 MCP Server 선택하기

https://smithery.ai/ 에서는 MCP 서버에서 사용할 수 있는 다량의 Tool들을 제공하여, 직접 구현할 필요없이 Claude Desktop에 간편하게 연결해 사용이 가능하다.

예시로 웹 검색 기능을 제공하는 Exa Search를 선택했다

원하는 Tool을 제공하는 서버를 선택한 다음, 우측의 JSON 버튼 - 운영체제 선택 후 빨간색 네모친 부분을 복사한다. 

 

1-4. Claude Desktop에 MCP Server 연결하기

Claude Desktop 프로그램을 열어, 설정 - 개발자 탭을 누르면 "로컬 MCP 서버"가 비어있는 것이 보인다.

"구성 편집" 버튼을 누르면 claude_desktop_config.json 파일로 연결되는데, 이를 열어서 이전 단계에서 복사한 JSON 객체를 그대로 붙여넣고 저장한다.

Claude Desktop 프로그램을 완전히 종료한 후 다시 연다.

다시 한번 설정 - 개발자 탭에 가보면 아래와 같이 방금 config에 등록한 MCP 서버가 연결되어 있는 것을 확인할 수 있다.

 

새 채팅 - 검색 및 도구 버튼을 눌러보면 exa 서버가 활성화된 것이 보인다.

 

1-5. 채팅에서 동작 테스트

기본적으로 제공되는 웹 검색 기능을 끄고, exa의 웹 검색 Tool이 잘 동작하는지 확인해본다.

좌: 웹 검색, exa 비활성화 / 우: 웹 검색 비활성화, exa 활성화

왼쪽 이미지에서는 내 블로그에 대한 정보를 학습하지 않은 데다가 웹 검색도 불가하기 때문에 내 질의에 제대로 대답하지 못한다.

하지만 오른쪽 이미지에서는 exa의 검색 Tool을 사용하여 내 블로그에 대한 정보를 찾아와 정확하게 대답하는 것을 확인할 수 있다.

 

---

2. VS Code에서 MCP 서버 직접 구현하기

 

공개된 MCP 서버 중 사용하려는 목적에 맞는게 없다면 custom하게 구현할 수도 있다.

 

2-1. Visual Studio Code 설치

https://code.visualstudio.com/ 링크에서 다운로드한다.

 

2-2. fastmcp 라이브러리 설치

fastmcp는 Python 환경에서 MCP를 빠르고 편리하게 구현할 수 있게 해주는 라이브러리이다.

pip install fastmcp

 

2-3. MCP Server 작성 및 실행

VS Code를 열어 Workspace를 생성하고, server.py라는 이름의 파일을 만들어 아래 코드를 작성한다.

간단하게 두 수를 더한 결과를 반환하는 add라는 이름의 Tool을 정의하였다.

from fastmcp import FastMCP


mcp = FastMCP("add-mcp-http")

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b


if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8000)

 

VS Code Terminal에서 아래 명령어를 실행하면, http://0.0.0.0:8000/mcp URL에서 서버가 실행된다.

python server.py

위와 같이 뜨면 서버가 성공적으로 실행되고 있는 것이다. (서버를 종료시키려면 Terminal에서 ctrl+C 또는 quit 입력)

 

2-4. 채팅에서 동작 테스트

서버를 실행한 상태에서, VS Code 상단바의 개구리? 같이 생긴 Toggle Chat 아이콘을 누르면 Chat 탭이 표시된다.

아래에 Ask 모드로 지정되어 있는 것을 Agent 모드로 바꿔준다. 

 

채팅창에 원하는 메시지를 입력한다. Continue 버튼이 뜬다면 눌러준다.

내가 입력한 메시지에서 add Tool에 필요한 arguments (a, b)를 잘 추출한 것과 Tool 호출도 잘 실행한 것을 확인할 수 있다.

Tool 호출 결과 값만을 그대로 사용자에게 반환하는 것이 아니라, 이를 자연어 문장으로 생성하여 사용자 친화적인 응답을 반환한다.

 

 

참고: https://www.youtube.com/watch?v=46HxP7kO9oY (시청 추천!)