4부 15장. 클라이언트 측 활용 베스트 프랙티스

좋은 MCP 서버를 만드는 일은 어렵다. 그런데 더 어려운 일이 하나 있다. 바로 사람들이 그 서버를 실제로 쓰게 만드는 것이다. 서버를 아무리 잘 만들어도 연결이 번거롭고, 승인 팝업이 너무 많고, 설정 파일이 제각각이면 결국 팀원들은 다시 복붙과 수작업의 세계로 돌아간다.

여기서 중요한 사실이 있다. MCP는 서버만의 기술이 아니다. 호스트와 클라이언트, 서버가 함께 돌아가는 구조다. 즉, 서버가 훌륭해도 클라이언트 연결 경험이 나쁘면 전체 시스템은 불편해진다.¹ 이번 장에서는 우리가 만든 PKM-MCP를 Claude Desktop, Claude Code, Cursor, VS Code, Continue, ChatGPT Apps 같은 클라이언트에서 어떻게 연결하고, 어떻게 관리하면 덜 귀찮고 더 오래 쓰게 되는지 정리해보자.

클라이언트 경험이 곧 채택률이다

클라이언트 쪽 베스트 프랙티스는 화려한 기술보다 생활 감각에 가깝다. 누가, 어떤 화면에서, 어떤 순간에, 어떤 도구를 쓰는지를 기준으로 설계해야 한다는 뜻이다.

예를 들어 PKM-MCP를 개인 회고와 메모 검색용으로 쓴다면 Claude Desktop 같은 대화형 클라이언트가 잘 맞는다. 반대로 코드 작성 중에 설계 메모와 회의록을 함께 찾아야 한다면 Claude Code, Cursor, VS Code, Continue 같은 개발 도구 안쪽이 더 편하다. 같은 서버라도 어디에 붙이느냐에 따라 체감 품질이 완전히 달라진다.

그래서 실전에서는 서버를 먼저 고르는 게 아니라, 사용 장면을 먼저 고르는 편이 낫다. "이 서버로 무엇을 할까?"보다 "이 서버를 어느 화면에서 가장 자주 부를까?"를 먼저 물어야 한다. PKM-MCP가 진짜 자주 쓰이려면, 메모 검색은 빠르고, 쓰기 도구는 신중하고, 인증은 덜 번거롭고, 설정은 팀이 함께 유지할 수 있어야 한다.

Claude Desktop와 Claude Code

Claude 계열 클라이언트는 MCP를 이해하기에 가장 자연스러운 출발점이다. 다만 둘의 성격은 꽤 다르다. Claude Desktop은 대화 중심이고, Claude Code는 작업 중심이다. 둘 다 좋지만, 잘 맞는 자리가 다르다.

Claude Desktop: 가장 쉬운 체험장

Claude Desktop은 "메모를 찾아줘", "이번 주 메모를 요약해줘" 같은 자연어 요청을 시험하기에 좋다. 특히 개발자가 아닌 팀원에게 PKM-MCP를 보여줄 때도 진입 장벽이 낮다. 설정 화면에서 서버를 연결하고, 도구 승인만 해주면 바로 써볼 수 있기 때문이다.

처음에는 로컬 stdio 서버로 시작하는 편이 안전하다. 서버를 내 컴퓨터에서 직접 띄우기 때문에 네트워크 인증 문제를 덜 신경 써도 되고, 디버깅도 단순하다. PKM-MCP 초기 버전이라면 아래처럼 붙이는 방식이 가장 이해하기 쉽다.

{
  "mcpServers": {
    "pkm": {
      "command": "uv",
      "args": ["run", "python", "-m", "pkm_mcp"],
      "env": {
        "PKM_NOTES_DIR": "/Users/me/notes"
      }
    }
  }
}

여기서 중요한 팁이 몇 가지 있다. 첫째, GUI 앱은 터미널의 PATH를 그대로 물려받지 않는 경우가 많으니 node, python, uv, npx 같은 명령이 자주 안 보인다. 이런 때는 명령어의 절대 경로를 쓰는 편이 속 편하다. 둘째, 비밀값은 args에 넣지 말고 env로 넘겨야 한다. 셋째, 설정을 바꾼 뒤에는 앱을 완전히 재시작해야 반영되는 경우가 많다. 망치 아이콘은 보이는데 도구가 안 뜨는 날의 절반은 이 세 가지에서 시작된다.

