Claude, Cursor, ChatGPT를 위한 채용 검색 어시스턴트 MCP 구축기

Four-Leaf는 four-leaf.ai/api/mcp에 Model Context Protocol (MCP) 서버를, github.com/fourleafai/clover-public에 MIT 라이선스의 Skill wrapper를 출시했습니다. 이들은 총 11개의 채용 검색 및 인터뷰 준비 도구를 Claude (Desktop, Code, Cowork), Cursor, ChatGPT Desktop, Perplexity, Cline, Continue, Windsurf, 그리고 OpenAI Codex CLI로 직접 가져옵니다. 해당 서버는 Official MCP Registry, Glama, Smithery, PulseMCP, 그리고 skills.sh에 등록되어 있습니다.

이 포스트는 엔지니어링 기술 문서(engineering write-up)입니다. 왜 아키텍처가 지금과 같은 형태를 갖추게 되었는지, 무엇이 예상보다 어려웠는지, 그리고 OAuth-MCP를 구축하려는 다른 팀이 복제하거나 피해야 할 설계 선택 사항은 무엇인지에 대해 다룹니다.

존재 이유

대부분의 AI 인터뷰 준비 도구들은 자체 앱 안에 갇혀 있습니다. 지원자는 별도의 탭을 열고, 로그인하고, 직무 기술서(job description)를 양식에 붙여넣고 기다려야 합니다. 그들이 이미 대화 중이던 AI 어시스턴트(Claude, Cursor, ChatGPT)는 그 과정의 일부가 아닙니다.

Model Context Protocol (MCP)은 이 문제의 형태를 바꿉니다. 도구들이 어시스턴트 자체에 존재한다면, 지원자는 컨텍스트 스위칭 (context-switch)을 할 필요가 없습니다. 질문을 하면 도구가 실행되고, 대화가 계속 이어집니다. 채용 검색 및 인터뷰 준비 도구가 있어야 할 적절한 위치는 지원자가 이미 머물고 있는 바로 그곳입니다.

이것이 제품의 테제 (product thesis)입니다. 아키텍처는 이 테제를 따릅니다.

파이프라인

11개의 도구 중 9개는 무료, 2개는 유료입니다. 무료 도구들은 MCP가 설치될 가치를 증명하게 만드는 읽기 및 연산 경로 (read and compute path)입니다.

search_jobs는 Greenhouse, Lever, Ashby, Workday로부터 매일 밤 스크래핑된 180,000개 이상의 활성 공고 풀을 탐색합니다. SQL이 실행되기 전에 자연어 파서 (natural-language parser)가 쿼리에서 역할 (role), 레벨 (level), 위치 (location), 고용 형태 (employment type), 그리고 원격 근무 전용 (remote-only) 플래그를 추출합니다.

get_role_intelligence와 list_roles는 24개의 역할(role)에 대한 구조화된 카탈로그를 노출하며, 각 역할은 파이프라인 설명, 채점 루브릭 (scoring rubric), 그리고 이력서 가이드를 포함합니다.

get_interview_questions는 엄선된 질문 은행에서 질문을 가져옵니다. generate_practice_questions는 팁과 핵심 사항을 포함한 역할 조정 프롬프트 (role-calibrated prompts)를 사용하여 Claude Haiku를 통해 필요할 때마다 새로운 질문을 생성합니다.

match_score는 이력서와 직무 기술서 (job description)를 대상으로 실제 채점 알고리즘을 실행하여, 0-100 사이의 적합도 점수와 함께 기술, 경력, 역할 정렬 (role-alignment)에 대한 세부 분석 내용을 반환합니다. 이 알고리즘은 불렛 포인트 형태의 경력 사항에 나타나지 않는 단순 기술 목록 언급에 감점을 부여하는데, 이는 올바른 동작입니다.

