MCP 서버를 구축하는 방법

작성자

Ash Minhas

Manager, Technical Content | AI Advocate

IBM

PJ Hagerty

Lead, AI Advocacy

IBM

Erika Russi

Data Scientist

IBM

이 튜토리얼에서는 IBM 튜토리얼을 검색하기 위한 단일 도구를 노출하는 간단한 모델 컨텍스트 프로토콜(MCP) 서버를 구축합니다. 스크립트는 fastmcp 프레임워크와 요청 라이브러리를 사용하여 원격 URL에서 튜토리얼의 JSON 인덱스를 다운로드합니다. 그런 다음 사용자의 쿼리와 일치하는 항목을 검색하고 깔끔한 형식의 결과 목록을 반환합니다. 또한 네트워크 문제, 잘못된 JSON 및 예기치 않은 문제에 대한 오류 처리를 추가하여 도구를 강력하고 초보자에게 친숙하게 만들 수 있습니다. 마지막으로 Cursor와 같은 클라이언트에 연결하고 테스트할 수 있도록 MCP 서버를 실행합니다.

MCP란 무엇인가요?

Enterprise 스타트업 개발자 모두 점점 더 많은 생성형 인공 지능(AI) 기반 솔루션을 개발하고 있습니다. 솔루션을 더욱 유용하게 활용하려면 최신 정보와 컨텍스트가 필요합니다. 머신 러닝 모델은 도구, 애플리케이션 프로그래밍 인터페이스(API), 소프트웨어 개발 키트(SDK) 및 프런트엔드 시스템과 상호 운용되어야 합니다.

MCP는 AI 모델과 시스템 간에 컨텍스트가 전달되는 방식을 표준화합니다. 대규모 언어 모델(LLM)과 외부 데이터 소스 및 도구 간의 조정을 간소화합니다. 일반적인 비유는 MCP를 LLM의 USB-C 포트로 생각하는 것입니다. 이것은 모델이 모델 훈련의 일부가 아닌 데이터와 능력에 액세스할 수 있기 때문에 LLM을 훨씬 더 유용하게 만듭니다. 이 능력은 AI 에이전트를 구축할 때 특히 유용합니다.

MCP는 Anthropic에서 개발했으며 OpenAI, Google DeepMind 및 더 광범위한 업계를 포함한 주요 AI 제공업체에서 채택했습니다. AI 모델이 외부 데이터, 리소스(예: 프롬프트 템플릿) 및 도구에 액세스하고 사용할 수 있는 안전하고 표준화된 방법을 제공합니다.

또한 Cursor 및 Visual Studio Code와 같은 통합 개발 환경(IDE)도 MCP를 채택하여 AI 어시스턴트가 MCP 서버에 액세스하여 보다 컨텍스트 관련성이 높고 개발자 친화적으로 사용할 수 있도록 했습니다. 개방형 표준으로 구축된 조직은 MCP를 사용하여 생성형 AI의 확률적 세계와 현재 존재하는 대부분의 엔터프라이즈 시스템의 결정론적 세계 사이의 가교 역할을 합니다. MCP는 검색 증강 생성(RAG), 도구 호출, AI 에이전트 등 최근 등장하기 시작한 다른 디자인 패턴과 유사하게 컨텍스트 정보가 포함된 LLM을 제공합니다.

이러한 다른 솔루션과 비교하여 MCP를 사용하면 다음과 같은 몇 가지 이점이 있습니다.

- 확장: MCP 서버를 한 번 정의하고 호스팅하여 여러 AI 시스템에서 사용할 수 있습니다. 이 용량으로 인해 여러 생성형 AI 시스템에 대해 동일한 소스 데이터, 리소스 및 AI 도구에 대한 액세스를 정의해야 할 필요성이 제한됩니다.

- 데이터 검색: 데이터 검색을 위해 쿼리 전에 전처리 및 벡터화가 필요한 RAG와 달리, MCP는 동적이며 실시간으로 정보 소스의 변동과 업데이트를 허용합니다.