Claude Desktop에서 PKM-MCP를 쓸 때는 도구 수를 적게 유지하는 것이 특히 중요하다. 메모 검색, 이번 주 요약, 노트 열기처럼 바로 이해되는 것만 먼저 노출하자. 도구가 너무 많으면 모델도 헷갈리고, 사람도 헷갈린다. 메모 앱에 리모컨 버튼 37개가 달려 있다고 생각해보면 금방 감이 온다.

Claude Code: 팀 개발에 더 강한 선택

Claude Code는 MCP를 훨씬 운영 친화적으로 다룬다. CLI로 서버를 추가하고, 목록을 보고, 제거하고, 현재 세션 상태를 확인할 수 있다. 특히 local, project, user 스코프를 지원해서 개인용 실험 서버와 팀 공용 서버를 구분하기 좋고, 프로젝트 스코프 설정은 루트의 .mcp.json 파일로 공유할 수 있다.²

예를 들어 로컬 PKM-MCP를 현재 프로젝트에만 연결하고 싶다면 이런 식으로 시작할 수 있다.

claude mcp add --scope project --transport stdio pkm -- uv run python -m pkm_mcp

이미 3부에서 PKM-MCP를 HTTP 모드와 OAuth까지 붙여 두었다면, 팀 공용 서버는 이렇게 추가하는 쪽이 더 낫다.

claude mcp add --scope project --transport http pkm https://mcp.example.com/mcp

Claude Code의 장점은 단순히 연결이 된다는 데 있지 않다. HTTP와 SSE 서버를 추가할 수 있고, /mcp로 상태를 확인할 수 있으며, 프로젝트 스코프 설정을 버전 관리에 태우기 좋다. 서버가 list_changed 알림을 보내면 도구 목록을 다시 읽을 수 있고, HTTP/SSE 연결이 끊겨도 재연결 로직이 들어 있다.² 운영하는 사람 입장에서는 "왜 오늘은 도구가 안 보여요?" 같은 질문이 줄어드는 방향이다.

PKM-MCP 기준으로 보면 Claude Code는 이런 조합이 좋다. 개발자는 Claude Code 안에서 설계 메모를 찾고, 이슈를 바탕으로 코드를 고치고, 변경 사항을 다시 노트에 기록한다. 메모 서버가 단순 검색기를 넘어서 개발 흐름의 일부가 되는 순간이다.

Cursor, VS Code, Continue

개발 도구 계열 클라이언트들은 같은 MCP라도 조금씩 다른 습관을 요구한다. 어떤 도구는 JSON 구조가 다르고, 어떤 도구는 Agent 모드에서만 MCP가 보이고, 어떤 도구는 시크릿 입력을 별도로 받는다. 여기서 핵심은 "모든 클라이언트를 하나처럼 다루려 하지 말 것"이다. 같은 PKM-MCP라도 클라이언트에 맞는 연결법을 택해야 한다.

Cursor: 프로젝트 문맥과 함께 쓰기 좋다

Cursor는 메모 검색이 코딩 흐름 안으로 자연스럽게 들어올 때 강하다. 예를 들어 "지난주 아키텍처 회의에서 인증 만료 시간 어떻게 정했지?" 같은 질문을 하면서 동시에 현재 코드베이스를 보고 싶을 때 잘 맞는다.

실무에서는 전역 설정보다 프로젝트 단위 설정을 더 권장한다. 전역으로 서버를 잔뜩 깔아두면 어느 프로젝트를 열든 도구가 우르르 따라오는데, 그중 절반은 지금 프로젝트와 무관하다. 결국 모델의 선택 비용만 늘어난다. PKM-MCP처럼 해당 저장소의 메모와 강하게 연결된 서버는 프로젝트 범위에 두는 편이 낫다.

Cursor 쪽 운영 원칙은 간단하다. 프로젝트당 서버 수를 최소화하고, 서버 이름은 짧고 분명하게, 읽기와 쓰기는 가능하면 분리한다. 특히 메모 읽기 전용 서버와 메모 수정 서버를 따로 두면 승인 경험이 훨씬 명확해진다. 모델도 "읽기인가, 쓰기인가"를 더 잘 구분한다.