explain_interview_format은 역할 지능 (role intelligence)에 지원자의 지정된 연차 (seniority) 및 선택 사항인 기업 정보를 결합하여 근거 있는 인터뷰 가이드를 합성합니다.

comp_coach와 comp_benchmarks는 보상 (comp) 기둥 역할을 합니다. 두 기능 모두 아래에서 자세히 설명합니다. 두 가지 유료 도구인 start_voice_mock_interview와 tailor_resume는 지원자의 컨텍스트가 이미 사전 채워진 상태로 four-leaf.ai 앱의 해당 페이지를 여는 딥링크 (deep-links)를 반환합니다.

이 체인(chain)이 바로 해자 (moat)입니다. 일자리를 찾고, 인터뷰를 파악하고, 연습하고, 이력서를 맞춤화하고, 모의 면접을 진행하고, 오퍼 (offer)를 해석합니다. 전용 인프라 없이는 어떤 범용 AI도 이를 엔드 투 엔드 (end-to-end)로 수행할 수 없습니다.

OAuth 2.1 + PKCE + Dynamic Client Registration

API 키 복사-붙여넣기는 표준적인 MCP 인증 패턴입니다. 사용자가 대시보드에서 키를 생성하고, 이를 MCP 클라이언트 설정에 붙여넣은 뒤, 실수로 커밋하지 않기를 기도하는 방식입니다. Four-Leaf가 서비스하는 지원자 대상은 그런 대상이 아닙니다.

대신 MCP 서버는 PKCE 및 동적 클라이언트 등록 (Dynamic Client Registration)을 포함한 OAuth 2.1을 사용합니다. 흐름은 다음과 같습니다:

사용자가 MCP를 설치합니다. 사용자의 AI 클라이언트가 브라우저를 열어 four-leaf.ai/api/mcp/.well-known/oauth-authorization-server로 접속합니다.
클라이언트가 DCR (Dynamic Client Registration)을 통해 스스로를 등록합니다. 사전 등록도, 앱 스토어도, 대기 명단도 필요 없습니다. MCP를 인식할 수 있는 클라이언트라면 무엇이든 연결할 수 있습니다.
사용자는 기존의 Four-Leaf 계정으로 인증합니다. PKCE (Proof Key for Code Exchange)가 권한 부여 코드 교환 (Authorization Code Exchange) 과정을 보호합니다.
MCP 클라이언트는 베어러 토큰 (Bearer Token)을 저장합니다. 향후 유료 상태 여부에 대한 신뢰할 수 있는 정보원 (Source of Truth)은 Four-Leaf 계정이 됩니다.

이를 통해 얻는 이점은 소비자용 제품(구독 등급, 음성 모의 면접 이력, 저장된 이력서)을 구동하는 것과 동일한 계정이 MCP 도구가 실행될 때 인증된다는 점입니다. 이중 결제나 두 번의 로그인이 필요 없습니다.

대가는 구현 비용입니다. PKCE 및 DCR을 포함한 OAuth 2.1은 정적인 API 키 확인 방식보다 더 많은 코드를 필요로 합니다. 표준 서버 측 OAuth 라이브러리들이 DCR 엔드포인트를 항상 올바르게 처리하는 것도 아닙니다. .well-known 디스커버리 엔드포인트 (Discovery Endpoint)는 정확한 형식으로 구성되어야 합니다.

보상 벤치마크를 위한 서버 측 웹 검색

가장 구현하기 어려웠던 도구는 comp_benchmarks였습니다. 요구 사항은 간단해 보입니다. 사용자가 "오스틴의 시니어 백엔드 엔지니어에게 적절한 급여는 얼마인가요?"라고 물으면, 도구가 인용된 급여 범위를 반환하는 것입니다.

첫 번째 구현에서는 클라이언트 측 웹 검색을 시도했습니다. MCP 도구가 AI 클라이언트에게 levels.fyi, Glassdoor, Payscale를 사용하여 자체적으로 웹 검색을 수행하라는 지침을 응답으로 보내는 방식이었습니다. 이는 두 가지 측면에서 실패했습니다.

