Mini Agent 03 · MCP

这是将 mini_agent_03_tool 的旅行 Tool 分离为 MCP Server 的小型实战项目。 FastAPI Backend 不直接 import Tool 函数，而是通过 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 子进程运行。一个 Agent 同时使用两种 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

练习与执行顺序

请遵守三个进程的执行顺序。确认前一步正常后再进入下一步， 这样可以轻松区分问题出在哪个连接上。

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 步 · 确认调用结构

在运行代码之前，先确认以下四个文件的作用。

第 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，也不要输出到屏幕和日志中。

第 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

打开第二个终端并运行。

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 的连接

在第三个 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

打开第四个终端并运行。

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. 确认一个 Round 中只执行一个 Tool。

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 将两个 MCP Server 中发现的 Tool Schema 加上 Server prefix 后 传递给 OpenAI Responses API。由于 parallel_tool_calls=False，GPT 在一个 Round 中 只提出一个 Tool。Backend 返回 Tool 结果后，GPT 选择下一个 Tool， 在没有 Function Call 的情况下直接回答之前，重复 Agent Loop。