당신의 AI 에이전트는 저장소(repository)의 모든 파일을 읽을 수 있습니다. 에이전트는 당신의 스키마(schema), 라우트 핸들러(route handlers), 그리고 alembic/versions에 남겨둔 미완성 마이그레이션(migration)까지 알고 있습니다. 거의 무엇이든 어떻게 만들지 물어본다면 에이전트는 대답해 줄 것입니다.

하지만 무엇을 만들지 물어본다면, 에이전트는 아는 것이 없습니다.

이러한 비대칭성은 몇 달 동안 저를 괴롭혔습니다. 저는 Claude Code에서 스프린트(sprint)를 계획하곤 했는데, 실제 수요 신호, 즉 사용자들이 무엇을 요구하는지, 얼마나 많은 사람이 원하는지, 그리고 결정적으로 왜 원하는지는 에이전트가 볼 수 없는 브라우저 탭에 놓여 있었습니다. 그래서 저는 매번 Alt-Tab을 눌러 보드를 훑어보고, 머릿속으로 우선순위를 정한 뒤, 다시 돌아와 그 결론을 프롬프트(prompt)로 다시 타이핑해야 했습니다. 매번 말이죠.

저는 피드백 보드 제품을 운영하고 있으므로, 돌이켜보면 해결책은 명확했습니다. MCP를 통해 보드를 노출하는 것이었습니다. 이 포스트는 설계 과정에서 결정적인 차이를 만들어낸 설계 결정들에 관한 것입니다. 왜냐하면 그 결정들 대부분은 시작할 당시에는 명확하지 않았기 때문입니다.

왜 단순한 REST API가 아닌 MCP인가

보드에는 이미 REST API가 있었습니다. 저의 첫 번째 본능은 그것을 문서화하고 사람들에게 스크립트를 작성하라고 말하는 것이었습니다.

하지만 REST API는 당신이 작성하는 프로그램을 위해 만들어졌습니다. MCP는 당신이 대화하는 에이전트(agent)를 위해 만들어졌습니다. 차이점은 전송 방식(transport)이 아니라, 누가 통합(integration) 작업을 수행하느냐에 있습니다.

REST를 사용할 때는 당신이 어떤 엔드포인트(endpoint)를 어떤 순서로 호출할지 결정하고 연결 코드(glue)를 작성해야 합니다. MCP를 사용하면 에이전트가 도구(tools)를 발견하고, 설명을 읽고, 스스로 이를 체이닝(chaining)합니다. "최상위 요청을 찾고, 댓글을 읽고, 사양(spec)을 초안 작성해줘"라는 말은 MCP 권한이 있는 에이전트에게는 단 한 문장이지만, REST API를 사용한다면 오후 내내 걸릴 작업입니다.

이것이 핵심입니다. 만약 당신의 제품에 에이전트가 추론할 수 있는 데이터가 있다면, MCP는 "추가 단계가 붙은 REST"가 아닙니다. 그것은 당신이 직접 구축하는 통합과 스스로 조립되는 통합 사이의 차이입니다.

도구 범위 지정: 5개의 읽기, 2개의 쓰기

이것은 제가 가장 많은 시간을 할애한 결정이었으며, 현재 많은 MCP 서버가 구축되고 있는 방식에 대해 제가 이의를 제기하고 싶은 부분이기도 합니다.

모든 것을 노출하고 싶은 유혹이 생깁니다. 이미 엔드포인트(endpoints)를 가지고 있으니, 이를 MCP 도구(tools)로 일대일 매핑하는 것이 공짜로 표면적(surface area)을 넓히는 것처럼 느껴질 것입니다. 하지만 이를 저항해야 합니다. 당신이 노출하는 모든 도구는 다음과 같은 비용을 발생시킵니다:

• 에이전트가 잘못 선택할 수 있는 선택지가 늘어남
• 에이전트가 유용한 작업을 수행하기 전에 컨텍스트 윈도우(context window)를 더 많이 차지함
• 무언가 잘못되었을 때의 폭발 반경(blast radius)이 커짐

저는 최종적으로 7개의 도구로 결정했습니다.

읽기 (다섯 개):

쓰기 (두 개):

이것이 전부입니다. 결제, 팀 관리, 워크스페이스 관리를 위한 도구는 없습니다. 하나의 토큰은 정확히 하나의 워크스페이스 피드백 데이터에만 접근 권한을 부여하며, 그 외의 것에는 접근할 수 없습니다.