첫째, MCP 클라이언트들은 웹 검색을 일관성 없게 사용합니다. 웹 검색 기능이 활성화된 Claude Code의 경우, 어떤 때는 검색을 수행하지만 어떤 때는 대신 명확한 질문을 던지기도 했습니다. 세션은 다르지만 프롬프트는 동일한 상황이었습니다.

둘째, 웹 검색 기능이 없는 MCP 클라이언트는 아무것도 할 수 없었습니다. MCP 도구가 클라이언트에게 없는 기능을 위임하는 것은 결국 대화가 막히는 결과(Dead-end conversations)만을 초래합니다.

해결책은 서버 측(server-side)에 있었습니다. 새로운 comp_benchmarks 도구는 Anthropic의 web_search_20250305 도구를 Sonnet 호출에 결합하여, 서버가 Four-Leaf의 API 키로 검색을 수행하도록 합니다. 그 후 인용된 급여 범위(salary bands), 명시된 출처(levels.fyi, Glassdoor, Payscale), 그리고 각 주장별 신뢰도 등급(confidence rating)이 포함된 구조화된 응답(structured response)을 반환합니다.

그에 따른 트레이드오프(trade-off)는 호출당 실제 비용이 발생한다는 점입니다. 웹 검색은 쿼리당 비용이 청구되고, Sonnet 래퍼(wrapper)는 Haiku보다 비용이 더 많이 들며, 일반적인 호출은 30~~60초 동안 3~~5개의 검색을 실행합니다. 사용자당 하루 20회 호출 제한을 두어 비용을 제한했으며, 이는 한두 개의 경쟁 제안(competing offers)을 검토하는 후보자에게는 충분한 양입니다.

이 아키텍처적 교훈은 일반화될 수 있습니다. MCP 도구가 클라이언트가 가졌을 수도 있고 가지지 않았을 수도 있는 기능이 필요할 때, 신뢰할 수 있는 경로는 이를 서버 측에서 제공하는 것입니다. 클라이언트가 무엇을 설치하기로 결정했는지에 따라 정확성(correctness)을 외주 주지 마세요.

60초 클라이언트 타임아웃 (client timeout)

일부 MCP 도구는 특히 조용하게 실패합니다. 서버 측 테스트 리그(test rig)에서는 도구를 실행하고 응답이 돌아오며 모든 것이 정상적으로 보입니다. 하지만 도구를 배포하면 실제 모든 사용자에게서 실패가 발생합니다.

원인은 대부분의 MCP 클라이언트에서 약 60초로 설정되어 있는 클라이언트의 도구 호출 타임아웃(tool-call timeout)입니다. 이는 서버의 함수 타임아웃(function timeout)과는 다릅니다 (Vercel은 최대 300초를 허용하며, Four-Leaf의 MCP 경로는 120초로 설정되어 있습니다). 서버가 응답을 포기하기 훨씬 전에 클라이언트가 도구 사용을 포기해 버리는 것입니다.

comp_coach 도구가 이 문제에 직면했습니다. 이 도구는 전체 협상 분석을 수행합니다. 제안(offer)이 입력되면 총 보상(total compensation) 계산, 시장 비교, 구성 요소별 분석, 레드 플래그(red flags), 그리고 구체적인 대화 포인트가 포함된 카운터 전략(counter strategy)이 담긴 구조화된 메모가 출력됩니다. 기존 구현은 8192 max_tokens에서 Sonnet을 사용했습니다. 생성에는 약 103초가 소요되었으며, API에 직접 테스트했을 때는 매번 깔끔한 응답을 생성했습니다.

하지만 Claude Code에서는 동일한 호출이 매번 실패했습니다. MCP 클라이언트가 60초에서 타임아웃이 발생하여 도구를 사용할 수 없다고 보고했기 때문입니다.

