127개의 도구를 갖춘 MCP 서버를 처음부터 구축하며 배운 점

Model Context Protocol (MCP)는 AI 에이전트가 도구와 통신하는 방식입니다. Claude Code, Cursor, Windsurf — 이들은 모두 이를 사용합니다. 하지만 대부분의 MCP 서버는 5~10개의 도구를 가지고 있습니다. 저는 127개의 도구를 가진 서버를 구축했습니다. 왜일까요? 저는 The Sovereign Hive라는 로컬 AI 운영 플랫폼을 실행하고 있기 때문입니다. 이 플랫폼은 멀티 에이전트 스웜 (multi-agent swarms)을 조정하고, 보안 스캔을 실행하며, 지식 그래프 (knowledge graph)를 관리하고, 제가 구축하는 모든 것의 중추 역할을 합니다. 모든 에이전트에는 도구가 필요하며, 저는 8개의 서로 다른 MCP 서버를 연결하는 것에 지쳤습니다. 그래서 모든 것을 하나의 서버, 하나의 포트, 하나의 헬스 엔드포인트 (health endpoint)로 통합했습니다.

도구 카테고리

카테고리	도구 개수	예시
File I/O	11	read, write, copy, move, delete, head, tail, wc
Search	6	grep, glob, find_symbol, find_references, search_replace
Git	10	status, diff, log, blame, commit, branch, stash, tag
Code Analysis	6	lint, complexity, dead_code, dependency_graph
Browser Automation	7	navigate, screenshot, click, fill, evaluate, snapshot
Docker	8	ps, logs, exec, images, inspect, run, stop, stats
Semantic Memory	7	store, search, relate, observe, get, list, delete
Monitoring	4	health_probe, logs_tail, service_status, uptime_check
HTTP/Web	5	fetch, request, dns_lookup, url_encode, curl_equivalent
Web Search	1	DuckDuckGo via ddgs (API 키 없음)
System	7	system_info, process_list, env_vars, port_check, disk_usage
Data Parsing	7	json_query, csv, yaml, toml, ini, xml, json_format
Database	3	sqlite_query, sqlite_schema, sqlite_tables
Archive	5	zip/tar create, extract, list
Text/Transform	8	diff, regex, base64, hash, token_estimate, string_transform
Crypto	4	generate_secret, uuid, hmac, password_hash
Notebook	3	read, create, add_cell
Task/Todo	4	create, list, update, complete
Prompt Engineering	4	build, chain, message_format, library
Thinking/Reasoning	4	sequential_think, decision_matrix, assumption_check, pros_cons
API Testing	4	graphql_query, websocket_send, api_test, openapi_parse
Comms Hub	3	post, read, channels
Ollama	2	list models, generate

아키텍처 결정 사항

모든 도구는 동일한 시그니처를 가진 비동기 함수 (async function)입니다:

async def tool_name ( args : dict ) -> dict : 입력은 항상 dict입니다. 출력은 항상 dict입니다. 시그니처에 예외는 없습니다 — 에러는 {"error": "..."} 안에 담깁니다. 모든 도구는 MCP 메타데이터를 포함합니다: TOOL_META = { " name " : " grep_recursive " , " description " : " 디렉토리 트리 내의 파일들에서 정규 표현식 패턴을 검색합니다. " , " inputSchema " : { ... } # JSON Schema } 이는 어떤 MCP 클라이언트라도 소스 코드를 읽지 않고도 도구를 발견하고, 파라미터를 확인하며, 호출할 수 있음을 의미합니다. 레지스트리(Registry)는 stdio와 HTTP/SSE 전송 방식을 모두 지원합니다: mcp_server.py — stdin/stdout을 통한 JSON-RPC (Claude Code 직접 통합용) mcp_server_sse.py — /tools, /tools/call, /mcp, /sse, /health 엔드포인트를 가진 FastAPI

필수적인 외부 의존성은 없습니다. 모든 도구는 가능한 경우 Python 표준 라이브러리(stdlib)를 사용합니다. 브라우저 도구에는 Playwright가 필요하고, Docker 도구에는 Docker가 필요합니다. 하지만 나머지 112개의 도구는 FastAPI/uvicorn 외에 추가적인 pip 설치 없이 작동합니다.

시맨틱 메모리 시스템 (The Semantic Memory System)
이것은 구축 과정에서 가장 흥미로웠던 부분입니다. 이는 TF-IDF 유사도 검색을 사용하는 SQLite 기반의 지식 그래프(Knowledge Graph)로, 벡터 데이터베이스(Vector Database)나 임베딩 모델(Embeddings Model)이 필요하지 않습니다.

await memory_store ({ " name " : " project-x " , " content " : " Redis 캐싱을 사용하는 FastAPI 백엔드 " , " type " : " project " })
await memory_relate ({ " from " : " duayne " , " relation " : " builds " , " to " : " project-x " })
await memory_observe ({ " entity " : " project-x " , " content " : " 프로덕션에 배포됨 " })
results = await memory_search ({ " query " : " FastAPI 캐싱 백엔드 " })

엔티티(Entities), 관계(Relationships), 관찰(Observations) — 이 모든 것을 쿼리할 수 있습니다. 에이전트(Agents)는 GPU나 외부 서비스 없이도 세션 전반에 걸쳐 지속적인 지식을 구축할 수 있습니다.

다르게 한다면 (What I'd Do Differently)
첫날부터 MCP 메타데이터를 적용하겠습니다. 저는 기존 15개 도구에 이를 사후에 적용했습니다. 처음부터 이를 포함하여 구축하는 것이 훨씬 깔끔합니다. 도구를 파일당 하나씩 만드는 대신 파일별로 그룹화하겠습니다. 관련된 도구들(예: 모든 git 작업)은 함께 묶여 있어야 합니다. DDG HTML 스크래퍼 방식은 실패했습니다.

DuckDuckGo는 이제 스크래퍼(Scraper)에게 CAPTCHA를 제공합니다. ddgs 라이브러리를 사용하거나 검색 API(Search API) 비용을 지불하십시오. 직접 시도해 보세요. 전체 스택은 오픈 소스(Open Source)입니다: 개발 중에는 저장소(Repo)가 비공개 상태입니다 — 조기 액세스(Early Access)를 원하시면 저에게 DM을 보내주세요.