Mini Agent 03 · MCP

mini_agent_03_toolの旅行ToolをMCP Serverとして分離した小さな実践プロジェクトです。FastAPI BackendはTool関数を直接importせず、MCP Clientを通じてToolを発見し呼び出します。

Streamlit :8501
  → FastAPI Backend :8000
    → Travel MCP Server :8010/mcp (Streamable HTTP)
    → Policy MCP Server (stdio 자식 프로세스)
    → OpenAI Responses API가 한 번에 Tool 하나를 선택
      → Tool 결과를 돌려주고 필요한 만큼 반복

Travel ServerはBackendと独立したプロセスとポートで実行します。Policy ServerはBackendがstdio子プロセスとして実行します。1つのAgentが2つのTransportを一緒に使いながら、Server prefixとルーティング、順次Tool依存性を学習します。

stdio学習例で変わる点

Tool実装とMCPのtools/list・tools/callの意味は変わりません。変わるのはServerの実行主体とメッセージを伝えるTransportです。

stdio
Backend → 자식 MCP Server

Streamable HTTP
Backend :8000 → 네트워크 → MCP Server :8010

FrontendはMCP Serverを直接呼び出しません。ユーザーのリクエストは常にAgent Backendを経由し、GPTがToolを提案し、Backendが権限確認・MCP呼び出し・結果伝達を担当します。GPTはMCP Toolを直接実行しません。

Related MCP server: Trip Planner MCP Server

提供機能

• GET /health: Backend状態

• GET /api/mcp/status: 別のMCP Server接続状態

• GET /api/mcp/tools: MCP Serverが公開したToolの発見

• GET /api/mcp/resources: MCP Resourceの発見

• POST /api/mcp/run: 質問 → Tool選択 → MCP呼び出し → 回答Trace

• GET /api/mcp/baggage-policy: MCP Resourceの読み取り

実習および実行順序

3つのプロセスの実行順序を守ります。前の段階が正常か確認してから次の段階に進むと、どの接続で問題が発生したか簡単に区別できます。

0. 구조 확인
→ 1. 가상환경 준비
→ 2. OpenAI 환경변수 설정
→ 3. MCP Server 실행 (:8010)
→ 4. Backend 실행 (:8000)
→ 5. Backend에서 MCP 연결 확인
→ 6. GPT·Tool·Resource API 확인
→ 7. Frontend 실행 (:8501)
→ 8. 화면에서 전체 Trace 확인

0段階・呼び出し構造の確認

コードを実行する前に、次の4つのファイルの役割を確認します。

1段階・仮想環境とパッケージ準備

最初の1回だけ実行します。

cd C:\mini_agent_st\mini_agent_03_mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

すでに.venvを作成した場合は、次の授業からはアクティベーションのみ行います。

cd C:\mini_agent_st\mini_agent_03_mcp
.\.venv\Scripts\Activate.ps1

2段階・OpenAI環境変数設定

.env.exampleを.envにコピーし、発行されたAPI Keyを入力します。

Copy-Item .env.example .env

OPENAI_API_KEY=발급받은_API_KEY
OPENAI_MODEL=gpt-4.1-mini

API KeyはGitにCommitしたり、画面やログに出力したりしません。

3段階・MCP Server実行

最初のターミナルを開いて実行します。

cd C:\mini_agent_st\mini_agent_03_mcp
.\.venv\Scripts\Activate.ps1
python .\mcp_server\travel_server.py

このターミナルは終了しません。MCP endpointはhttp://127.0.0.1:8010/mcpです。コンソールに127.0.0.1:8010でサーバーが実行されたという案内が表示されたら、次の段階に進みます。

4段階・FastAPI Backend実行

2番目のターミナルを開いて実行します。

cd C:\mini_agent_st\mini_agent_03_mcp
.\.venv\Scripts\Activate.ps1
uvicorn backend.app.main:app --reload --port 8000

