MCP 서버를 처음 붙이는 5분 가이드 — 글

요약 — 세 줄

클라이언트의 설정 파일을 연다.
mcpServers 안에 서버 한 줄을 넣는다.
클라이언트를 다시 켜고 도구 목록에 뜨는지 본다.

설정 파일 한 곳에 서버 한 줄을 넣고, 클라이언트를 다시 켜 도구 목록에 뜨는지 보는 데까지. 예시는 등대 데스크와 파일 정리함(:1031)으로 들지만, 다른 클라이언트도 파일 위치만 다르고 순서는 같습니다.

1준비물

클라이언트 하나 — 여기서는 등대 데스크 3.8 이상. 지원 기능은 클라이언트 쪽에서 확인합니다.
Node.js 20 이상 — 서버를 npx 로 받아 띄웁니다.
서버가 만질 폴더 하나 — 예: ~/문서. 처음에는 중요한 파일이 없는 폴더로 시작하세요.

2설정 파일 열기

등대 데스크는 설정을 JSON 파일 하나에 둡니다. 파일이 없으면 빈 파일을 만들고 {} 만 적어 두세요.

터미널 — 설정 파일 열기

# macOS
open ~/Library/Application\ Support/Deungdae/config.json
# Linux
xdg-open ~/.config/deungdae/config.json
# Windows (PowerShell)
notepad $env:APPDATA\Deungdae\config.json

3서버 넣기

mcpServers 아래에 서버 이름을 키로, 띄우는 명령을 값으로 넣습니다. 마지막 인자가 서버가 만질 수 있는 폴더입니다.

config.json

{
  "mcpServers": {
    "file-keeper": {
      "command": "npx",
      "args": ["-y", "@osolgil/file-keeper", "~/문서"]
    }
  }
}

이미 다른 서버가 있다면 쉼표로 이어 붙입니다. 이름(file-keeper)은 대화 창의 도구 목록에 그대로 보이니 짧게 짓습니다.

4다시 켜고 확인

클라이언트를 완전히 끄고 다시 켭니다. 대화 창의 도구 단추에 파일 정리함 · 도구 11이 뜨면 붙은 것입니다. 원격 서버라면 주소만 넣으면 되는데, 두 방식은 이렇게 다릅니다.

항목	로컬 (stdio)	원격 (HTTP)
어디서 도나	내 컴퓨터 — 클라이언트가 띄운다	제공자 서버 — 주소로 붙는다
설정에 적는 것	`command` · `args`	`url` 하나
인증	대개 없음 — 폴더 권한으로 막는다	OAuth 로그인 창에서 권한을 고른다
알맞은 곳	파일 · 로컬 데이터베이스 · 터미널	브라우저 · 캘린더 · 팀 채팅

5막히면

도구 목록이 비어 있다면

대부분 npx 를 못 찾는 경우입니다. 터미널에서 which npx 로 경로를 확인하고, 설정의 "command" 에 전체 경로를 적어 보세요. JSON 의 쉼표 하나가 빠져도 클라이언트는 조용히 서버를 건너뜁니다.¹

그래도 안 되면 클라이언트 로그를 봅니다. 등대 데스크는 ~/Library/Logs/Deungdae/mcp.log 에 서버가 뱉은 첫 줄을 남깁니다.²

설정 파일을 JSON 검사기에 한 번 넣어 보면 빠진 쉼표를 바로 찾습니다. 본문으로
로그 위치는 클라이언트마다 다릅니다 — 클라이언트 상세 쪽의 ‘설정 예시’ 에 적어 둡니다. 본문으로

MCP 서버를 처음 붙이는
5분 가이드