Molayo

© 2026 Molayo

Dev.to헤드라인2026. 05. 31. 14:01

Lab 06: Streamable HTTP를 사용하여 첫 번째 MCP 서버 구축하기 | Strands Agentic AI

요약

Streamable HTTP 전송 방식을 사용하여 직접 MCP(Model Context Protocol) 서버를 구축하고 Strands Agent와 연결하는 방법을 다루는 튜토리얼입니다. 산술 연산을 수행하는 Calculator MCP 서버를 통해 에이전트가 도구를 호출하는 원리를 학습합니다.

핵심 포인트

  • MCP 서버, 클라이언트, 에이전트 간의 상호작용 이해
  • Streamable HTTP 전송 방식을 이용한 서버 구축
  • 커스텀 MCP 도구를 통한 내부 API 및 로직 노출 방법
  • Strands Agent의 자동 도구 호출 메커니즘 학습

이전 실습(Labs)에서는 Strands Agent를 기존 MCP 서버에 연결하여 그 도구(Tools)들을 사용해 보았습니다.

하지만 만약 여러분만의 MCP 서버를 직접 만들고 싶다면 어떻게 해야 할까요?

그것이 바로 이번 실습에서 우리가 할 일입니다.

우리는 덧셈, 뺄셈, 곱셈, 나눗셈과 같은 산술 연산을 제공하는 Calculator MCP Server를 구축할 것입니다. 그런 다음 Streamable HTTP 전송(Transport) 방식을 사용하여 Strands Agent를 해당 서버에 연결할 것입니다.

이 튜토리얼이 끝날 때쯤, 여러분은 MCP 생태계의 양면을 모두 이해하게 될 것입니다:

  • MCP Server (MCP 서버)
  • MCP Client (MCP 클라이언트)
  • Strands Agent (Strands 에이전트)

📚 Strands Agentic AI 실습 시리즈

⬅️ 이전: Lab 06: STDIO를 통한 MCP 연결

📍 현재: Lab 07: 첫 번째 MCP 서버 구축

➡️ 다음: Lab 08: 고급 MCP 도구 및 멀티 도구 워크플로우

🚀 학습 내용

이번 실습에서는 다음을 배웁니다:

  • MCP Server를 만드는 방법
  • MCP 도구(Tools)가 노출되는 방식
  • Streamable HTTP 전송(Transport)의 작동 원리
  • 커스텀 MCP 서버에 Strands Agent를 연결하는 방법
  • 에이전트가 MCP 도구를 자동으로 호출하는 방법

🤖 왜 직접 MCP 서버를 구축해야 할까요?

이전에는 기존의 MCP 서버를 소비(Consume)했습니다.

Agent (에이전트)
  ↓
AWS Documentation MCP Server

이제는 직접 구축할 것입니다.

Agent (에이전트)
  ↓
Your MCP Server (여러분의 MCP 서버)
...

이를 통해 표준 MCP 인터페이스를 통해 다음을 노출할 수 있습니다:

  • 내부 API (Internal APIs)
  • 데이터베이스 (Databases)
  • 비즈니스 로직 (Business Logic)
  • 엔터프라이즈 시스템 (Enterprise Systems)
  • 커스텀 애플리케이션 (Custom Applications)

🏗️ 아키텍처 (Architecture)

우리의 솔루션은 다음과 같습니다:

User (사용자)
  ↓
Strands Agent (Strands 에이전트)
...

에이전트는 계산을 직접 수행하지 않습니다.

대신, 계산을 MCP 도구(Tools)에 위임합니다.

🛠️ 사전 요구 사항 (Prerequisites)

시작하기 전에 다음 사항이 준비되었는지 확인하십시오:

  • Python 3.10 이상
  • Strands SDK
  • MCP SDK
  • AWS Bedrock 액세스 권한
  • uv 설치

의존성 설치:

pip install strands-agents
pip install mcp

📜 전체 스크립트

이 예제는 다음을 생성합니다:

  • MCP Calculator Server
  • 4개의 계산기 도구 (Calculator tools)
  • Strands Agent
  • 대화형 채팅 루프 (Interactive chat loop)

에이전트는 계산이 필요할 때마다 MCP 도구를 자동으로 사용합니다.

⚙️ Step 1: MCP 서버 생성하기

mcp = FastMCP("Calculator Server")

이 코드는 새로운 MCP 서버를 초기화합니다.

다음과 같이 생각하면 쉽습니다:

Web Framework (웹 프레임워크)
    ↓
Routes (라우트)

하지만 AI 도구(tools)를 위한 것입니다.

MCP Server (MCP 서버)
    ↓
Tools (도구)

⚙️ Step 2: MCP 도구 생성하기

덧셈 도구 (Addition Tool)

@mcp.tool(description="Add two numbers together")
def add(x: int, y: int) -> int:
    return x + y

뺄셈 도구 (Subtraction Tool)

@mcp.tool(description="Subtract one number from another")
def subtract(x: int, y: int) -> int:
    return x - y

