Laravel 앱 내부에 MCP 서버 구축하기
AI 에이전트에게는 단순히 스크래핑된 UI 그 이상의 것이 필요합니다. 적절한 권한을 가지고 특정 도구를 호출할 수 있는 방법이 필요합니다. 이것이 바로 Model Context Protocol (MCP)이 하는 역할입니다.
최근 저는 MCP 서버를 Laravel 애플리케이션에 직접 통합했습니다. 이를 안전하게 구축하기 위한 아키텍처 결정 사항들을 공유하고자 합니다.
접수원 비유
앱을 하나의 오피스 빌딩이라고 생각해보세요.
- 웹 UI는 사람들을 위한 로비입니다.
- REST API는 시스템을 위한 직원 전용 입구입니다.
- MCP 서버는 AI 에이전트를 위한 접수 데스크입니다.
에이전트는 ID를 제시하며 특정 작업을 요청합니다. 접수원은 에이전트에게 빌딩 열쇠를 통째로 넘겨주지 않습니다. 권한을 확인하고, 하나의 작업을 수행한 뒤, 구조화된 답변을 반환합니다.
주요 설계 결정 사항
1. 단일 엔드포인트 사용
다양한 도구를 위해 여러 라우트를 만들지 마세요. 하나의 /mcp 엔드포인트를 사용하세요. 프로토콜이 도구 탐색(tool discovery)을 자동으로 처리합니다. 단일 접점(surface)을 유지하는 것이 보안을 강화하고 문서를 작성하기에 더 쉽습니다.
2. 이중 인증 지원
호출 주체에 따라 서로 다른 보안 방식이 필요합니다:
- 퍼스트 파티 호출자(CLI 도구 등)는 Sanctum 개인 액세스 토큰(personal access tokens)을 사용합니다.
- 서드 파티 에이전트(사용자를 대신하여 동작)는 OAuth 2.1을 사용합니다.
드라이버 스타일의 리졸버(resolver)를 사용하여 두 방식을 모두 처리하세요. 도구 코드는 사용자가 어떻게 로그인했는지가 아니라, 인증된 사용자가 누구인지에만 집중해야 합니다.
3. 기존 RBAC 적용
인증은 호출자가 누구인지만 증명할 뿐입니다. 그들이 무엇을 할 수 있는지는 여전히 확인해야 합니다. 모든 도구는 기존의 권한(ability)에 매핑되어야 합니다. 사용자가 웹 UI에서 참가자를 볼 수 없다면, MCP를 통해서도 볼 수 없어야 합니다.
4. 데이터 출력 제한
데이터베이스 모델 전체를 반환하지 마세요. MCP 출력을 공개 API처럼 취급하세요. 에이전트가 필요로 하는 특정 필드만 반환하세요. 이는 의도치 않은 데이터 유출을 방지합니다.
보안 테스트
테스트는 시스템이 올바르게 실패하는지 증명해야 합니다. 다음 사항을 테스트하세요:
- 권한이 없는 사용자가 403 Forbidden 에러를 받는지 확인합니다.
- 권한이 있는 사용자가 허용된 필드만 받는지 확인합니다.
자율 에이전트를 사용할 때, 잘 짜여진 테스트 스위트는 데이터 유출을 막는 가장 강력한 방어 수단입니다.
요약
책임감 있는 MCP 서버를 구축하려면 다음 세 가지 규칙을 따르세요:
- 적절한 스킴(scheme)을 사용하여 모든 호출자를 인증하세요.
- 기존 권한 모델을 사용하여 모든 도구에 대한 권한을 부여하세요.
- 모든 도구 출력을 제한된 공개 리소스로 취급하세요.