Model Context Protocol(MCP)의 첫 발걸음을 떼는 방법에 대해 명쾌하게 설명해 드리겠습니다. 자, 다들 집중하세요!

MCP “Hello, World!”

지난 시간, 우리는 “도대체 MCP가 왜 게임 체인저인가?”에 대해 깊이 있게 탐구했습니다. LLM(대규모 언어 모델)들이 세상과 상호작용하는 강력한 에이전트로 변모할 수 있도록 돕는 만능 아답터, 그게 바로 MCP라고 말씀드렸죠?

자, 오늘은 말이죠, 드디어 이론을 넘어 실전으로 뛰어드는 시간입니다!

빈 폴더에서 시작해서, 여러분의 첫 MCP 서버를 로컬은 물론 네트워크를 통해 원격으로도 실행하는 방법을 배우게 될 겁니다.

이 강의가 끝나면 여러분은 다음을 확실하게 마스터하게 될 겁니다.

uv를 활용한 전문적인 파이썬 개발 환경 설정
fastmcp와 mcp 라이브러리에서 @mcp.tool 데코레이터로 첫 툴 만들기
기본적인 두 가지 통신 방식, 즉 로컬(STDIO)과 원격(HTTP) 트랜스포트 완벽 이해
디버깅의 가장 친한 친구, MCP 인스펙터 사용법 익히기

자, 그럼 지체 없이 코딩의 세계로 뛰어들어 볼까요?!

1. 개발 환경 구축: 당신의 코딩 작업실!

무언가를 만들기 전에 뭐가 필요할까요? 맞습니다! 제대로 된 작업실이 필요하죠. 파이썬 개발에서는 이 작업실이 바로 격리된 프로젝트 환경, 다시 말해 **가상 환경(Virtual Environment)**입니다. 왜 중요하냐고요? 여러분 시스템 전체에 영향을 주지 않고, 특정 프로젝트에 필요한 도구들만 깔끔하게 설치할 수 있기 때문이죠.

번개처럼 빠르다고 해서 uv래요. (웃음) 자, uv를 다운로드하여 설치하셨다면, 터미널(명령 프롬프트)을 열고 따라 해 보세요.

uv는 파이썬이 설치되어 있지 않아도 설치할 수 있고, Rust로 작성되었기 때문에 매우 빠릅니다.* **macOS 및 Linux:** 터미널을 열고 다음 명령어를 입력하세요.

bash

$ curl -LsSf https://astral.sh/uv/install.sh | sh

* **Windows (PowerShell):** PowerShell을 열고 다음 명령어를 입력하세요.

powershell

PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

먼저, 프로젝트를 위한 새 디렉터리를 만들고 그 안으로 이동합니다.

mkdir mcp_tutorial
cd mcp_tutorial

mkdir mcp_tutorial

cd mcp_tutorial

다음으로, uv를 사용해서 새 가상 환경을 초기화합니다. 이건 마치 이 프로젝트만을 위한 깨끗한 빈 공구함을 만드는 것과 같아요.

uv init

uv init

이 명령어를 실행하면 .venv라는 디렉터리가 생겨날 겁니다. 여기가 바로 여러분의 프로젝트 라이브러리들이 살게 될 공간이죠.

이제 공구함에 도구들을 채워 넣어야겠죠? 우리는 공식 mcp 라이브러리와 고수준 fastmcp 라이브러리가 모두 필요합니다. uv add 명령으로 새 환경에 이들을 다운로드하고 설치할 수 있습니다.

uv add fastmcp
uv add mcp[cli]

uv add fastmcp

uv add mcp[cli]

잠깐! mcp[cli]에서 [cli]가 왜 붙었는지 궁금해하는 학생들 있죠? 으레 이런 질문이 나오기 마련입니다. mcp 패키지에는 선택적인 “추가 기능(extras)”이 포함되어 있어요. 여기서 cli는 명령줄 유틸리티를 포함한다는 뜻입니다. 완벽한 개발 환경을 위해서는 이걸 설치하는 것이 좋습니다.