VS Code: 엔터프라이즈 감각이 강한 편

VS Code는 MCP 설정을 mcp.json으로 관리하며, 워크스페이스의 .vscode/mcp.json이나 사용자 프로필 쪽 설정을 사용할 수 있다. 여기서는 루트 키가 mcpServers가 아니라 servers이고, 각 서버에 type을 명시하는 식으로 구조가 잡힌다. 또한 민감한 값은 inputs를 통해 입력받게 할 수 있고, 로컬 stdio 서버는 macOS와 Linux에서 샌드박싱까지 걸 수 있다.³

예를 들어 PKM-MCP를 워크스페이스 기준으로 붙이면 이런 모양이다.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "pkmToken",
      "description": "PKM API Token",
      "password": true
    }
  ],
  "servers": {
    "pkm": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:pkmToken}"
      }
    }
  }
}

이 방식의 장점은 팀원에게 토큰을 JSON 파일에 박아 넣으라고 시키지 않아도 된다는 점이다. 특히 보안 규정이 빡빡한 조직에서는 이 차이가 꽤 크다. 또 stdio 서버를 꼭 써야 한다면 샌드박스 규칙으로 파일 시스템과 네트워크 접근 범위를 제한할 수 있다.³ "도구는 필요하지만 너무 많은 권한은 싫다"는 조직에 꽤 잘 맞는다.

한 가지 더 기억할 점이 있다. VS Code에서 MCP 도구는 보통 Agent 모드에서 가장 자연스럽게 동작한다. Ask 모드에서 왜 안 나오지 하며 한참 헤매기 쉽다. 설정이 틀린 게 아니라 모드가 다른 것뿐인 경우도 많다.

Continue: 설정 자유도가 높다

Continue는 이미 팀 차원에서 커스텀 AI 환경을 굴리고 있는 경우 특히 유용하다. MCP 서버를 .continue/mcpServers/ 아래에 YAML이나 JSON으로 둘 수 있고, stdio, sse, streamable-http를 모두 다룰 수 있다. 다만 Continue에서도 MCP는 Agent 모드에서 사용되는 것이 기본이다.⁴

예를 들어 PKM-MCP를 Continue에 붙이면 다음처럼 쓸 수 있다.

name: PKM MCP
version: 1.0.0
schema: v1
mcpServers:
  - name: PKM Notes
    type: streamable-http
    url: https://mcp.example.com/mcp

Continue의 장점은 구성 방식이 유연하다는 데 있다. Claude Desktop이나 Cursor에서 쓰던 JSON MCP 파일을 그대로 가져와 활용할 수도 있고, 팀이 이미 Hub 설정과 시크릿 관리를 잘 해두었다면 그 위에 얹기도 편하다.⁴ 대신 자유도가 높다는 말은 팀 규칙이 약하면 더 쉽게 혼란스러워진다는 뜻이기도 하다. 파일 위치, 서버 이름, 인증 방식 정도는 팀에서 미리 맞춰두는 편이 좋다.

ChatGPT Apps에서 MCP

ChatGPT 쪽에서 MCP를 바라보는 방식은 개발 도구와 조금 다르다. IDE 안에서는 텍스트 결과만 잘 나와도 충분할 때가 많지만, ChatGPT에서는 사용자가 결과를 보고 만지는 경험까지 기대하는 경우가 많다. OpenAI 문서에 따르면 ChatGPT는 MCP Apps와 같은 iframe-and-bridge 모델을 구현하고 있어서, 한 번 만든 UI를 ChatGPT와 다른 MCP Apps 호스트에서 재사용할 수 있다.⁵

이 말은 굉장히 반갑다. 나중에 PKM-MCP에 노트 카드, 검색 결과 패널, 필터 UI를 붙이면 ChatGPT 같은 호스트에서도 같은 개념으로 보여줄 수 있다는 뜻이기 때문이다. 실제로 MCP Apps 공식 저장소도 Claude, ChatGPT 등 여러 호환 호스트에서 같은 종류의 임베디드 UI를 노릴 수 있다고 설명한다.⁶

