MCP 서버를 "제대로" 설정해 본 적이 있다면 아마 이런 과정을 거쳤을 겁니다.

• MCP JSON을 Claude Code에 붙여 넣기
• 조금 다른 MCP JSON을 Codex에 붙여 넣기
• OpenCode는 또 다른 위치를 쓴다는 걸 발견
• 노트북과 서버에서 다시 반복

동작은 합니다.

하지만 어느 머신에 있느냐에 따라 세션이 다르게 동작하게 되는 원인이기도 합니다.

정말 원하는 건:

• 도구는 한 번만 정의
• 일관되게 사용 가능
• 그러면서도 머신 전용 도구는 머신 전용으로 유지

이 가이드는 그 워크플로에 관한 것입니다.

요약

1. MCP를 무엇에 쓸지 정합니다(브라우저 자동화, GitHub, 문서 검색, 내부 도구).
2. 흔한 실패는 설정 드리프트입니다. 머신/프로바이더마다 MCP JSON이 달라집니다.
3. 더 나은 모델은 "하나의 도구 라이브러리 + 명시적인 적용 범위"입니다.
4. Happier에서는 MCP 서버를 한 번 정의하고, 기존 프로바이더 MCP 설정을 감지하고, 세션에서 실제로 쓰이는 도구 구성을 미리 보고, 다음 범위에 적용할 수 있습니다.
   • 모든 머신
   • 머신 한 대
   • 머신 한 대의 워크스페이스 하나

문제

MCP는 좋은 아이디어지만, 단순한 설정 방식은 깨지기 쉽습니다.

• 여러 설정 파일
• 여러 머신
• 여러 프로바이더

그래서 질문은 "MCP를 실행할 수 있나?"가 아닙니다.

질문은:

믿을 수 있을 만큼 도구 구성을 일관되게 만들 수 있나?

일반적인 방법과 트레이드오프

• JSON을 여기저기 복사/붙여넣기: 머신 하나를 잊기 전까지는 됩니다.
• 프로바이더 하나에만 설정: 이식성이라는 목적 자체를 잃습니다.
• 도구를 프로젝트별로만 유지: 어떤 경우엔 좋지만, GitHub 같은 공통 도구에는 고통스럽습니다.

Happier가 처음이라면

Happier를 처음 본다면: Claude Code, Codex, OpenCode 같은 세션을 여러 머신에서 실행하기 위한 오픈 소스 컴패니언 앱(모바일/웹/데스크톱)입니다.

여기서 관련 있는 부분: MCP 서버를 한곳에서 관리하고 일관되게 적용할 수 있게 해 줍니다.

설정하기:

• 휴대폰에서 Happier 사용하는 방법
• GitHub: https://github.com/happier-dev/happier
• 설치/다운로드: https://github.com/happier-dev/happier#how-it-works
• Discord (커뮤니티 + 지원): https://discord.gg/W6Pb8KuHfg

실제로 쓸 수 있는 워크플로

1) 도구를 JSON 더미가 아니라 라이브러리로 다루기

머신이 둘 이상이 되는 순간 MCP 설정은 인프라가 됩니다.

그러니 라이브러리처럼 다루세요.

• 저장됨
• 검토 가능
• 범위가 정해짐

2) "Configured / Detected / Preview"로 생각하기

Happier에서 MCP 서버는 세 탭으로 정리됩니다.

• Configured: 앱에서 관리하는 서버
• Detected: 프로바이더 네이티브 설정 파일(Claude, Codex, OpenCode)에서 찾은 서버
• Preview: 특정 백엔드 + 머신 + 워크스페이스에서 실제로 쓰이는 도구 구성

Preview가 핵심입니다.

"이 세션은 실제로 무엇을 보게 되나?"에 답해 줍니다.

3) 올바른 범위 적용: 모든 머신 / 머신 한 대 / 워크스페이스 하나

드리프트 대부분은 범위를 명시하지 않아서 생깁니다.

잘 통하는 규칙:

• 원격 HTTP/SSE 서버 → All machines
• npx로 설치한 로컬 stdio 서버 → Machine(한 대)
• 프로젝트 로컬 서버 → Workspace(머신 한 대의 하나)

4) 시크릿을 JSON에 넣지 않기 (토큰 유출 멈추기)

토큰을 MCP JSON에 직접 붙여 넣을 때마다 시크릿이 퍼집니다.

• 셸 기록에 남음
• dotfiles에 남음
• 스크린샷에 찍힘
• 결국 실수로 리포지토리에 들어감

더 나은 방법은:

• 시크릿을 한 번만 저장하는 곳
• 시크릿을 넣지 않고 MCP 설정에서 참조하는 방법
• 그걸 머신 간에 안전하게 재사용하는 방법

Happier는 MCP 서버 헤더/환경 변수 값으로 세 가지 소스를 지원합니다.

• Saved Secrets(권장)
• ${MY_TOKEN} 같은 머신 환경 변수 참조
• 일반 텍스트(정말 민감하지 않은 게 아니면 피하기)

이 "Saved Secrets" 옵션이 여러 머신에서의 MCP를 크게 쉽게 해 줍니다.

시크릿을 한 번 연결하면 MCP 서버 정의는 머신 간에 똑같이 유지할 수 있습니다.

실전 예시: Authorization 헤더를 쓰는 GitHub MCP 서버 (Saved Secret)

흔한 패턴은 다음이 필요한 원격 MCP 서버(HTTP/SSE)입니다.

• Authorization: Bearer <token>

토큰을 JSON에 한 번도 붙여 넣지 않는 처음부터 끝까지의 설정입니다.

1단계: GitHub 토큰 만들기

필요한 최소 범위로 GitHub 토큰을 만듭니다(classic PAT 또는 fine-grained 토큰).

(어떤 범위가 필요한지는 호출할 MCP 도구에 따라 다릅니다. 리포지토리, 이슈, PR 등.)

2단계: 토큰을 Saved Secret으로 저장

Happier에서:

• Settings → Saved Secrets(또는 Settings → Secrets)
• New secret
• 알아볼 수 있는 이름 붙이기, 예: github_pat_work
• 토큰 값 붙여 넣기

이제 값은 설정 파일이 아니라 Happier의 암호화된 설정 저장소에 있습니다.

3단계: Happier에 GitHub MCP 서버 추가

Happier에서:

• Settings → MCP servers → Add server
• Remote HTTP 또는 Remote SSE 선택(서버가 지원하는 것에 따라)
• 이름 붙이기, 예: github

그리고 설정합니다.

• Applies to: 보통 All machines(원격 서버는 이식 가능하므로)

4단계: Saved Secret으로 Authorization 헤더 설정

MCP 서버 설정에서 헤더를 추가합니다.

• 헤더 이름: Authorization
• 헤더 값: Bearer <your-saved-secret>

중요한 건 시크릿을 어떻게 참조하느냐입니다.

• 토큰 값을 붙여 넣지 않기
• 헤더 값 필드에서 Saved Secret(예: github_pat_work)을 선택/참조하기

헤더 편집기에서 값 소스를 고를 수 있습니다.

• Literal(일반 텍스트)
• Saved Secret

Saved Secret을 고르면 Happier는 시크릿 값이 아니라 시크릿에 대한 참조를 저장하고, MCP 서버를 테스트/실행할 때 런타임에 해석합니다.

5단계: Test 후 Preview

• Test로 Happier가 다음을 할 수 있는지 확인:
  • Saved Secret 참조 해석,
  • 서버 연결/시작,
  • 도구 목록 표시.
• Preview(백엔드 + 머신 + 워크스페이스)로 원하는 세션에 GitHub 도구가 실제로 있는지 확인.

Test는 되는데 Preview에서 그 세션의 도구가 0개라면, 거의 항상 범위 불일치입니다(All machines / Machine / Workspace).

(선택) 동작하는 이유 (구현 세부 사항)