마지막으로, 환경을 “활성화”해야 합니다. 이건 터미널에게 .venv 안에 있는 파이썬과 라이브러리를 사용하라고 알려주는 거예요. 운영체제에 따라 명령어가 약간 다릅니다.

Windows (PowerShell):

.venv\Scripts\Activate

1
2

.venv\Scripts\Activate
Linux 또는 macOS:

source .venv/bin/activate

1
2

source .venv/bin/activate

활성화되면 터미널 프롬프트 시작 부분에 (.venv) 또는 여러분의 디렉터리 이름이 보일 거예요. 축하합니다! 여러분의 전문 개발 환경이 이제 준비 완료입니다. 첫 MCP 서버를 만들 준비가 되었어요!

2. MCP의 심장: `@mcp.tool` 데코레이터!

여러분, MCP 서버의 절대적인 핵심은 바로 **툴(Tool)**입니다. 툴은 쉽게 말해, LLM에 새로운 기능을 제공하기 위해 노출하는 일반 파이썬 함수에 불과합니다.

우리는 가장 간단한 툴을 만들어볼 거예요. 이름을 받아서 인사말을 반환하는 함수죠. 이걸 fastmcp와 mcp 두 가지 방식으로 만들어서 차이점과 유사점을 직접 경험해 볼 겁니다.

fastmcp 방식: 쉽고 빠르게!

먼저 fastmcp로 시작해 봅시다. 이 라이브러리의 고수준 API는 과정을 정말 놀랍도록 직관적으로 만들어 줍니다.

hello_world_local_server_fast.py라는 새 파일을 만들고 다음 코드를 추가하세요.

from fastmcp import FastMCP

# 1. Initialize the MCP server
mcp = FastMCP("My FastMCP Server")

# 2. Define a tool
@mcp.tool()
def greet(name: str) -&gt; str:
    """A simple tool that returns a greeting."""
    return f"Hello, {name}!"

# 3. Make the script runnable
if __name__ == "__main__":
    mcp.run()

from fastmcp import FastMCP

# 1. Initialize the MCP server

mcp = FastMCP("My FastMCP Server")

# 2. Define a tool

@mcp.tool()

def greet(name: str) -> str:

"""A simple tool that returns a greeting."""

return f"Hello, {name}!"

# 3. Make the script runnable

if __name__ == "__main__":

mcp.run()

자, 이 코드를 한 줄씩 뜯어봅시다.

서버 초기화: FastMCP를 임포트하고 인스턴스를 생성합니다. "My FastMCP Server"는 이 서버의 사람이 읽을 수 있는 이름입니다.
툴 정의: 이것이 바로 마법입니다! 평범한 파이썬 함수 greet 위에 @mcp.tool() 데코레이터를 붙였습니다. fastmcp는 여러분의 함수를 자동으로 분석해서:
- 함수 이름(greet)을 툴 이름으로 사용합니다.
- 타입 힌트(name: str, -> str)를 사용해서 스키마를 만듭니다. 이건 클라이언트에게 어떤 종류의 입력을 보내고 어떤 종류의 출력을 기대해야 하는지 알려주는 역할을 합니다.
스크립트 실행 가능하게 만들기: if __name__ == "__main__": 블록은 파이썬의 표준적인 부분입니다. 여러분이 이 스크립트를 직접 실행할 때만 mcp.run()이 호출되도록 보장합니다. 별표 하나 더! 이건 아주 중요한데, 잠시 후 클라이언트 스크립트도 이 서버 스크립트를 실행하게 될 것이기 때문입니다.

이게 다입니다! 여러분은 방금 완벽한 MCP 서버를 작성했습니다. 이제 이 서버와 대화할 클라이언트만 있으면 됩니다.

