Mini Agent 03 · MCP

Это небольшой практический проект, в котором Travel Tool из mini_agent_03_tool вынесен в MCP Server. FastAPI Backend не импортирует Tool-функции напрямую, а обнаруживает и вызывает Tool через MCP Client.

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 и смысл tools/list·tools/call в MCP не меняются. Меняется то, кто запускает 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: обнаружение Tool, опубликованных MCP Server

• 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

Проверьте Tool, опубликованные MCP Server.

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 и 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.

6. Измените вопрос на 서울에서 15만원 이하 호텔을 찾아 주세요. и сравните выбор Tool.

7. С помощью 수하물 정책 읽기 проверьте обращение к Resource, а не к Tool.

Порядок завершения

Нажмите 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, а URL MCP Server и права на выполнение управляются Backend.

Backend добавляет Server prefix к Schema Tool, обнаруженным на двух MCP Server, и передаёт их в OpenAI Responses API. Поскольку parallel_tool_calls=False, GPT предлагает один Tool за один Round. Когда Backend возвращает результат Tool, GPT выбирает следующий Tool, и Agent Loop повторяется до тех пор, пока не будет дан ответ без Function Call.