다만 여기서 흔히 하는 실수가 하나 있다. UI가 생긴다고 해서 텍스트 응답을 대충 만들어도 된다고 생각하는 것이다. 실제로는 반대다. 좋은 MCP Apps는 항상 두 층으로 설계된다.

첫 번째 층은 텍스트만 받아도 이해되는 응답이다. 예를 들어 PKM-MCP가 검색 결과를 반환한다면, 적어도 제목, 요약, 출처, 작성 시각 정도는 텍스트와 구조화된 데이터로 깔끔하게 제공해야 한다. 그래야 UI가 없는 클라이언트에서도 유용하다.

두 번째 층은 UI가 있을 때 더 편해지는 표현이다. 노트 카드, 태그 필터, 관련 메모 묶음, 하이라이트 이동 같은 기능은 이 층에서 빛난다. 즉, ChatGPT Apps를 염두에 둔 MCP 서버는 "UI가 없어도 쓸 만하고, UI가 있으면 더 즐거운" 구조가 가장 좋다.

정리하면 ChatGPT Apps 시대의 MCP는 단순한 도구 호출보다 한 단계 더 나아간다. 도구, 구조화된 결과, 그리고 임베디드 UI가 한 세트로 묶인다. 그래서 4부로 갈수록 서버 개발이 프런트엔드 감각과 다시 만난다. 메모 검색 서버가 어느 순간 작은 제품이 되는 것이다.

팀 단위 .mcp.json을 Git으로 관리하기

이제 진짜 실무 이야기로 들어가 보자. 혼자 쓸 때는 설정 파일이 조금 지저분해도 버틸 수 있다. 하지만 팀이 되면 바로 무너진다. 누구는 Claude Code를 쓰고, 누구는 Cursor를 쓰고, 누구는 VS Code를 쓰는데, 서버 이름은 다르고 인증 방식은 다르고 경로는 절대 경로로 박혀 있으면 온보딩 첫날부터 분위기가 싸늘해진다.