3. 통신의 비밀: STDIO 트랜스포트!

동일한 머신에서 클라이언트와 서버가 함께 실행될 때, MCP는 STDIO 트랜스포트라는 간단하고 효율적인 통신 방법을 제공합니다.

STDIO는 “표준 입출력(Standard Input/Output)”의 약자입니다. 이 트랜스포트를 사용하면 클라이언트는 네트워크 포트에 연결하는 것이 아니라, 서버 스크립트를 서브프로세스로 실행합니다. 그리고 서버의 표준 입력에 메시지를 쓰고 표준 출력에서 응답을 읽음으로써 서버와 “대화”합니다.

이 방식은 로컬 개발에 완벽합니다. 왜냐고요? 빠르고, 네트워크 설정이 전혀 필요 없기 때문입니다!

fastmcp 클라이언트: 간편함의 극치!

클라이언트 역할을 할 hello_world_local_client_fast.py라는 두 번째 파일을 만드세요.

import asyncio
from fastmcp import Client

# 1. Create a client that points to the server script
client = Client("hello_world_local_server_fast.py")

async def call_tool(name: str):
    # 2. Connect to the server
    async with client:
        # 3. Call the 'greet' tool with arguments
        output = await client.call_tool("greet", {"name": name})

        # 4. Extract the text from the response
        extracted_text = output.content[0].text

        print(extracted_text)

# 5. Run the asynchronous code
asyncio.run(call_tool("Justine"))

import asyncio

from fastmcp import Client

# 1. Create a client that points to the server script

client = Client("hello_world_local_server_fast.py")

async def call_tool(name: str):

# 2. Connect to the server

async with client:

# 3. Call the 'greet' tool with arguments

output = await client.call_tool("greet", {"name": name})

# 4. Extract the text from the response

extracted_text = output.content[0].text

print(extracted_text)

# 5. Run the asynchronous code

asyncio.run(call_tool("Justine"))

자, 이것도 한땀 한땀 분석해봅시다.

클라이언트 생성: fastmcp에서 Client를 인스턴스화하고 서버 스크립트의 경로를 전달합니다. 이것이 바로 fastmcp의 강력한 단축키입니다. 클라이언트에게 “서버와 대화해야 할 때 이 파일을 실행해!”라고 알려주는 거죠.
연결: MCP의 클라이언트 상호작용은 비동기적입니다. async with client: 블록이 서버 서브프로세스를 시작하고 STDIO 통신 채널을 설정하는 작업을 처리합니다.
툴 호출: client.call_tool()이 메인 이벤트입니다. 실행하려는 툴의 이름(“greet”)과 인자 딕셔너리({"name": name})를 전달합니다.
결과 추출: call_tool의 응답은 구조화된 객체입니다. 간단한 텍스트 응답의 경우, 내용은 output.content[0].text에 있습니다.
실행: asyncio.run()이 전체 비동기 프로세스를 시작합니다.

이제 활성화된 터미널에서 클라이언트를 실행해 보세요. 클라이언트 스크립트만 실행한다는 점에 주목하세요!

python .\hello_world_local_client_fast.py
Hello, <code class="language-python">Justine</code>!

1 2	python .\hello_world_local_client_fast.py Hello, <code class="language-python">Justine</code>!

짜잔! Hello, Justine!가 출력되는 것을 볼 수 있을 겁니다.

mcp 라이브러리 방식: 좀 더 자세히!

이제 공식 mcp 라이브러리를 사용해서 동일한 로컬 서버와 클라이언트를 만들어봅시다. 이 방법을 통해 두 라이브러리의 설계 철학 차이를 명확하게 알 수 있을 겁니다.

먼저 서버입니다. hello_world_local_server_mcp.py 파일을 만드세요.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

@mcp.tool()
def greet(name: str) -&gt; str:
    return f"Hello, {name}!"

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

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My MCP Server")

@mcp.tool()

def greet(name: str) -> str:

return f"Hello, {name}!"

if __name__ == "__main__":

mcp.run()

어라? fastmcp 버전과 거의 똑같아 보이죠? 맞습니다! 유일한 차이점은 임포트 문입니다: from mcp.server.fastmcp import FastMCP.

일타 강사 저스틴의 팁: “두 라이브러리 이야기” 이 글의 저자가 1장에서 언급했듯이, fastmcp 라이브러리의 고수준 서버 API는 너무 훌륭해서 공식 mcp 라이브러리에 직접 통합되었습니다. 그래서 서버 코드가 거의 동일한 겁니다!

이제 클라이언트 차례입니다. mcp 라이브러리는 좀 더 저수준(low-level)이고 명시적입니다. 연결 세부 사항을 더 세밀하게 구성해야 하죠.

새 파일 hello_world_local_client_mcp.py를 만드세요.

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 1. Define how to run the server
server_params = StdioServerParameters(
    command="python",
    args=["hello_world_local_server_mcp.py"]
)

async def call_tool(name: str):
    # 2. Create a low-level STDIO client
    async with stdio_client(server_params) as (read, write):
        # 3. Create a protocol session on top of the client
        async with ClientSession(read, write) as session:
            # 4. Explicitly initialize the session
            await session.initialize()

            # 5. Call the tool on the session object
            result = await session.call_tool("greet", arguments={"name": name})

            extracted_text = result.content[0].text

            print(extracted_text)

if __name__ == "__main__":
    asyncio.run(call_tool("Justine"))

import asyncio

from mcp import ClientSession, StdioServerParameters

from mcp.client.stdio import stdio_client

# 1. Define how to run the server

server_params = StdioServerParameters(

command="python",

args=["hello_world_local_server_mcp.py"]

)

async def call_tool(name: str):

# 2. Create a low-level STDIO client

async with stdio_client(server_params) as (read, write):

# 3. Create a protocol session on top of the client

async with ClientSession(read, write) as session:

# 4. Explicitly initialize the session

await session.initialize()

# 5. Call the tool on the session object

result = await session.call_tool("greet", arguments={"name": name})

extracted_text = result.content[0].text

print(extracted_text)

if __name__ == "__main__":

asyncio.run(call_tool("Justine"))

코드가 확실히 더 장황해졌죠? 차이점을 하나씩 짚어봅시다.

서버 파라미터: 단순히 파일 이름을 전달하는 대신, StdioServerParameters 객체를 생성합니다. 이는 클라이언트에게 서버를 어떻게 실행할지 명시적으로 알려줍니다: python 명령어를 hello_world_local_server_mcp.py 인자와 함께 사용하라는 뜻이죠. 더 유연하지만, 코드가 더 필요합니다.
저수준 클라이언트: stdio_client 컨텍스트 매니저는 원시 프로세스 시작을 처리하고 read 및 write 스트림을 제공합니다.
클라이언트 세션: 이 원시 스트림을 ClientSession으로 감쌉니다. 이 객체는 MCP 프로토콜 자체, 즉 요청을 어떻게 포맷하고 응답을 어떻게 파싱하는지 등을 이해합니다.
초기화: mcp 라이브러리를 사용하면 서버와 초기 핸드셰이크를 수행하기 위해 await session.initialize()를 명시적으로 호출해야 합니다. fastmcp는 이 작업을 자동으로 처리해 줍니다.
툴 호출: 툴을 클라이언트 객체가 아닌 세션 객체에서 호출합니다.

이제 이 클라이언트 스크립트를 실행해 보세요.

python .\hello_world_local_client_mcp.py
Hello, <code class="language-python">Justine</code>!

1 2	python .\hello_world_local_client_mcp.py Hello, <code class="language-python">Justine</code>!