- 복잡성: 여기에서 설명하는 것처럼 MCP는 설정과 AI 애플리케이션 통합이 매우 간단합니다. 구성 파일을 사용하여 MCP 서버를 여러 환경에서 쉽게 이식할 수 있습니다.

- 플랫폼 독립적: Python, TypeScript 또는 기타 언어로 MCP 서버를 구축할 수 있다는 사실 외에도 특정 LLM 솔루션과 연결되지 않습니다.

- 클라이언트/서버 모델을 통한 디버깅: MCP 클라이언트가 MCP 서버에 요청을 보내면 서버는 API, 데이터베이스 또는 로컬 파일 등 다양한 외부 시스템 및 소스에서 필요한 데이터를 가져옵니다. 이러한 구조화된 접근 방식은 AI 모델이 일관되고 관련성 있는 컨텍스트를 수신하여 보다 정확하고 신뢰할 수 있는 아웃풋으로 이어지도록 보장합니다. MCP는 JSON-RPC를 사용하여 메시지를 인코딩하고 stdio 및 스트리밍 가능한 HTTP의 두 가지 전송 메커니즘을 지원합니다. 이전 버전의 프로토콜에서는 서버 전송 이벤트(SSE)를 통해 HTTP도 지원했습니다.

기업에 필요한 최신 정보를 지속적으로 최신 상태로 유지해야 하는 것은 쉽지 않은 일입니다. MCP는 컨텍스트를 구축하고 계약이 실행될 때 계약에 대한 새로운 정보, 디지털화되고 있지만 반드시 이해 가능하지는 않은 레거시 정보 등을 통합하는 데 도움을 줄 수 있습니다. 해당 정보는 내부 및 외부 모두일 수 있지만 컨텍스트를 추가하면 LLM을 유용하게 사용하기 위해 시간이 많이 걸리는 LLM을 재훈련할 필요가 없습니다.

많은 원격 MCP 서버를 사용할 수 있으며 github.com에서 다양한 레퍼런스 구현을 확인할 수 있습니다.

단계

이 단계별 가이드는 MCP 서버를 만들 때 참조할 server.py 스크립트와 함께 GitHub 리포지토리에서 찾을 수 있습니다. 이 튜토리얼에서는 다음을 수행할 수 있는 기본 사용자 지정 MCP 서버를 구축하는 방법을 살펴보겠습니다.

튜토리얼의 GitHub 리포지토리에 연결
사용자가 관심을 가질 만한 주제 검색 수행
튜토리얼 링크와 함께 결과 반환

이 튜토리얼을 쉽게 만들 수 있도록 구축할 서버가 인증 없이도 튜토리얼 콘텐츠를 쉽게 사용할 수 있는 메커니즘을 만들었습니다.

1단계. 환경 설정

- 컴퓨터에 Python 3.11 이상이 설치되어 있어야 합니다(터미널에서 python3 --version을 실행하여 확인).

- 내장된 venv 모듈을 사용할 수 있습니다(대부분의 시스템에서 Python과 함께 제공되며 일부 Linux 배포판에서는 sudo apt install python3-venv를 사용하여 별도로 설치해야 할 수도 있음).

- 명령줄 터미널(CLI):

- macOS 또는 Linux: 터미널 앱을 사용합니다(이러한 환경은 Unix와 유사함).

- Windows: PowerShell 또는 프롬프트를 사용하며, 다음 단계에서 약간의 구문 차이를 설명합니다.

- 원하는 텍스트 편집기 또는 IDE

새 디렉토리를 만들고 그 디렉토리로 이동합니다.

mkdir ibmtutorialmcpserver 및 cd ibmtutorialmcpserver

해당 디렉토리에 위치했는지 확인한 후 다음 명령어를 실행하여ibmtutorialmcpserver 가상 환경을 생성할 수 있습니다.

python3 -m venv venv

참고: Windows에서는python3 을(를) 다음으로 교체할 수도 있습니다.python

가상 환경을 만든 후에는 다음 명령을 사용하여 활성화해야 합니다.