Backend自体の状態を確認します。

Invoke-RestMethod http://127.0.0.1:8000/health

予想結果の核心値は次のとおりです。

status      : ok
mcp_servers : travel=streamable-http, policy=stdio

5段階・BackendとMCP Server接続確認

3番目のPowerShellターミナルで実行します。

Invoke-RestMethod http://127.0.0.1:8000/api/mcp/status

正常ならstatus=connected、tool_count=3が表示されます。ここで503が発生した場合は、Frontendを実行する前に、最初のターミナルのMCP ServerとTRAVEL_MCP_URLを先に確認します。

6段階・GPT、ToolとResource API確認

MCP Serverが公開したToolを確認します。

Invoke-RestMethod http://127.0.0.1:8000/api/mcp/tools |
    ConvertTo-Json -Depth 10

travel__get_current_weather、travel__search_hotels、policy__get_hotel_policyと各arguments Schemaが表示される必要があります。

Agent全体のフローを呼び出します。

$body = @{
    question = "부산 날씨와 15만원 이하 호텔을 찾고 호텔 정책도 알려 주세요."
} | ConvertTo-Json
Invoke-RestMethod `
    -Uri http://127.0.0.1:8000/api/mcp/run `
    -Method Post `
    -ContentType "application/json" `
    -Body $body |
    ConvertTo-Json -Depth 10

応答で次の順序を確認します。

available_tools
→ travel__get_current_weather
→ travel__search_hotels
→ 검색 결과에서 hotel_id 획득
→ policy__get_hotel_policy(hotel_id)
→ Function Call이 없는 응답에서 Loop 종료
→ 일반적으로 llm_calls = Tool 실행 수 + 1
→ answer

Resourceも確認します。

Invoke-RestMethod http://127.0.0.1:8000/api/mcp/baggage-policy |
    ConvertTo-Json -Depth 10

7段階・Streamlit Frontend実行

4番目のターミナルを開いて実行します。

cd C:\mini_agent_st\mini_agent_03_mcp
.\.venv\Scripts\Activate.ps1
streamlit run frontend\app.py --server.port 8501

ブラウザでhttp://127.0.0.1:8501を開きます。FastAPI Swaggerはhttp://127.0.0.1:8000/docsです。

8段階・画面実習

次の順序でボタンを実行します。

1. 上部のMCP接続状態がconnectedか確認します。

2. MCP Tool発見を押してTool名とSchemaを確認します。

3. 基本質問でMCP Agentを実行します。

4. 1ラウンドでToolが1つずつ実行されるか確認します。

5. ホテル検索結果のhotel_idがPolicy Tool argumentsとして渡されるか確認します。

6. 質問を서울에서 15만원 이하 호텔을 찾아 주세요.に変えてTool選択を比較します。

7. 수하물 정책 읽기でToolではなくResource照会を確認します。

終了順序

各実行ターミナルでCtrl+Cを押します。

Frontend 종료
→ Backend 종료
→ MCP Server 종료

MCP Serverだけを先に終了した後、/api/mcp/statusを再度呼び出すと、Backendが503を返す接続失敗の実習もできます。

比較ポイント

環境変数

BACKEND_API_URL=http://127.0.0.1:8000
TRAVEL_MCP_URL=http://127.0.0.1:8010/mcp
MCP_HOST=127.0.0.1
MCP_PORT=8010
OPENAI_API_KEY=발급받은_API_KEY
OPENAI_MODEL=gpt-4.1-mini

FrontendはBackendのみを呼び出し、MCP Server URLと実行権限はBackendが管理します。

Backendは2つのMCP Serverで発見したTool SchemaにServer prefixを付けてOpenAI Responses APIに渡します。parallel_tool_calls=Falseなので、GPTは1ラウンドでToolを1つ提案します。BackendがTool結果を返すとGPTが次のToolを選択し、Function Callなしで回答するまでAgent Loopを繰り返します。