Claude Code는 프로젝트 스코프 서버를 루트의 .mcp.json에 저장할 수 있고, 환경 변수 확장도 지원한다.² 이 파일은 팀 공유의 중심축으로 쓰기 좋다. 다만 현실적으로 모든 클라이언트가 이 파일 하나만 읽어주지는 않는다. VS Code는 .vscode/mcp.json, Continue는 .continue/mcpServers/*처럼 자기 방식이 있다.³⁴ 그래서 팀 운영에서는 하나의 공용 기준 파일 + 클라이언트별 얇은 어댑터 전략이 가장 덜 아프다.

예를 들어 PKM-MCP 팀 설정의 기준 파일을 이렇게 둘 수 있다.

{
  "mcpServers": {
    "pkm": {
      "command": "uv",
      "args": ["run", "python", "-m", "pkm_mcp"],
      "env": {
        "PKM_ENV": "${PKM_ENV:-local}",
        "PKM_NOTES_DIR": "${PKM_NOTES_DIR:-./notes}"
      }
    }
  }
}

그리고 저장소에는 이런 구조를 권장한다.

repo/
├─ .mcp.json
├─ .vscode/mcp.json
├─ .continue/mcpServers/pkm.yaml
├─ .env.example
└─ docs/mcp.md

여기서 핵심은 파일 개수가 아니라 역할 분리다. .mcp.json은 공용 서버 정의의 기준, .vscode/mcp.json은 VS Code 전용 문법 어댑터, .continue/...는 Continue용 어댑터, .env.example은 필요한 환경 변수 목록, docs/mcp.md는 설치와 검증 절차를 적는 자리다. 이렇게 해두면 새 팀원이 들어와도 "아, 읽을 파일이 여기 있구나"가 된다.

팀 운영 규칙은 다음 여섯 가지면 충분하다.

1. 서버 이름을 클라이언트마다 바꾸지 않는다. Claude Code에서는 pkm, Cursor에서는 personal-knowledge, VS Code에서는 notes-prod처럼 제각각이면 프롬프트와 문서가 다 꼬인다. 이름은 한 번 정하면 통일하자.

2. 비밀값은 Git에 커밋하지 않는다. 토큰, API 키, 사용자별 도메인은 환경 변수나 입력 프롬프트로 받는다. 설정 파일에는 자리만 남긴다.

3. 버전은 가능하면 고정한다. @latest는 편하지만, 어느 날 아침 도구 설명이 바뀌고 입력 스키마가 바뀌는 마술을 보여주기도 한다. 팀 공용 설정은 가능한 한 버전을 핀ning하는 편이 낫다.

4. 읽기와 쓰기 서버를 논리적으로 분리한다. PKM-MCP라면 pkm-read, pkm-write처럼 나누는 방식도 좋다. 승인 UX가 선명해지고 권한 최소화도 쉬워진다.

5. 프로젝트에 필요한 서버만 넣는다. 모든 저장소에 GitHub, Slack, Notion, Figma, Browser, PKM, DB, Deploy를 다 넣는 방식은 멋져 보이지만 실제로는 모델의 집중력을 깎아먹는다.

6. 반드시 스모크 테스트 프롬프트를 문서에 적어 둔다. 예를 들어 "이번 주 메모 3개를 찾아 제목만 보여줘" 같은 검증 프롬프트 한 줄이 있으면, 설정이 살아 있는지 새 팀원도 바로 확인할 수 있다.

여기에 한 가지를 더 보태고 싶다. .mcp.json 변경도 코드처럼 PR로 리뷰하자. 서버 URL이 바뀌거나, 새 쓰기 도구가 추가되거나, 권한 스코프가 넓어지는 변경은 그냥 설정 수정이 아니라 제품 동작의 변경이다. MCP 설정 파일은 이제 단순한 개인 취향 파일이 아니라 팀의 작업 표면을 정의하는 계약서에 가깝다.

PKM-MCP에 바로 적용하는 권장 조합

이 장의 내용을 PKM-MCP에 그대로 적용하면 운영 그림이 꽤 선명해진다.

개인 사용자라면 Claude Desktop에 로컬 stdio PKM-MCP를 붙여서 메모 검색과 주간 요약부터 시작하는 편이 좋다. 복잡한 인증 없이도 "정말 쓸 만한가?"를 빨리 확인할 수 있다.

개발팀이라면 Claude Code나 Cursor에서 프로젝트 단위 설정으로 붙이는 편이 좋다. 코드 작업 중 바로 회의 메모를 찾고, TODO를 노트에 남기고, 이슈를 메모와 연결하는 흐름이 자연스럽다. 이때는 .mcp.json을 저장소에 두고 팀 규칙을 같이 관리하면 된다.

보안과 운영이 중요한 조직이라면 VS Code나 Continue에 원격 HTTP PKM-MCP를 붙이고 OAuth를 쓰는 쪽이 낫다. 사용자별 노트 격리, 시크릿 관리, 감사 로그, 샌드박스 같은 운영 요구사항을 다루기 쉬워진다.³⁴

그리고 메모를 단순 검색 결과가 아니라 작은 제품처럼 보여주고 싶다면, ChatGPT Apps나 MCP Apps 호환 클라이언트까지 시야에 넣어야 한다. 이때부터 PKM-MCP는 "메모를 찾아주는 서버"를 넘어서 "메모를 탐색하고 정리하는 인터페이스"로 진화한다.⁵⁶

마무리

MCP 서버를 만든다는 건 API 하나를 여는 일이 아니다. 사람의 작업 화면 속으로 들어가는 일이다. 그래서 마지막 승부는 서버 코드보다도, 연결 경험과 관리 경험에서 난다.

좋은 클라이언트 활용법은 화려하지 않다. 프로젝트에 맞는 범위로 연결하고, 불필요한 서버를 줄이고, 비밀값을 분리하고, 팀이 읽을 수 있는 설정 파일을 남기는 것이다. 그렇게 해야 PKM-MCP가 "데모에서는 멋진 서버"가 아니라 "매일 켜두는 도구"가 된다.

참고

¹Architecture overview - Model Context Protocol

²Connect Claude Code to tools via MCP - Claude Code Docs

³MCP configuration reference - Visual Studio Code

⁴How to Set Up Model Context Protocol (MCP) in Continue

⁵MCP Apps compatibility in ChatGPT - Apps SDK | OpenAI Developers

⁶ext-apps: Official repo for spec & SDK of MCP Apps protocol