source venv/bin/activate

활성화되면 셸이 프롬프트에서(venv) 사용자를 표시할 것입니다.

이제 다음을 위한 Python 패키지를 설치해야 합니다.fastMCP 이 오픈 소스 프레임워크는 MCP 서버 실행에 필요한 모든 기능을 제공하며 적극적으로 유지 관리됩니다. 또한 간단한 HTTP 요청 수행을 위해requests package 을(를) 설치할 것입니다.

다음 명령을 사용하여fastMCP 및requests 패키지를pip 설치합니다.

pip install fastmcp requests

이 단계가 완료되면 다음 명령을 실행하여 fastMCP가 올바르게 설치되었는지 확인할 수 있습니다

fastmcp version

아래와 같은 아웃풋이 나오면 가상 환경에 fastMCP가 설치된 것입니다.

FastMCP version:                                       2.10.1
MCP version:                                           1.10.1
Python version:                                       3.11.13
Platform:                          macOS-15.5-arm64-arm-64bit
FastMCP root path: /opt/homebrew/lib/python3.11/site-packages

이제 fastMCP가 설치되었으니 MCP 서버를 생성해 보겠습니다.

2단계. MCP 서버 생성

디렉토리에 새 파일을 만들고 이름을 지정해 보겠습니다.server.py .

해당 파일이 있으면 파일을 열고 다음 코드 스니펫을 복사하여 붙여넣습니다.

# Simple MCP server that exposes a single tool to search IBM tutorials.
# How to run:
# 1) Install dependencies: pip install fastmcp requests
# 2) Start the server using an MCP client with the command: fastmcp run <YOUR PATH>/server.py

from fastmcp import FastMCPimport requests

# Source of the tutorials index
DOCS_INDEX_URL = "https://raw.githubusercontent.com/IBM/ibmdotcom-tutorials/refs/heads/main/docs_index.json"

mcp = FastMCP("IBM Tutorials")

@mcp.tool
def search_ibmtutorials(query: str) -> str:
    """
    Search for tutorials on GitHub by downloading a JSON file from a GitHub repo and searching the payload for any relevant results and the respective details

Args:
    query: The search term to look for in tutorial titles and URLs

Returns:
    A formatted list of relevant tutorial results
    """
    try:
        # Download the JSON file from the GitHub repo
        response = requests.get(DOCS_INDEX_URL, timeout=10)
        response.raise_for_status() # Raise an exception for bad status codes

        # Parse the JSON data
        tutorials = response.json()

        # Search for relevant tutorials (case-insensitive)
        query_lower = query.lower()
        relevant_tutorials = []

        for tutorial in tutorials:
            # Search in title and URL
            title = tutorial.get('title', '').lower()
            url_path = tutorial.get('url', '').lower()

            if query_lower in title or query_lower in url_path:
                relevant_tutorials.append(tutorial)

        # Format and return results
        if not relevant_tutorials:
            return f"No IBM tutorials found matching '{query}'"

        # Format the results
            result_lines = [f"Found {len(relevant_tutorials)} tutorial(s) matching '{query}':\n"]

        for i, tutorial in enumerate(relevant_tutorials, 1):
            title = tutorial.get('title', 'No title')
            tutorial_url = tutorial.get('url', 'No URL')
            date = tutorial.get('date', 'No date')
            author = tutorial.get('author', '')

            result_lines.append(f"{i}. **{title}**")
            result_lines.append(f" URL: {tutorial_url}")
            result_lines.append(f" Date: {date}")
            if author:
                result_lines.append(f" Author: {author}")
            result_lines.append("") # Empty line for spacing

        return "\n".join(result_lines)

    except requests.exceptions.RequestException as e:
    return f"Error fetching tutorials from GitHub: {str(e)}"
    except ValueError as e:
    return f"Error parsing JSON data: {str(e)}"
    except Exception as e:
    return f"Error searching IBM tutorials: {str(e)}"

if __name__ == "__main__":
    mcp.run()

