영양 데이터를 위한 MCP 서버 구축하기

MCP (Model Context Protocol) 서버는 AI 클라이언트에게 모델이 기억에 의존하여 제품 라벨을 회상하도록 요청하는 대신, 좁고 조사 가능한 영양 정보 조회 도구를 제공합니다. DietlyAPI를 Model Context Protocol로 래핑(Wrapping)하면 Claude, Cursor 및 기타 MCP 호스트가 필요할 때 실제 영양 성분(macros)을 가져온 다음, 찾은 내용을 정확하게 설명할 수 있습니다. 이 가이드에서는 Python을 사용하여 두 개의 도구를 갖춘 작지만 완전한 서버를 구축합니다.

왜 추측보다 도구가 나은가

언어 모델(Language models)은 영양에 대해 유창하게 말하지만, 구체적인 수치에 대해서는 자주 틀립니다. 도구 호출(Tool call)은 이를 변화시킵니다. 모델이 "그릭 요거트"를 요청하면, 출처와 100g당 기준이 포함된 실제 기록을 받아와서 값을 지어내는 대신 해당 값을 보고합니다. 호스트가 언제 호출할지 추론할 수 있도록 범위를 작게 유지하세요.

1. 명확한 의도를 가진 두 가지 도구 정의

search_foods(쿼리 및 선택적 작은 제한)와 get_food(Dietly 음식 ID)로 시작하세요. 식단을 파싱하고, 다이어트를 선택하고, 계획을 한 번에 세우려고 시도하는 하나의 모호한 도구는 피해야 합니다. 좁은 범위의 도구가 모델이 올바르게 사용하기에 더 쉽습니다.

{"name":"search_foods",
 "description":"Search Dietly's food catalog by product or food name.",
 "inputSchema":{"type":"object",
...

2. Python SDK를 사용한 완전한 서버

공식 mcp 패키지는 FastMCP 헬퍼를 제공합니다. 각 도구는 일반적인 비동기 함수(async function)이며, 일반 딕셔너리(dictionary)를 반환하면 SDK가 프로토콜을 처리합니다. 이 서버는 GET /search 및 GET /food/{id}를 호출하며 API의 의미를 보존합니다.

import httpx
from mcp.server.fastmcp import FastMCP

...

3. API의 의미 보존

검색 결과가 비어 있을 때 일치하는 항목을 임의로 만들어내지 마세요. 또한, Null 허용 값(nullable values)은 0으로 기본값을 설정하기보다 Null 상태를 유지하세요. 사람이 숫자가 어디서 왔고 Dietly가 얼마나 확신하는지 볼 수 있도록 source와 confidence를 출력값으로 전달하세요. 데이터 도구의 가치는 불확실성을 매끄럽게 다듬지 않는 데 있습니다.

4. 호스트에 서버 등록하기

MCP 호스트는 stdio (표준 입출력)를 통해 서버를 실행합니다. Claude Desktop의 경우 설정 파일(config file)에 추가하면 되며, Cursor 및 기타 호스트에서도 동일한 형식이 적용됩니다.

{
  "mcpServers": {
    "dietly-nutrition": {
...

로컬에 설치 및 실행하기

서버에는 두 가지 의존성(dependencies)이 필요합니다: MCP SDK와 HTTP 클라이언트입니다. 가상 환경(virtual environment)에 이를 설치하고, 위의 코드를 server.py로 저장한 뒤 실행하세요. MCP 서버는 기본적으로 stdio를 통해 통신하므로, 로컬 사용을 위해 열어야 할 포트나 인터넷에 노출해야 할 요소가 없습니다.

python -m venv .venv && source .venv/bin/activate
pip install "mcp[cli]" httpx
python server.py

개발 중에는 MCP 커맨드 라인 인스펙터(command-line inspector)를 사용하여 각 도구(tool)를 수동으로 호출하고, 호스트가 받게 될 가공되지 않은 JSON을 확인할 수 있습니다. 이는 실제 클라이언트에 연결하기 전에 필드 전달(field passthrough)이 제대로 작동하는지 확인하는 가장 빠른 방법입니다. mcp dev server.py를 실행하여 인스펙터를 여세요. 서버는 호출 간에 상태(state)를 유지하지 않으므로 자유롭게 재시작할 수 있습니다. 호스트가 자동으로 다시 연결하고 도구 목록을 다시 나열합니다.

5. 모델에게 결과 사용법 알려주기

권장 호스트 지침(host instruction): 특정 식품에 대해 search_foods를 호출하세요. 100g당 기준임을 명시하고, 선택된 제품명과 브랜드를 언급하며, 영양 성분을 확인할 수 없는 경우 이를 알리세요. 영양 데이터는 답변을 뒷받침하는 용도로 사용할 수 있지만, 이를 진단이나 개인적인 의료 권고로 전환하지 마세요.

6. 키(key) 및 제한 사항 보호하기

로컬 읽기 전용 도구의 경우 익명 액세스(anonymous access)도 괜찮습니다. 더 높은 제한(limits)을 위해 키를 추가하는 경우, 키가 트랜스크립트(transcript)에 유출되지 않도록 도구 인자(tool arguments)나 프롬프트가 아닌 호스트 환경(host environment)에서 로드하세요. 429 응답을 받으면 Retry-After를 기다려 준수하고 재시도 횟수를 제한하세요. Open Food Facts에서 파생된 출력이 공개적으로 표시될 때는 API 약관에서 요구하는 출처 표기를 포함해야 합니다.

신뢰하기 전에 테스트하세요

정확한 제품, 일반적인 식품, 그리고 의도적인 오타를 입력하여 테스트해 보고, 모델이 추측하는 대신 도구 (tool)를 호출하는지, 그리고 결과가 없을 때 이를 설명할 수 있는지 확인하세요. 도구가 조용히 건너뛰어지는 것은 도구가 없는 것보다 더 나쁩니다. 답변이 여전히 권위 있게 들리기 때문입니다. 만약 호스트에 도구 호출 (tool calls)을 기록하는 방법이 있다면, 초기 단계에서 실제 세션을 몇 번 모니터링하세요. 특정 제품 질문에는 모델이 search_foods를 호출하고, 일반적인 질문에는 모델 자체의 지식으로만 답변하는지 확인해야 합니다. 일상적인 사용에서 통합 (integration)의 신뢰성을 만드는 것은 원시 코드 (raw code)가 아니라 바로 이러한 균형입니다.

다음 단계: 모든 필드에 대해 OpenAPI 스키마 (OpenAPI schema)를 검토하고, API 가이드 (API guide)를 읽은 후, MCP가 아닌 통합을 위해 Python 퀵스타트 (Python quickstart)를 사용해 보세요.

원문 게시지: getdietly.com. 데이터 출처: Dietly Nutrition API — 85만 개 이상의 식품 데이터, 무료 티어 이용 가능.