읽기/쓰기의 비대칭성은 의도된 것입니다. 5개의 읽기 도구는 에이전트가 보드를 _이해(understand)_하는 데 필요한 모든 것을 제공합니다. 2개의 쓰기 도구는 에이전트가 _행동(act)_할 수 있게 하며, 두 행동 모두 되돌리는 비용이 저렴합니다. 이 서버를 통해 에이전트가 할 수 있는 일 중 파괴적인 것은 아무것도 없습니다.

update_post_status는 흥미로운 도구인데, 부수 효과(side effect)가 있기 때문입니다. 요청을 '완료' 상태로 옮기면 해당 요청에 투표한 모든 사람에게 이메일이 발송됩니다. 이것은 숨겨진 함정이 아니라 의도된 설계입니다. 하지만 이 기능 때문에 에이전트가 외부로 이메일을 발송하는 트리거를 가질 수 있는지에 대해 깊이 고민하게 만들었습니다. 그럼에도 불구하고 저는 이를 유지했습니다. 왜냐하면 이 루프(loop) 자체가 전체 가치이기 때문입니다. 사용자는 요청이 효과가 있다는 것을 배우게 되고, 그래서 계속 요청하게 되며, 결과적으로 신호(signal)가 개선됩니다. 조심스럽게 행동하겠다고 이 루프를 끊어버린다면 이 통합(integration)은 무의미해졌을 것입니다.

토큰 범위(Token scoping), 그리고 제가 구축하기를 거부한 것들

하나의 토큰, 하나의 워크스페이스, 설정에서 즉시 취소 가능. 스트리밍 가능한 HTTP 상의 베어러 인증(Bearer auth). OAuth 절차는 없습니다.

초기에 여러 제품을 운영하는 사람들을 위해 서버가 "모든 워크스페이스에 걸쳐 모든 것을 읽을 수 있는" 토큰을 지원해야 하는지에 대한 질문을 받았습니다. 제 대답은 '아니오'입니다. 편의성은 확실히 존재하지만, 장애 발생 시의 결과가 매우 치명적입니다. 하나의 보드에 도달하는 토큰 유출은 번거로운 일이지만, 모든 보드에 도달하는 토큰 유출은 사고(incident)입니다. 여러 워크스페이스를 사용하는 사용자는 여러 개의 토큰을 생성합니다. 이는 보안 측면에서 실질적으로 훨씬 더 나은 이야기를 제공하기 위해 UX를 약간 희생하는 선택입니다.

제가 제안하고 싶은 일반적인 원칙은 다음과 같습니다. MCP 토큰이 어디까지 접근할 수 있는지 결정할 때, 그 토큰이 공개된 GitHub 커밋에 포함되어 있다고 상상하십시오. 결국 언젠가는 그렇게 될 것이기 때문입니다. '해피 패스(happy path)'가 아닌, 최악의 상황을 고려하여 설계하십시오.

실제 설정 방법

Claude Code:

claude mcp add --transport http featurewish \
  https://app.featurewish.com/mcp \
  --header "Authorization: Bearer fw_mcp_YOUR_TOKEN"

Cursor, .cursor/mcp.json 파일 내:

{
  "mcpServers": {
    "featurewish": {
...

Claude Desktop 및 Claude.ai는 이를 커스텀 커넥터(custom connector)로 취급합니다. 엔드포인트 URL(endpoint URL)과 베어러 헤더(bearer header)로서의 토큰을 입력하면 됩니다. 클라이언트는 처음 연결할 때 7개의 도구(tools)를 발견합니다.

SDK는 없습니다. 이는 제 구현의 특징이 아니라 일반적으로 MCP의 특징이지만, 명확히 언급할 가치가 있습니다. 왜냐하면 보통 "통합(integration)"이라고 하면 패키지, 설정 파일, 그리고 웹훅 수신기(webhook receiver)를 의미하기 때문입니다.

이것이 실제로 내 워크플로(workflow)를 어떻게 바꾸었는가

솔직한 답변은, 제가 깨닫지 못했던 '비싼 비용이 드는 컨텍스트 스위칭(context switch)'을 없애주었다는 것입니다.

이제 저는 Alt-Tab을 누르는 대신 세션 도중에 다음과 같이 말합니다:

현재 가장 많은 투표를 받은 오픈 요청(open requests) 10개는 무엇인가요?

CSV 내보내기 요청에 달린 댓글을 읽고 사람들이 실제로 필요로 하는 것이 무엇인지 요약해 주세요. 그들이 요청하는 것이 아니라, 그들에게 진짜 필요한 것을 말이죠.

계획된 로드맵 항목 중 투표수가 가장 적은 것은 무엇인가요? 우선순위를 낮춰야 할 항목이 있나요?

한 고객이 SSO를 요청하는 이메일을 보냈습니다. 그 이유와 함께 Features 보드에 기록해 주세요.

방금 다크 모드를 출시했습니다. 해당 요청을 완료(completed)로 표시해 주세요.

세 번째 사례는 예상치 못한 복병(sleeper)이었습니다. 로드맵(Roadmaps)에는 단 세 명의 사람이 요청했을 때 약속했던 항목들이 쌓여가지만, 그 이후로는 다시 검토되지 않는 경우가 많습니다. 요청 시점에 명시된 계획과 현재의 수요를 교차 참조(cross-reference)할 수 있는 에이전트를 갖는 것은, 단순히 보드를 열어보며 막연한 죄책감을 느끼는 것과는 본질적으로 다른 로드맵과의 관계를 형성해 줍니다.

두 번째 사례 또한 피드백과 관련된 특정한 이유 때문에 중요합니다. 실제 요구사항(requirement)이 살아있는 곳은 바로 댓글 스레드(comment thread)이기 때문입니다. 요청 제목은 "CSV 내보내기 추가"일 수 있습니다. 하지만 댓글을 읽어보면 세 명은 예약된 작업이 필요하고, 한 명은 특정 열 순서가 필요하며, 또 다른 한 명은 사실 CSV 내보내기로는 해결할 수 없는 보고(reporting) 문제를 설명하고 있다는 것을 알게 됩니다. 이는 읽어야 할 양이 매우 많습니다. 따라서 에이전트에게 아주 적합한 요약(summarization) 작업입니다.

자신의 제품을 위한 MCP 서버를 구축하고 있다면

다시 하더라도 똑같이 할 네 가지가 있습니다:

1. 필요하다고 생각하는 것보다 더 적은 수의 도구(tools)를 노출하세요. 언제든 추가할 수 있습니다. 모든 도구는 컨텍스트 예산(context budget)을 소모하며 결정 표면(decision surface)을 넓힙니다.
2. 읽기(read)와 쓰기(write)를 명시적으로 분리하고, 가능한 경우 쓰기 작업이 되돌릴 수 있도록(reversible) 만드세요. 어떤 쓰기 작업이 부작용(side effects)을 일으키는지 파악하고 의도적으로 설계하세요.
3. 토큰(tokens)의 범위를 유출(leak)이 발생하더라도 견딜 수 있을 만큼 좁게 설정하세요. 하나의 워크스페이스(workspace)로 제한하고, 취소 가능하며, 관리자 권한(admin surface)은 부여하지 마세요.
4. 당신의 제품을 한 번도 본 적 없는 독자를 위해 도구 설명(tool descriptions)을 작성하세요. 에이전트가 당신의 도메인을 이해하는 유일한 방법은 당신이 그 문자열에 적어 넣은 내용뿐입니다. 이것은 스키마(schema)라는 모자를 쓴 프롬프트 엔지니어링(prompt engineering)이며, 구현(implementation)보다 더 많은 반복(iteration)을 들일 가치가 있습니다.

그리고 다르게 하고 싶은 한 가지가 있습니다. 저는 읽기 도구를 먼저 구축하여 출시한 다음 쓰기 도구를 추가했습니다. 그것은 옳은 선택이었습니다. 만약 처음부터 일곱 개를 모두 설계했다면, 읽기 기능이 활성화된 후 사람들이 실제로 요청하는 내용이 아니라 사용 방식에 대한 추측에 맞춰 쓰기 기능을 과적합(over-fitted)시켰을 것입니다.

저는 인디 SaaS를 위한 피드백 보드인 FeatureWish를 만들고 있습니다. 기능 요청(feature requests), 투표(voting), 로드맵(roadmap), 변경 로그(changelog) 기능을 제공합니다. MCP 서버는 유료 티어에 포함되어 있으며, 보드 자체는 영구적으로 무료입니다. 하지만 위에서 언급한 범위 설정(scoping)에 관한 결정 사항은 모든 MCP 서버에 적용됩니다. 이 내용을 참고하여 여러분만의 서버를 구축해 보세요.

이 기사는 AI의 도움을 받아 작성되었습니다.