🚀 [Project] AI 내 직원 만들기: MCP 로컬 서버 구축과 오류의 정석

🛠️ 실전 트러블슈팅: fastapi-mcp와 보낸 48시간의 기록

Django에 익숙한 저에게 FastAPI는 매력적인 신세계였습니다. 하지만 'Zero Configuration'을 표방하는 fastapi-mcp 라이브러리를 만나면서 예상치 못한 난관에 부딪혔습니다.

 

1. mount() 메소드의 Deprecation 경고

대부분의 참조 문서에서는 mcp.mount(app)를 권장합니다. 하지만 최신 버전(25년 하반기 기준)에서는 이 메소드에 취소선이 그어지며 Deprecated 경고가 뜹니다.

• 해결책: 이제는 전송 방식에 따라 mount_http() 또는 mount_sse()를 명시적으로 사용해야 합니다. 공식 문서는 비동기 처리에 최적화된 mount_http()를 권장합니다.

 

2. "Client must accept text/event-stream" 서버 에러의 공포

권장 방식인 mount_http()를 적용하고 /mcp 경로를 확인했을 때, 저를 반긴 것은 화려한 관리자 페이지가 아닌 아래의 차가운 JSON 에러 메시지였습니다.

{"jsonrpc":"2.0","id":"server-error","error":{"code":-32600,"message":"Not Acceptable: Client must accept text/event-stream"}}

이 메시지 때문에 저는 "서버 세팅이 잘못되었다"고 판단하고 수 시간을 허비했습니다. 하지만 여기서 반전이 일어납니다. 브라우저에서 보이는 이 에러를 무시하고 실제 MCP 클라이언트(TradeNPU_AI)에서 도구를 호출하면 정상 작동합니다. 브라우저는 text/event-stream을 수락하도록 설정되어 있지 않기 때문에 발생하는 현상일 뿐, 서버는 이미 준비된 상태였던 것이죠.

 

3. mount_sse()의 함정과 405 에러

에러 메시지를 없애보려고 mount_sse()로 우회했을 때, 겉으로는 핑(Ping)이 오가며 정상처럼 보였습니다. 하지만 실제 도구를 호출하자 405 Method Not Allowed 에러가 발생했습니다. 분명 POST로 요청을 보내고 서버 로그에도 POST로 찍히는데, 원인 모를 거부 반응이 일어난 것이죠.

결론: 밤잠을 설쳐가며 내린 해답은 "오류 메시지를 믿지 말고 권장 세팅(mount_http)으로 밀어붙여라"였습니다. 겉모습(브라우저 결과)에 속지 않는 것이 이번 트러블슈팅의 핵심이었습니다.

---

 

🧠 깨달음의 기록: MCP와 Function Calling의 '진짜' 관계

실제 코드를 짜보며 이전에 제가 가졌던 오해들을 바로잡게 되었습니다.

 

1. MCP vs Function Calling? (비교 대상이 아닙니다)

과거의 저는 두 개념을 대등한 선택지로 보았습니다. 하지만 만들어보니 이 둘은 포함 관계에 가깝습니다.

• Function Calling: AI가 함수를 호출하는 행위와 방법론입니다.

• MCP (Model Context Protocol): 그 호출 과정을 규격화하고 표준화한 규약(Protocol)입니다. 즉, MCP 서버 안에서도 결국 Function Calling이 일어납니다. "어떤 방식이 더 품질이 좋을까?"라는 고민은 무의미합니다. 결국 호출된 함수가 내놓는 결과값의 제약이 품질을 결정하기 때문입니다.

 

2. 로컬 vs 원격? (결국은 '원격'이 답이다)

"필요할 때만 로컬 서버를 켠다"는 초기 발상은 '24시간 상주하는 AI 직원'이라는 목적에 부합하지 않습니다.

• 현실적 문제: 유동 IP 문제, 방화벽 개방의 위험성, 24시간 가동의 불안정성.

• 나아갈 방향: 제대로 된 업무 위임을 위해서는 MCP 서버 역시 원격 환경에서 안정적으로 호스팅되어야 합니다. "모두에게 이로운 서비스를 만들겠다"는 관점에서도 원격 배포는 필수적입니다.

---

 

⏭ 다음 단계: 실질적인 '도구'의 구현

이제 아키텍처와 서버 세팅에 대한 지루한(?) 씨름은 끝났습니다. 다음 글에서는 실제로 AI 직원이 업무를 수행할 수 있도록 DRF(Django REST Framework)를 활용해 구체적인 CRUD 엔드포인트를 만드는 과정을 공유하겠습니다.

 

---

💡 안내: 이 포스팅은 기존 네이버 블로그의 '개발용 MCP 로컬서버 만들기' 시리즈를 통합한 글입니다. fastapi-mcp 라이브러리를 사용하며 겪은 치명적인 오류들과, 이를 통해 정립한 MCP와 Function Calling의 올바른 관계를 다룹니다.

---

---

---