해결 방법은 세 가지 부분이었습니다. Sonnet에서 Haiku로 전환하여 동일한 구조를 몇 배 더 빠르게 생성하도록 했습니다. 논의 사항(talking points), 위험 신호(red flags), 산문 길이(prose length)에 대한 명시적인 제한을 두어 프롬프트(prompt)를 더 정교하게 다듬었습니다. 그리고 제어되지 않는 생성(runaway generation)을 방지하기 위한 강력한 보호책으로 max_tokens를 8192에서 4096으로 줄였습니다.

새로운 도구는 모든 정보가 포함된 오퍼(기본급, 지분, 사이닝 보너스, 경쟁사 오퍼, 우선순위, 제약 조건)를 처리하는 데 약 38초가 소요됩니다. 이는 클라이언트 타임아웃(client timeout) 기준에서 네트워크 지터(network jitter) 및 속도 제한(rate-limit) 재시도를 위한 약 22초의 여유 시간을 남겨둡니다.

교훈: 서버 측 스모크 테스트(smoke tests)만 수행하지 말고, 매번 실제 MCP 클라이언트를 통해 엔드 투 엔드(end-to-end)로 검증하십시오. 60초라는 클라이언트 예산이 실제 제약 사항입니다.

대용량 텍스트 전달을 위한 일회용 저장소 (Single-use stash)

four-leaf.ai 앱으로의 딥링크(deep-links)를 반환하는 MCP 도구들은 경계를 넘어 컨텍스트(context)를 전달해야 합니다. 후보자가 Claude에 직무 기술서(JD)를 붙여넣으면, tailor_resume 도구가 URL을 생성하고 사용자가 이를 클릭합니다. 이때 랜딩 페이지는 JD를 다시 요구하는 대신, 동일한 JD로 양식을 미리 채워주어야 합니다.

URL 쿼리 파라미터(query parameters)가 가장 명확한 메커니즘입니다. 가벼운 컨텍스트(역할, 레벨, 인터뷰 유형)는 문제없이 URL에 담길 수 있습니다. 하지만 무거운 텍스트는 문제가 됩니다. 대부분의 브라우저는 약 2,000자까지의 URL을 허용하지만, 실제 직무 기술서와 실제 이력서를 합치면 통상적으로 만 자에서 이만 자에 달합니다. 이를 쿼리 문자열(query string)에 밀어 넣는 것은 이메일 클라이언트, 소셜 링크 미리보기, 분석 파이프라인(analytics pipelines) 전반에서 신뢰하기 어렵습니다.

해결책은 서버 측 저장소(server-side stash)를 사용하는 것입니다. 다음과 같은 제약 조건을 가진 새로운 Postgres 테이블 mcp_handoff_stashes를 생성했습니다:

auth.uid() = user_id를 보장하는 행 수준 보안(row-level security)이 적용된 user_id 외래 키(foreign key)
삽입 시에는 null이며 첫 읽기 시 타임스탬프가 찍히는 consumed_at 타임스탬프
오래된 데이터(stale data)를 방지하기 위한 15분 유효 기간인 expires_at TTL
실제 페이로드(payload)를 담기 위한 context JSONB 컬럼

MCP 도구가 랜딩 페이지(landing page)로 방대한 텍스트를 전달해야 할 때, 도구는 행(row)을 삽입하고 반환된 UUID를 가져와 딥링크(deep-link) URL 끝에 ?stash=<id>를 추가합니다. 랜딩 페이지는 RLS(Row Level Security) 하에서 ID를 통해 해당 행을 소비(consume)하고, 이를 소비된 것으로 표시한 뒤 양식을 미리 채웁니다(pre-fill). 일회성 소비와 짧은 TTL(Time To Live)의 조합 덕분에, 첫 소비 후 브라우저를 새로고침하더라도 원래의 MCP 컨텍스트(context)가 다시 적용되는 대신 사용자의 수정 사항이 그대로 유지됩니다.