환경 변수/헤더 편집기에서 Saved Secret을 고르면, UI는 시크릿 자체가 아니라 작은 타입이 있는 참조(시크릿 ID)를 저장합니다.

그래서 다음이 가능합니다.

• 토큰을 옮기지 않고 같은 MCP 서버 정의를 머신 간에 재사용
• MCP JSON을 건드리지 않고 시크릿 값을 한곳에서 교체

쓰는 데 내부 타입 이름을 알 필요는 없습니다. 하지만 이 모델이 견고한 이유가 이것입니다.

예시: 환경 변수가 필요한 로컬 stdio MCP 서버

stdio 서버(로컬 명령)의 경우 많은 README가 환경 변수를 설정하라고 합니다.

요령은 그걸 "모두가 셸 rc 파일에서 시크릿을 영원히 export"하는 상태로 만들지 않는 것입니다.

더 나은 패턴:

• 값을 Saved Secret으로 한 번 저장
• 그 서버에 필요한 환경 변수 이름에 연결

5) 사용자 지정 MCP 서버 정의 (로컬 stdio)

Happier는 로컬 명령 MCP 서버(stdio)를 지원합니다.

Settings → MCP servers → Add server에서 다음을 할 수 있습니다.

• 명령줄 붙여 넣기(Happier가 명령과 인수로 나눔)
• 범위 선택(로컬 설치는 보통 Machine이 맞음)
• 환경 변수 추가(Saved Secrets 권장)

그런 다음 Test로 시작되고 도구 목록이 나오는지 확인합니다.

6) 사용자 지정 MCP 서버 정의 (원격 HTTP/SSE)

원격 서버의 경우:

• 범위를 All machines로
• 헤더 추가(Saved Secrets 권장)
• 한 번 테스트

7) 중요한 세션을 시작하기 전에 실제 도구 구성 미리 보기

이 가이드에서 습관 하나만 가져간다면 이것으로 하세요.

• Preview로 세션이 실제로 받을 도구 확인

Preview는 다음을 합쳐서 보여 줍니다.

• 기본으로 적용되는, Happier가 관리하는 MCP 서버
• 그 백엔드/맥락에서 감지된 프로바이더 네이티브 MCP 서버
• 사용 가능하지만 현재 적용되지 않은 서버

"이 세션엔 왜 GitHub 도구가 없지?"를 10초 만에 답할 수 있는 질문으로 바꿔 줍니다.

8) 믿기 전에 서버 테스트하기

시간을 아껴 주는 작은 습관:

• MCP 서버 테스트
• 도구 목록이 나오는지 확인

잘못된 명령줄이나 빠진 설치를 일찍 잡아 줍니다.

동작하는 이유 (그리고 깨지는 경우)

이 설정이 동작하는 건 보통 뒤엉키는 세 가지를 분리하기 때문입니다.

1. 정의(MCP 서버가 무엇인지)
2. 범위(어디에 적용할지)
3. 시크릿(어떻게 인증할지)

깨질 때는 보통 다음 중 하나입니다.

• 잘못된 범위(All machines / Machine)
• 로컬 stdio 서버가 해당 머신에 설치되지 않음
• 시크릿을 해석할 수 없음(Saved Secret 미연결, 환경 변수 없음)
• 프로바이더 네이티브 MCP 설정이 기대한 설정을 가림

문제 해결

MCP 서버가 시작되지 않음

• 명령줄 확인
• 선택한 머신에 존재하는지 확인
• npx라면 그 머신에 Node가 설치되어 있고 접근 가능한지 확인

Configured에는 도구가 있는데 세션에는 없음

• 그 백엔드 + 머신 + 워크스페이스의 Preview 확인
• "Applies to" 범위가 이 세션과 맞는지 확인

인증 실패 (401/403)

• 인라인 토큰을 Saved Secrets로 교체
• 헤더/환경 변수가 Saved Secret을 올바르게 참조하는지 확인
• 서버 다시 테스트

관련 가이드

• Claude Code, Codex, OpenCode 세션 여러 개를 병렬로 실행하기 (흐름을 놓치지 않고)