앞의 코드를 살펴보고 주요 부분이 수행하는 작업을 설명하겠습니다.

가져오기 및 설정

이 스크립트는 MCP 서버를 만들기 위한 프레임워크를 제공하는 FastMCP와 HTTP를 통해 데이터를 다운로드하는 데 사용되는 요청을 가져오는 것으로 시작됩니다. 다음과 같이 상수를 추가하여DOCS_INDEX_URL 튜토리얼 인덱스에 대한 원격 JSON URL을 보관했습니다. 이 접근 방식을 사용하면 나중에 이 튜토리얼을 재사용하려는 JSON 데이터의 다른 소스가 있는 경우 소스 위치를 더 쉽게 변경할 수 있습니다.

MCP 서버 설정

그런 다음 다음을 사용하여 MCP 서버 인스턴스를 만듭니다.FastMCP(“IBM Tutorials”) 이 단계는 서버가 MCP 클라이언트에 노출할 모든 도구에 대한 중앙 컨트롤러 역할을 합니다. 예를 들어 정의하는search_ibmtutorials 도구가 이에 해당됩니다.

MCP 도구 정의

이러한@mcp.tool 데코레이터는search_ibmtutorials 을(를) MCP 도구로 표시합니다. 이 함수는 검색어를 가져와서 다음에서 튜토리얼 색인을 다운로드합니다. 이때DOCS_INDEX_URL 을(를) 사용합니다requests.get() (네트워크 안전을 위해 10초 시간 제한 포함). 그리고 HTTP 응답 상태가 오류를 나타내는 경우 예외를 발생시킵니다. 데이터가 검색되면 JSON에서 Python 객체로 구문 분석됩니다.

검색은 대소문자를 구분하지 않습니다. 쿼리는 소문자로 변환되고 각 튜토리얼의 제목과 URL은 일치를 위해 소문자로 변환됩니다. 튜토리얼의 제목이나 URL에 검색어가 포함된 경우 관련 결과 목록에 추가됩니다.

결과 형식 지정 및 반환

검색과 일치하는 튜토리얼이 없으면 함수는 아무것도 발견되지 않았음을 나타내는 친숙한 메시지를 반환합니다. 일치하는 항목이 있는 경우 이 함수는 각 튜토리얼의 제목, URL, 날짜 및 작성자(가능한 경우)를 표시하는 형식이 지정된 번호 목록을 작성합니다. 서식은 제목에 마크다운 스타일의 굵은 글씨를 사용하므로 이를 지원하는 클라이언트에서 눈에 띕니다. 최종 서식이 지정된 텍스트는 단일 문자열로 반환됩니다.

오류 처리

이 함수에는 대상 예외 처리가 포함됩니다.

requests.exceptions.RequestException 은(는) 시간 초과 또는 연결 불량과 같은 네트워크 문제를 포착합니다.

ValueError (. JSON()에 의해 발생 가능) 은(는) 응답이 유효한 JSON이 아닌 경우를 포착합니다.

일반Exception 핸들러는 예상치 못한 다른 것을 포착합니다.

각 오류는 프로그램을 중지하는 대신 호출자에게 설명 메시지를 반환합니다.

서버 시작

하단에는if name == “main” : 블록은mcp.run() 스크립트가 직접 실행되는 경우에만 실행되도록 합니다. 이 단계에서는 MCP 서버를 시작하여search_ibmtutorials 도구를 MCP Inspector와 같이 모든 MCP 클라이언트에서 사용할 수 있도록 합니다. 이 도구는 MCP 서버 문제를 해결하고 디버깅하는 데 유용합니다. 이 도구는 MCP 서버를 디버깅하고 예상 동작을 검증하는 데 사용할 수 있는 UI를 제공합니다.

3단계. IDE에 MCP 서버 추가

이제 서버를 구축했으므로 사용하기 전에 IDE에서 서버를 활성화해야 합니다. 프로토콜과의 다양한 수준의 통합으로 MCP를 지원하는 클라이언트가 많이 있습니다. MCP 공식 웹사이트에서는 다양한 예시 클라이언트 목록을 제공합니다.
Cursor가 설치되어 있는 경우 다음 지침에 따라 Cursor 내에 MCP 서버를 추가할 수 있습니다.

