CoreMCP

Mac mini의 도구를 한곳에서 관리하기

CoreMCP는 Mac mini에서 쓸 개인용 MCP 게이트웨이로 만들었습니다. 여러 도구를 AI 클라이언트마다 반복해서 등록하는 대신, 서버와 도구함을 한곳에서 관리하고 클라이언트는 /mcp 연결점을 사용하도록 구성했습니다.

연결 설정을 모으면 도구 목록과 상태도 같은 위치에서 확인할 수 있어야 합니다. 어떤 서버를 등록했는지, 그 서버의 도구가 목록에 있는지, 지금 호출해도 되는지는 서로 다른 질문입니다. 관리 화면과 호출 경로에서 이 질문들을 구분하는 것이 CoreMCP를 다듬는 데 필요한 작업이었습니다.

그중 하나가 2026년 5월 18일의 카탈로그 수정입니다. 서버를 재검증할 때 마지막으로 확인한 도구 목록까지 사라지지 않도록 바꿨습니다. 이 작업은 단순히 서버를 연결하는 것에서 더 나아가, 상태가 바뀌는 동안 무엇을 보여줄지 정하는 일이었습니다.

문서를 찾는 도구부터 범위를 정했다

프로젝트 폴더의 Markdown을 탐색하는 Project Docs MCP에는 프로젝트 목록, 문서 목록, 검색, 읽기, 프로젝트 소개 문서 요약 도구를 넣었습니다. 파일을 쓰거나 지우는 기능은 두지 않았습니다. 문서를 찾는 작업의 읽기 범위를 먼저 명확히 한 것입니다.

프로젝트 문서에서 특정 내용을 찾는 요청을 예로 들면 다음 순서로 도구를 조합할 수 있습니다.

project_docs.project_list로 프로젝트 후보를 찾습니다.
project_docs.project_docs_search로 필요한 키워드가 있는 문서를 좁힙니다.
project_docs.project_doc_read로 선택한 문서를 읽고 결과가 잘린 부분이 있는지 확인합니다.

이 순서에서는 처음부터 모든 프로젝트의 문서 본문을 가져올 필요가 없습니다. “어떤 프로젝트가 있는가”만 묻는다면 첫 단계에서 끝낼 수 있고, 내용을 분석하려면 검색과 읽기를 이어갑니다. 연결한 도구 수보다 요청에 필요한 읽기 범위를 결정하는 쪽이 작업을 이해하기 쉽습니다.

도구 이름에는 project_docs. 접두어를 붙였습니다. 같은 이름의 도구가 다른 서버에 있어도 어느 서비스에서 제공하는지 알 수 있게 하기 위해서입니다. 문서 경로는 허용된 프로젝트 범위 안으로 제한하고, 긴 응답은 잘릴 수 있도록 했습니다. 따라서 내용을 읽은 뒤에는 응답의 길이 제한도 함께 살펴야 합니다.

재검증하는 동안 이전 목록을 유지하기

기존 카탈로그 조회는 상태가 active인 서버만 포함했습니다. 그런데 수동 검증을 시작하면 새 카탈로그를 저장하기 전에 서버 상태가 validating으로 바뀝니다. 새 결과를 기다리는 구간에, 이전에 확인해 둔 도구 목록까지 조회 대상에서 빠지는 구조였습니다.

저는 검증 중인 서버도 마지막으로 확인한 카탈로그를 보여주도록 조회 조건을 바꿨습니다. 핵심 조건은 아래와 같습니다.

-- 변경 전
AND s.status = 'active'

-- 변경 후
AND s.status IN ('active', 'validating')

도구 목록뿐 아니라 리소스와 프롬프트를 조회하는 경로, 도구함의 서비스 목록 처리도 함께 맞췄습니다. 한 화면에만 목록이 남고 다른 경로에서는 사라진다면 같은 서버를 두고 다른 판단을 하게 되기 때문입니다.