정확히 동일한 결과가 나옵니다! fastmcp 클라이언트는 mcp 클라이언트의 모든 단계를 내부적으로 수행하는 고수준 래퍼(wrapper)입니다. 간단한 경우에는 fastmcp가 많은 상용구 코드를 절약해 주죠. 반면, 공식 mcp 라이브러리는 연결 수명 주기에 대해 더 세밀한 제어를 제공합니다. 핵심은 이걸 아는 겁니다!

4. 네트워크를 넘어서: HTTP 트랜스포트!

STDIO는 로컬 개발에 아주 좋습니다. 하지만 MCP의 진정한 힘은 네트워크를 통해 서비스를 연결하는 능력에서 나옵니다. 여러분의 툴이 강력한 서버에서 실행되어야 하거나, 다른 개발자에게 서비스로 제공하고 싶다면 어떻게 해야 할까요?

바로 이때, HTTP 트랜스포트가 필요합니다.

HTTP를 사용하면 서버를 특정 네트워크 주소와 포트(예: 127.0.0.1:9000)에서 연결을 수신하는 독립 실행형, 장기 실행 프로세스로 실행합니다. 클라이언트는 동일한 머신, 로컬 네트워크의 다른 머신, 심지어 인터넷을 통해서도 이 URL에 연결할 수 있죠.

fastmcp 방식 (원격): 간결함은 여전하다!

우리 fastmcp 서버를 HTTP로 실행하도록 바꿔봅시다. 변경 사항은 거의 없습니다.

hello_world_remote_server_fast.py라는 새 파일을 만드세요.

from fastmcp import FastMCP

mcp = FastMCP("My Remote Server")

@mcp.tool
def greet(name: str) -&gt; str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    # The only change is here!
    mcp.run(transport="http", host="127.0.0.1", port=9000)

from fastmcp import FastMCP

mcp = FastMCP("My Remote Server")

@mcp.tool

def greet(name: str) -> str:

return f"Hello, {name}!"

if __name__ == "__main__":

# The only change is here!

mcp.run(transport="http", host="127.0.0.1", port=9000)

유일한 차이점은 mcp.run() 호출 부분입니다. 이제 transport, host, port를 명시합니다.

이번에는 서버 스크립트를 먼저 실행하고 계속 실행 상태로 유지해야 합니다.

python .\hello_world_remote_server_fast.py

1 2	python .\hello_world_remote_server_fast.py

fastmcp의 멋진 시작 배너가 보일 거예요.

╭─ FastMCP 2.0 ────────────────────────────────────────────────────────╮
│                                                                      │
│ _ __ ___ ______ __ __ _____________ ____ ____ │
│ _ __ ___ / ____/___ ______/ /_/ |/ / ____/ __ \ |___ \ / __ \│
│ _ __ ___ / /_ / __ `/ ___/ __/ /|_/ / / / /_/ / ___/ / / / / /│
│ _ __ ___ / __/ / /_/ (__ ) /_/ / / / /___/ ____/ / __/_/ /_/ / │
│ _ __ ___ /_/ \__,_/____/\__/_/ /_/\____/_/ /_____(_)____/ │
│                                                                      │
│ Server name: My Remote Server                                        │
│ Transport: Streamable-HTTP                                           │
│ Server URL: http://127.0.0.1:9000/mcp/                               │
│                                                                      │
...
INFO: Uvicorn running on http://127.0.0.1:9000 (Press CTRL+C to quit)

╭─ FastMCP 2.0 ────────────────────────────────────────────────────────╮

│ │

│ _ __ ___ ______ __ __ _____________ ____ ____ │

│ _ __ ___ / ____/___ ______/ /_/ |/ / ____/ __ \ |___ \ / __ \│

│ _ __ ___ / /_ / __ `/ ___/ __/ /|_/ / / / /_/ / ___/ / / / / /│

│ _ __ ___ / __/ / /_/ (__ ) /_/ / / / /___/ ____/ / __/_/ /_/ / │

