build-mcp-serverlisted

# build-mcp-server 외부 서비스를 에이전트에 붙이는 방법은 둘이다. 공식 MCP 서버를 깔아 API 전체를 여는 것, 그리고 필요한 일만 하는 작은 서버를 직접 만드는 것. 이 스킬은 **두 번째**를 위한 것이다. 사람이 이걸 택하는 이유는 대개 능력을 넓히려는 게 아니라 **좁히려는** 것이다 — "알림 채널의 서버 경보만 모아 줘"는 원하지만, 그 대가로 에이전트가 워크스페이스 전체를 뒤지고 메시지를 보낼 수 있게 되는 건 원하지 않는다. **핵심 원칙**: - **도구 목록이 곧 권한이다.** 범용 조회 도구(`call_api(method, params)` 같은 것)를 하나라도 두면 좁히기는 전부 무효다. 노출하는 도구는 사람이 실제로 시킬 일 2~4개로 끝낸다. - **막는 자리는 한 곳이 아니다.** 목록 조회만 막으면 다른 데서 알아낸 ID로 상세를 열 수 있다. 들어오는 경로마다 같은 기준으로 막는다. - **자격 증명은 코드 밖, 대화 밖.** 값이 에이전트의 대화 기록을 지나가면 그 기록에 영원히 남는다. 사용자가 직접 실행하는 설치 스크립트로 받아, 서버 코드 폴더 **밖**에 권한 600으로 둔다. - **셸에 토큰을 남겨 두면 서버는 장식이다.** 환경 변수로도 같은 API를 부를 수 있으면 좁힌 게 아니다. 서버가 돌기 시작하면 셸 쪽 자격 증명은 걷어낸다. --- ## 실행 절차 ### 1. 무엇을 좁힐지 먼저 정한다 코드를 쓰기 전에 **허용 목록의 축**을 정한다. 이게 서버 전체의 모양을 결정한다. 축은 그 서비스가 이미 가지고 있는 분류를 빌리는 게 가장 좋다 — 메일이면 라벨, 채팅이면 채널, 드라이브면 폴더, 이슈 트래커면 프로젝트. 사람이 그 서비스의 화면에서 이미 쓰는 단위라 "뭘 열어 뒀는지"를 나중에도 안 헷갈린다. 사용자에게 확인할 것은 대개 하나다 — **어느 항목을 열 것인가.** 후보를 추측하지 말고 실제 목록을 조회해 보여준다. 다만 아직 못 읽는 항목의 내용을 이름만 보고 단정하지 말고, 근거가 이름뿐이면 그렇다고 밝힌다. 권한(스코프)도 여기서 정한다. 읽기만 시킬 거면 읽기 전용 스코프만 받는다 — 나중에 도구를 안 만들면 그만이라고 미루면, 자격 증명 자체가 쓰기 가능한 상태로 남는다. ### 2. 파일 세 개를 만든다 서버 모음 폴더(예: `~/mcp-servers/`) 아래 서비스별 폴더를 만들고 세 파일을 둔다. | 파일 | 하는 일 | |---|---| | `server.py` | stdio JSON-RPC 루프 + 도구 구현 + 게이트 | | `setup.py` | 사용자가 직접 실행해 자격 증명을 만든다 | | `test_gate.py` | 허용 목록 밖이 막히는지 검사 | `assets/server.template.py`와 `assets/setup.template.py`��� 복사해 시작한다. 표준 라이브러리만 쓴다 — 의존성이 없으면 설치 절차도 없고, 파이썬 경로만 맞으면 어느 하네스에서든 그대로 돈다.