이 선택에는 두 정보가 함께 있습니다. 서버는 지금 재검증 중이고, 마지막으로 확인했던 도구들은 여전히 이 서버에 속합니다. 검증 중이라는 상태를 감추지 않으면서 도구의 위치도 잃지 않도록 한 것입니다. 새 결과가 준비되기 전까지 무엇을 유지할지 정하는 일이었습니다.

목록에 보이는 것과 호출 허용을 나누기

검증 중인 서버의 목록을 유지해도 곧바로 모든 호출을 허용하는 것은 아닙니다. 카탈로그에는 validating 서버를 포함하면서, 사용할 수 없는 서비스 정보에는 service_not_active를 남겼습니다. 도구의 존재와 현재 사용 가능성을 따로 설명할 수 있도록 했습니다.

도구별 정책도 별도로 둡니다. callable은 호출 허용, visible_only는 목록 표시만 허용, hidden은 목록에서도 숨기는 정책입니다. 서버가 재검증 중인지와 운영자가 이 도구의 호출을 허용했는지는 다른 조건이므로 같은 상태로 합치지 않았습니다.

이 구분이 없으면 “목록에는 있는데 왜 실행이 안 되는가”를 알아보기 어렵습니다. 운영할 때는 서버 등록, 도구 노출, 호출 권한, 실제 요청 결과를 각각 살펴야 합니다. Simulator에도 최종 답변과 도구 호출 흐름, 실행 메타데이터를 나눠 두었습니다. 답변만 읽고 끝내지 않고 어떤 도구를 거쳐 결과가 나왔는지 확인할 수 있게 한 구성입니다.

평상시 목록보다 상태 전환을 검사하기

카탈로그 수정에는 검증 중인 상태를 만드는 회귀 테스트를 함께 뒀습니다. 테스트용 서비스를 등록하고 검증한 뒤 기본 도구함에 넣습니다. 그다음 상태를 다시 validating으로 바꿔 MCP의 tools/list와 Playground 양쪽에서 같은 도구가 계속 보이는지 확인합니다.

이 검수 조건에서 중요한 것은 상태를 일부러 바꾸는 순서입니다. 서버가 정상 상태일 때 목록이 보이는지만 확인하면, 재검증 시작과 새 결과 저장 사이의 빈틈은 지나칠 수 있습니다. 목록을 소비하는 두 경로를 함께 검사하는 것도 같은 이유입니다.

실제 서버를 다루는 화면에는 등록, 검증, 실패, 복구처럼 상태가 이어집니다. 저는 이 수정에서 “정상일 때 표시되는가”에 더해 “상태가 바뀌는 동안 마지막 정보가 유지되는가”를 확인 조건으로 남겼습니다. 도구를 하나 더 연결할 때도 이 조건을 함께 살필 수 있습니다.

연결점을 줄인 뒤 남는 운영 책임

CoreMCP는 한 사람이 관리하는 개인용 도구함을 목표로 만들었습니다. 클라이언트가 사용하는 연결점은 하나로 모았지만, 게이트웨이의 인증과 상태, 로그를 관리하는 일은 여전히 필요합니다. 반복 등록을 줄이는 선택에는 중앙에서 운영 상태를 살피는 책임이 따라옵니다.

같은 구성을 만들고 싶다면 반복해서 등록하는 도구가 무엇인지부터 정하면 좋습니다. 그다음 읽기 범위가 명확한 한 업무를 연결하고, 목록 표시와 호출 허용을 구분해 확인합니다. 마지막으로 실패한 요청이 어느 도구와 상태를 거쳤는지 추적할 수 있는지 살펴야 합니다.

재검증을 시작해도 마지막으로 확인한 도구 목록은 보여 주고, 지금 호출할 수 있는지는 따로 알리도록 했습니다. 새 도구를 연결할 때도 정상 상태의 목록만 보지 않고 재검증 중의 목록과 호출 안내를 함께 확인하려고 합니다.