anti-patterns

안티패턴 — 직접 만들 때

1. 한 서버에 모든 도구 다 넣기

사양 설계 원칙 2를 어김. 시스템별로 쪼개라. — mcp-architecture

2. 첫 릴리스에 쓰기 도구 포함

create_*, delete_*, update_*는 보안 검토 후. 처음에는 read-only로. → 04-MCP-보안

3. stdout으로 print 디버깅

프로토콜 즉시 깨짐. 모든 로그는 stderr.

4. 도구 docstring을 비워둠

LLM이 docstring을 보고 호출 결정한다. 비면 호출도 안 한다. 용도와 인자 의미를 한국어/영어 어느 쪽이든 명확하게.

5. 큰 결과를 통째로 반환

컨텍스트 초과·지연. 요약 + 페이지네이션 + 잘림 표시.

6. 토큰을 코드/.mcp.json에 하드코딩

환경변수만 사용. project 스코프는 Git에 커밋된다.

7. 예외를 그대로 throw

LLM이 다음 행동을 결정 못 함. isError: true로 메시지 반환.

8. 동기 I/O로 외부 API 호출

stdio 서버가 멈추면 호스트도 멈춘다. async/await(Python httpx.AsyncClient, TS fetch).

9. 사용자 동의 없이 부작용 일으키기

호스트가 도구 호출 전 동의를 묻는 것은 기능이다. 동의를 우회하는 트릭(자동 승인 hook 등)을 만들지 말 것.

10. README 없이 배포

사내 MCP라도 README가 있어야 한다: 설치, 환경변수, 도구 목록, 권한 표면, 보안 가정.