│ _ __ ___ /_/ \__,_/____/\__/_/ /_/\____/_/ /_____(_)____/ │

│ │

│ Server name: My Remote Server │

│ Transport: Streamable-HTTP │

│ Server URL: http://127.0.0.1:9000/mcp/ │

│ │

...

INFO: Uvicorn running on http://127.0.0.1:9000 (Press CTRL+C to quit)

별표 세 개! Server URL: http://127.0.0.1:9000/mcp/ 이 부분에 주목하세요. 이것이 바로 클라이언트가 연결해야 할 엔드포인트입니다. 이 터미널 창은 그대로 열어두세요.

이제 클라이언트를 작성해 봅시다. 새 터미널 창을 열고 가상 환경을 활성화했는지 확인하세요. hello_world_remote_client_fast.py라는 파일을 만드세요.

import asyncio
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport

# 1. Define the transport with the server URL
transport = StreamableHttpTransport("http://localhost:9000/mcp/")

# 2. Create a client using the transport
client = Client(transport=transport)

async def main(name: str):
    async with client:
        output = await client.call_tool("greet", {"name": name})

        extracted_text = output.content[0].text

        print(extracted_text)

asyncio.run(main("Justine"))

import asyncio

from fastmcp import Client

from fastmcp.client.transports import StreamableHttpTransport

# 1. Define the transport with the server URL

transport = StreamableHttpTransport("http://localhost:9000/mcp/")

# 2. Create a client using the transport

client = Client(transport=transport)

async def main(name: str):

async with client:

output = await client.call_tool("greet", {"name": name})

extracted_text = output.content[0].text

print(extracted_text)

asyncio.run(main("Justine"))

다시 한번, Client가 구성되는 방식이 바뀌었습니다.

트랜스포트 정의: StreamableHttpTransport를 임포트하고 인스턴스를 생성하며, 서버 출력에서 확인했던 서버 URL을 전달합니다.
클라이언트 생성: 이 transport 객체를 transport= 키워드 인자를 사용해서 Client 생성자에 전달합니다.

이제 클라이언트를 실행해 보세요.

python .\hello_world_remote_client_fast.py
Hello, <code class="language-python">Justine</code>!

1 2	python .\hello_world_remote_client_fast.py Hello, <code class="language-python">Justine</code>!

성공입니다! 클라이언트가 실행 중인 서버에 HTTP를 통해 연결하여 올바른 응답을 받았습니다.

mcp 라이브러리 방식 (원격): 더 세밀하게!

mcp 라이브러리로도 같은 작업을 해봅시다. 서버 코드에는 구성 방식에 작은, 하지만 중요한 차이가 있습니다.

hello_world_remote_server_mcp.py를 만드세요.

from mcp.server.fastmcp import FastMCP

# 1. Host and port are configured in the constructor
mcp = FastMCP("My MCP Server", host="127.0.0.1", port=9000)

@mcp.tool()
def greet(name: str) -&gt; str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    # 2. Transport is specified in the run method
    mcp.run(transport="streamable-http")

from mcp.server.fastmcp import FastMCP

# 1. Host and port are configured in the constructor

mcp = FastMCP("My MCP Server", host="127.0.0.1", port=9000)

@mcp.tool()

def greet(name: str) -> str:

return f"Hello, {name}!"

if __name__ == "__main__":

# 2. Transport is specified in the run method

mcp.run(transport="streamable-http")

mcp를 사용하면 host와 port는 FastMCP 생성자에 전달되는 반면, transport 타입("streamable-http")은 run() 메서드에 전달됩니다.

이전 서버는 반드시 중지하세요! 이 서버를 실행하면, 기본 Uvicorn 웹 서버에서 좀 더 표준적인 출력이 보일 겁니다.python .\hello_world_remote_server_mcp.py INFO: Started server process [28768] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:9000 (Press CTRL+C to quit)