이 과정을 안전하게 만드는 것은 RLS 정책입니다. MCP 도구는 관리자 클라이언트(admin client, bearer-token 인증)로 실행되어 삽입(insert) 시 RLS를 우회합니다. 반면 랜딩 페이지는 사용자의 세션 클라이언트(user's session client)로 실행되며 정책의 제한을 받습니다. 설령 stash UUID가 유출되더라도, 다른 사용자가 타인의 컨텍스트를 읽을 수는 없습니다.

전체 과정은 약 40줄의 SQL과 두 개의 TypeScript 헬퍼(helper)로 이루어져 있습니다. 돌이켜보면 매우 당연하게 느껴지는 패턴입니다.

오픈 소스 Skill 래퍼 (wrapper)

MCP 서버는 호스팅되어 있습니다. 이를 감싸는 Skill은 오픈 소스입니다.

four-leaf-coach는 Claude Code, Cursor, OpenAI Codex CLI, 그리고 GitHub Copilot에 단 한 번의 npx 명령어로 설치할 수 있는 Claude 호환 Skill입니다:

npx four-leaf-coach add

CLI는 현재 사용 중인 도구를 감지하거나(또는 --tool 플래그를 허용함), 적절한 번들(bundle)을 올바른 위치에 복사하고, 실시간 데이터를 위한 MCP 설치 명령어를 출력합니다. 번들 구조는 도구마다 다릅니다. Claude Code와 Cursor는 참조(references) 디렉토리를 읽습니다. Codex는 AGENTS.md와 참조 트리(references tree)를 읽습니다. Copilot은 단일화된(flattened) 하나의 지침(instructions) 파일을 읽습니다. 빌드 스크립트는 단일 소스로부터 타겟별로 하나의 번들을 생성합니다.

Skill 자체는 라우팅(routing) 및 코칭(coaching) 레이어입니다. 7가지 워크플로우(kickoff, 채용 공고 찾기, 역할 준비, 연습, 직무 기술서(JD) 분석, 협상, 인터뷰 전략) 각각에는 워크플로우가 실행되는 시점, 어떤 MCP 도구를 먼저 호출할지, 그리고 응답에 따라 어떻게 코칭할지를 설명하는 참조 파일이 있습니다. MCP는 구조화된 JSON을 반환하며, Skill은 이를 대화로 변환합니다.

라이선스는 MIT입니다. 코드는 github.com/fourleafai/clover-public에서 확인할 수 있습니다. 새로운 도구 지원, 새로운 워크플로우, 또는 음성 기능 개선을 위한 Pull Request(PR)를 환영합니다.

설치 (Install)

MCP 서버:

claude mcp add --transport http four-leaf https://four-leaf.ai/api/mcp

Skill, 두 가지 경로가 있습니다. 전용 CLI를 통한 도구별 번들:

npx four-leaf-coach add

또는 범용 Skill 인식 설치 프로그램 (Claude Code, Cursor, Codex, Cline, Amp, OpenCode, Zed, Gemini CLI 및 기타 다수):

npx skills add fourleafai/clover-public

읽기 전용 도구(read tools)는 무료 Four-Leaf 계정으로 사용 가능합니다. 일일 제한이 있는 연산 도구(이력서 점수 산정, 연습 문제 생성, 비교 분석, 비교 벤치마크)는 넉넉한 한도 내에서 무료로 제공됩니다. 두 가지 유료 서비스(루브릭 점수가 포함된 피드백이 제공되는 음성 모의 면접, 그리고 전체 AI 이력서 맞춤화)는 3일 무료 체험을 포함하여 활성화된 모든 Four-Leaf 유료 플랜을 통해 이용할 수 있습니다.

각 도구별 샘플 프롬프트를 포함한 전체 기능 범위는 four-leaf.ai/oss에서 확인할 수 있습니다.