Cursor 설정을 열고 도구 및 통합으로 이동합니다. 새 MCP 서버를 선택하고 mcp.js 파일에 붙여넣습니다. 이 파일은 Cursor가 새 탭에서 열리는 파일입니다. <YOUR PATH>을(를) 현재 디렉토리로 바꿔야 합니다. 터미널에서 pwd를 실행하여 전체 경로를 가져올 수 있습니다. Cursor와 MCP에 대한 자세한 내용은 Cursor 문서를 참조하세요.

{
  &quot;mcpServers&quot;: {
    &quot;tutorials&quot;: {
      &quot;command&quot;: &quot;fastmcp&quot;,
      &quot;args&quot;: [&quot;run <YOUR PATH>/ibmtutorialmcpserver/server.py&quot;],
      &quot;env&quot;: {
      }
    }
  }
}

Microsoft VS Code 사용자인 경우 여기에 링크된 지침을 사용하여 MCP 서버를 추가할 수 있습니다. 계속하기 전에 Copilot이 VS Code에 설정되어 있는지 확인하세요.
파일을 사용하여 MCP 서버를 활성화하려면 이 프로젝트의 디렉토리에 .vscode/mcp.json 파일을 생성하고 이 코드를 복사하여 파일에 붙여넣습니다. <YOUR PATH>을(를) 현재 디렉터리로 바꾸어야 합니다. 터미널에서 pwd를 실행하여 전체 경로를 가져올 수 있습니다.

&quot;servers&quot;: {
		&quot;IBM Tutorials&quot;: {
			&quot;type&quot;: &quot;stdio&quot;,
			&quot;command&quot;: &quot;fastmcp&quot;,
			&quot;args&quot;: [
				&quot;run&quot;,
				&quot;<YOUR PATH>/ibmtutorialmcpserver/server.py&quot;
			]
		},
	},

4단계. MCP 서버 사용

이제 MCP 서버를 활성화했으니 서버를 실행하여 server.py에서 만든 도구를 사용할 수 있도록 해 보겠습니다. VS Code를 사용하는 경우 다음 문서를 확인하세요.

IDE 채팅에서 "IBM 시계열 튜토리얼이 무엇인가요?"라고 질문합니다. 다음은 수신된 아웃풋을 보여 주지만, 사용 중인 모델과 IDE에 따라 응답이 달라질 수 있습니다.

아웃풋:

Here are some IBM time series tutorials:

Time series forecasting with Lag-Llama (zero-shot learning)
Tutorial link
Predict overnight low temperatures using the Lag-Llama model in a zero-shot learning scenario.

Using the watsonx.ai Time Series Forecasting API to predict energy demand
Tutorial link
Predict energy demand with the watsonx.ai Time Series Forecasting API.
Authors: Aleksandra Kłeczek and Meredith Syed

Let me know if you want details or help with a specific tutorial.

훌륭합니다! 에이전트는 시계열과 관련된 튜토리얼을 검색하기 위해 만든 search_ibmtutorials 도구를 사용할 수 있었습니다.

요약

이 튜토리얼에서는 원하는 MCP 클라이언트를 사용하여 모든 튜토리얼을 검색할 수 있는 MCP 서버를 구축하는 방법을 배웠습니다. 원격 JSON 인덱스를 검색하고, 검색어를 기반으로 결과를 필터링하고, 읽을 수 있는 형식으로 반환하는 단일 검색 도구로 MCP 서버를 만들었습니다. fastmcp를 사용하여 도구를 등록 및 실행하고, 데이터 가져오기를 요청하고, 네트워크, 구문 분석 및 예기치 않은 문제에 대한 오류 처리를 포함합니다. 서버를 실행하면 MCP 클라이언트에서 서버에 연결하여 모든 튜토리얼을 실시간으로 조회할 수 있습니다.