이것도 실행 상태로 유지하세요. 이제 새 터미널에서 클라이언트 차례입니다. hello_world_remote_client_mcp.py를 만드세요.

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main(name: str):
    # 1. Use the streamablehttp_client context manager
    async with streamablehttp_client("http://127.0.0.1:9000/mcp/") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            output = await session.call_tool("greet", arguments={"name": name})

            extracted_text = output.content[0].text

            print(extracted_text)

if __name__ == "__main__":
    asyncio.run(main("Justine"))

import asyncio

from mcp import ClientSession

from mcp.client.streamable_http import streamablehttp_client

async def main(name: str):

# 1. Use the streamablehttp_client context manager

async with streamablehttp_client("http://127.0.0.1:9000/mcp/") as (read, write, _):

async with ClientSession(read, write) as session:

await session.initialize()

output = await session.call_tool("greet", arguments={"name": name})

extracted_text = output.content[0].text

print(extracted_text)

if __name__ == "__main__":

asyncio.run(main("Justine"))

구조가 mcp STDIO 클라이언트와 매우 유사하죠? 핵심 변경 사항은 stdio_client를 streamablehttp_client로 교체하고 서버 URL을 전달하는 것입니다.

일타 강사 저스틴의 꿀팁: 밑줄(_)의 의미 여러분, (read, write, _) 튜플에서 밑줄(_)을 보셨을 겁니다. streamablehttp_client는 추가적인 HTTP 특정 정보(예: 응답 헤더)를 포함하는 세 번째 값을 반환합니다. 우리의 간단한 툴 호출에서는 이 값이 필요 없으므로, 표준 파이썬 관례에 따라 **버리는 변수(_)**에 할당한 겁니다.

클라이언트를 실행해 보세요.

python .\hello_world_remote_client_mcp.py
Hello, <code class="language-python">Justine</code>!

1 2	python .\hello_world_remote_client_mcp.py Hello, <code class="language-python">Justine</code>!

자, 보이시죠? 두 가지 주요 라이브러리를 사용해서 네트워크화된 MCP 서버를 성공적으로 구축하고 통신했습니다! 이것이 바로 여러분이 해낸 일입니다!

5. 디버깅의 치트키: MCP 인스펙터!

지금까지 여러분은 파이썬 클라이언트를 작성해서 파이썬 서버를 테스트했습니다. 하지만 툴이 제대로 작동하는지 빠르게 확인하고 싶거나, 반환되는 원시 JSON 데이터를 검사하고 싶다면 어떨까요? 매번 새 클라이언트 스크립트를 작성하는 건 너무 번거롭겠죠?

이때 등장하는 것이 바로 MCP 인스펙터입니다! 이것은 Postman이나 Insomnia와 같지만, Model Context Protocol 전용으로 만들어진 웹 기반 애플리케이션입니다. 개발과 디버깅에 없어서는 안 될 필수 도구죠.

인스펙터는 Node.js 애플리케이션입니다. Node.js를 먼저 설치했는지 확인하세요. npx 명령어(Node.js에 포함되어 있음)는 한 번에 패키지를 다운로드하고 실행할 수 있습니다.

원격 서버가 아직 실행 중인지 확인한 다음, 새 터미널에서 다음 명령을 실행하세요.

npx @modelcontextprotocol/inspector

1 2	npx @modelcontextprotocol/inspector

이 명령어를 처음 실행하면 npx가 패키지 설치 권한을 요청할 겁니다. y를 입력하고 Enter를 누르세요. 시작하면서 다음과 같은 출력이 보일 겁니다.

...
Starting MCP inspector...
Proxy server listening on localhost:6277
Session token:
,→ 2de1f4fe39be7c7a2e5ce2b3df254861689a0f0602756baca19ea3a4dad25217
Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to
,→ disable auth

MCP Inspector is up and running at:
http://localhost:6274

Opening browser...

...

Starting MCP inspector...

Proxy server listening on localhost:6277