곱셈 도구 (Multiplication Tool)

@mcp.tool(description="Multiply two numbers together")
def multiply(x: int, y: int) -> int:
    return x * y

나눗셈 도구 (Division Tool)

@mcp.tool(description="Divide one number by another")
def divide(x: float, y: float) -> float:
    if y == 0:
...

모든 도구는 MCP를 통해 자동으로 검색(discoverable) 가능해집니다.

추가적인 등록 과정은 필요하지 않습니다.

⚙️ Step 3: MCP 서버 시작하기

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

이 코드는 Streamable HTTP 전송 방식(transport)을 사용하여 MCP 서버를 실행합니다.

서버 엔드포인트(Server endpoint):

이제 다른 MCP 클라이언트(clients)가 연결할 수 있습니다.

⚙️ Step 4: 백그라운드 스레드에서 서버 실행하기

server_thread = threading.Thread(
    target=start_calculator_server,
    daemon=True
...

왜 그럴까요?

다음이 동시에 실행되어야 하기 때문입니다:

Calculator Server (계산기 서버)
      +
Strands Agent (Strands 에이전트)

백그라운드 스레드는 에이전트가 실행되는 동안 서버를 계속 활성화된 상태로 유지합니다.

⚙️ Step 5: MCP 클라이언트 연결하기

def create_streamable_http_transport():
    return streamablehttp_client(
        "http://localhost:8000/mcp/"
...

이 코드는 MCP 클라이언트(MCP Client) 연결을 생성합니다.

아키텍처(Architecture):

Agent (에이전트)
   ↓
MCP Client (MCP 클라이언트)
...

⚙️ Step 6: 사용 가능한 도구 검색하기

tools = streamable_http_mcp_client.list_tools_sync()

이것이 MCP의 가장 큰 장점 중 하나입니다.

도구를 수동으로 등록하는 대신:

tools=[add, subtract]

클라이언트가 도구들을 자동으로 검색합니다.

예시:

사용 가능한 MCP 도구:

add
...

⚙️ Step 7: 에이전트 (Agent) 생성

agent = Agent(
    model=bedrock_model,
    system_prompt=system_prompt,
...

참고:

tools=tools

이 도구들은 MCP 서버로부터 직접 가져온 것입니다.

별도의 커스텀 통합(custom integration)이 필요하지 않습니다.

⚙️ Step 8: 대화형 계산기 어시스턴트 (Interactive Calculator Assistant)

while True:
    user_input = input("Question: ")

...

이것은 대화형 계산기를 생성합니다.

예시:

Question:
What is 125 * 42?

Agent:

5250

내부 동작:

Agent
 ↓
multiply()
...

▶️ 애플리케이션 실행

실행:

python agent.py

또는:

uv run labs/07-mcp-calculator-server/agent.py

📊 상호작용 예시

사용자 (User)

What is 25 + 17?

에이전트 워크플로우 (Agent Workflow)

Question
   ↓
Agent Reasoning
...

응답 (Response)

25 + 17 = 42

🔍 내부에서는 어떤 일이 일어났을까요?

당신이 다음과 같이 질문했을 때:

What is 25 + 17?

에이전트는:

  1. 요청을 이해했습니다.
  2. 덧셈이 가능한 MCP 도구를 찾았습니다.
  3. 도구를 호출(invoke)했습니다.
  4. 결과를 받았습니다.
  5. 응답을 생성했습니다.

실제 계산은 MCP 서버에서 수행되었습니다.

LLM (대규모 언어 모델) 내부가 아닙니다.

💡 이것이 중요한 이유

이 간단한 계산기는 강력한 개념을 보여줍니다.

오늘:

add()
subtract()
multiply()
...

내일:

Create Customer
Generate Invoice
Query Database
...

정확히 동일한 MCP 아키텍처가 엔터프라이즈 애플리케이션으로 확장됩니다.

🎯 핵심 요약 (Key Takeaways)

  • MCP 서버는 AI 에이전트에게 도구를 노출합니다.
  • FastMCP는 서버 구축을 단순하게 만듭니다.
  • Streamable HTTP는 원격 통신을 가능하게 합니다.
  • 에이전트는 도구를 자동으로 검색(discover)합니다.
  • MCP는 도구 구현과 에이전트 로직을 분리합니다.
  • 이 패턴은 계산기에서 엔터프라이즈 시스템까지 확장 가능합니다.

📚 소스 코드

실습 소스 코드:
당신의 GitHub 저장소

🔗 계속 학습하기

⬅️ 이전 실습

Lab 06: Connecting to MCP with STDIO

➡️ 다음 실습

Lab 08: Advanced MCP Tools & Multi-Tool Workflows

🚀 다음 실습

다음 튜토리얼에서는 더욱 정교한 MCP 도구 (tools)를 구축하고, 도구 스키마 (tool schemas)를 탐색하며, 에이전트 (agents)가 복잡한 작업을 해결하기 위해 여러 MCP 기능 사이에서 어떻게 선택할 수 있는지 배워보겠습니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0