Session token:

,→ 2de1f4fe39be7c7a2e5ce2b3df254861689a0f0602756baca19ea3a4dad25217

Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to

,→ disable auth

MCP Inspector is up and running at:

http://localhost:6274

Opening browser...

여러분의 웹 브라우저가 자동으로 http://localhost:6274로 열릴 겁니다. 만약 열리지 않으면, URL을 복사해서 붙여넣기만 하세요. 인스펙터 인터페이스가 보일 겁니다.

이제 실행 중인 greet 툴을 테스트하기 위해 인스펙터를 사용해 봅시다.

트랜스포트 구성: “Transport Type” 드롭다운에서 Streamable HTTP를 선택합니다.
URL 입력: “URL” 필드에 서버의 MCP 엔드포인트인 http://localhost:9000/mcp/를 입력합니다.
토큰 입력: 터미널로 돌아가서 긴 Session token을 복사합니다. 인스펙터 웹페이지의 “Configuration” 섹션 아래에 있는 “Proxy Session Token” 필드에 이 토큰을 붙여넣으세요. 이것은 여러분만이 이 인스펙터 세션을 사용할 수 있도록 하는 보안 조치입니다.
연결: 파란색 “Connect” 버튼을 클릭합니다. 성공하면 버튼이 녹색으로 바뀌고 “Connected”라고 표시될 겁니다.
툴 목록 확인: 왼쪽의 “Tools” 탭으로 이동합니다. “List Tools” 버튼을 클릭합니다.
툴 실행: 목록에서 greet 툴을 클릭합니다. 툴을 호출하기 위한 인터페이스가 나타날 거예요. “arguments” 섹션에서 name 매개변수 필드가 보일 겁니다. 값 필드에 “Inspector”라고 입력합니다.
결과 확인: “Run Tool” 버튼을 클릭합니다. 오른쪽에는 서버에서 받은 원시 JSON 응답이 보일 겁니다. content 블록 안에 “Hello, Inspector!”라는 텍스트가 보일 거예요.

여러분은 단 한 줄의 클라이언트 코드도 작성하지 않고 MCP 서버를 성공적으로 테스트했습니다! 인스펙터는 서버의 로직 구축에 집중할 수 있도록 해주는 강력한 동반자가 될 겁니다.

강의 마무리: 이제 시작일 뿐!

수강생 여러분, 오늘 정말 많은 것을 배웠습니다. 아무것도 없는 상태에서 시작해서, 네트워크로 연결되는 MCP 서버를 실행하기까지 엄청난 발전을 이뤘습니다!

오늘 강의에서 여러분이 마스터한 핵심 개념들을 다시 한번 짚어봅시다.

개발 환경: uv를 사용해서 깨끗하고 격리된 파이썬 프로젝트를 설정하고 필요한 MCP 라이브러리를 설치하는 방법을 배웠습니다.
핵심 툴: @mcp.tool 데코레이터는 MCP 서버의 심장이며, 파이썬 함수를 AI를 위한 기능으로 즉시 전환시켜 줍니다.
STDIO vs. HTTP: 이 두 가지 주요 트랜스포트 방법의 차이를 이제 명확히 이해했습니다. STDIO는 빠르고 로컬 기반의 서브프로세스 통신에, HTTP는 독립 실행형 네트워크 서버를 만드는 데 사용됩니다.
fastmcp vs. mcp: 두 라이브러리 간의 실질적인 차이점을 봤습니다. fastmcp는 더 간단하고 고수준의 클라이언트 경험을 제공하는 반면, 공식 mcp 라이브러리는 연결 수명 주기에 대한 더 명시적이고 세밀한 제어를 가능하게 합니다.
인스펙터는 당신의 친구: MCP 인스펙터를 사용해서 서버에 연결하고 테스트하는 방법을 익혔습니다. 이는 여러분의 개발 워크플로우를 극적으로 가속화할 겁니다.