내 코드와 연결하기 (MCP)

왜 코드를 연결하나요

Specnote는 코드를 연결하지 않아도 바로 쓸 수 있어요. 사이트 주소만 알려 주면 AI가 화면을 사람처럼 눌러 보며 시나리오를 만들고 검증합니다. 그러니 처음에는 연결 없이 가볍게 시작하셔도 됩니다.

그래도 코드를 연결하면 세 가지가 눈에 띄게 강해져요.

• 자동 추출이 정확해집니다. AI가 화면 겉모습만 보는 게 아니라 실제 만든 코드 구조를 참고하기 때문에, 시나리오와 단계를 더 빈틈없이 정리합니다. (여기서 단계는 "이메일 입력 → 비밀번호 입력 → 가입 버튼 클릭"처럼 시나리오를 잘게 나눈 동작 하나하나예요.)
• 영향 분석이 가능해집니다. 기능 하나를 바꿨을 때 어떤 시나리오의 어떤 단계가 영향을 받는지 짚어 줍니다. "이번 변경으로 무엇이 깨질 수 있는지"를 미리 가늠할 수 있어요.
• 재검증이 똑똑해집니다. 코드가 바뀐 부분만 골라 다시 확인하므로, 매번 처음부터 전부 검증하지 않아도 됩니다.

연결은 Claude Code·Cursor 같은 AI 코딩 도구와 Specnote를 잇는 방식이에요. 이때 쓰는 다리가 MCP(Model Context Protocol)인데, AI 도구가 외부 서비스와 안전하게 대화하도록 약속된 표준 통로라고 보시면 됩니다.

먼저 드리는 보안 약속

코드를 연결한다고 하면 가장 먼저 떠오르는 걱정이 "내 비밀번호나 결제 키까지 넘어가는 거 아냐?"일 거예요. 그래서 약속부터 분명히 말씀드릴게요.

운영 비밀은 내 PC에서 먼저 가린 뒤에 보내고, 서버에 그대로 저장하지 않습니다.

사용자 PC 안에서 먼저 비밀을 가린 다음, 가려진 코드만 서버로 보냅니다. 서버는 안전망으로 한 번 더 검사해서 빠진 비밀까지 잡아냅니다.

여기서 운영 비밀이란 실제 서비스를 돌리는 데 쓰는 진짜 열쇠예요. 운영 데이터베이스 비밀번호, 결제 키, 외부 서비스 접근 키 같은 것들이죠. 다만 비밀을 가리는 일은 정해진 패턴을 찾아 바꾸는 방식이라 100%를 장담하긴 어려워요. 그러니 운영 비밀은 코드에 직접 적어 두지 않는 것이 가장 안전합니다. 혹시 남아 있더라도 내 PC와 서버 양쪽에서 한 번씩 더 걸러내도록 설계해 두었어요.

받는 것 · 받지 않는 것

연결했을 때 무엇이 오가는지 한눈에 정리하면 이래요.

받는 것	받지 않는 것
화면 코드 (프론트엔드 — 사용자가 보는 부분)	.env · *.key · *.pem 같은 비밀 파일
서버 코드 (Backend API — 화면 뒤에서 도는 부분)	AWS · OpenAI · Google 같은 외부 서비스 키
코드 구조 분석 결과 (어떤 화면이 어떤 기능과 이어지는지)	결제 키 · 데이터베이스 비밀번호 · 운영 환경변수

받는 것은 "이 앱이 어떻게 생겼고 어떻게 움직이는지"를 이해하는 데 필요한 코드와 구조뿐이에요. 비밀번호나 키 같은 값은 받지 않습니다.

비밀을 지키는 3겹 안전망

비밀이 새지 않도록 세 겹으로 막아요. 한 겹이 놓치더라도 다음 겹이 잡습니다.

1. 1겹 — 내 PC에서 비밀 파일 자체를 제외합니다. .env·*.key·*.pem 같은 비밀 파일과 .gitignore에 적힌 파일은 처음부터 읽지 않아요. 파일이 아예 후보에서 빠지는 단계예요.
2. 2겹 — 내 PC에서 코드 본문 속 비밀을 가립니다. 코드 안에 실수로 적어 둔 키가 있어도, 14가지 비밀 패턴(외부 서비스 키·결제 키·데이터베이스 접속 정보·인증 토큰 등)을 찾아 가림 표시로 바꾼 뒤에야 전송합니다.
3. 3겹 — 서버에서 한 번 더 검사합니다. 혹시 내 PC에서 놓친 비밀이 있는지 서버가 안전망으로 다시 훑어 추가로 가립니다. 무언가 추가로 잡히면 "이만큼 더 가렸어요"라고 알려 드려요.

핵심은 가리는 일이 모두 내 PC 안에서 먼저 끝난다는 점이에요. 서버는 이미 가려진 코드를 받고, 마지막으로 한 번 더 확인하는 역할만 합니다.

연결하기 — 토큰 또는 브라우저 인증

연결 방식은 두 가지예요. 둘 중 편한 쪽을 고르시면 됩니다.

방법 A — 브라우저 인증 (권장). Claude Code 같은 AI 도구에서 한 번만 "허용"을 누르면 끝나요. 토큰을 직접 복사하거나 다룰 필요가 없습니다. 한 번 허용해 두면 30일 동안 자동으로 회전(주기적으로 안전하게 갱신)되어, 그동안 다시 인증하지 않아도 돼요. 토큰을 신경 쓰고 싶지 않은 분께 가장 편한 방식이라 권장합니다.

방법 B — 자동 동기화 토큰. 마이페이지에서 토큰을 발급받아 쓰는 방식이에요. 이 토큰은 spnt_로 시작하고, 따로 만료되지 않습니다 — 마이페이지에서 직접 폐기하기 전까지 계속 쓸 수 있어요. 토큰에는 프로젝트 읽기·추가와 테스트 실행 권한이 함께 담깁니다. CI 같은 자동 환경에서 쓰기 좋아요. 다만 이 토큰은 비밀번호처럼 다뤄 주세요 — 깃(git)에 올리거나 남에게 공유하지 말고, 새어 나간 것 같으면 마이페이지에서 즉시 폐기하세요.

토큰을 발급받았다면, specnote-sync라는 도구로 한 줄이면 코드를 보낼 수 있어요. 따로 무언가를 설치할 필요 없이(Node 18 이상이면 됩니다) 아래 한 줄을 터미널에 입력하면 됩니다.

npx @specnote/sync sync-all --base-url https://specnote.io --spec-id <프로젝트 ID> --pat <토큰>

연결한 뒤 AI 코딩 도구 안에서 쓸 수 있는 주요 기능은 이래요.

기능	하는 일
코드 보내기 (specnote_sync_code)	가린 코드를 통째로 보냅니다
API 목록 보내기 (specnote_sync_api)	서버 기능 목록을 보냅니다
변경 영향 분석 (specnote_analyze_change)	바뀐 부분이 어떤 시나리오에 영향을 주는지 알려줍니다
AI 자동 추출 (specnote_run_ai_agent_extraction)	AI가 앱을 탐색해 시나리오 후보를 찾아냅니다
수정 리포트 받기 (specnote_get_failure_report)	검증이 실패했을 때 어디서 왜 멈췄는지 정리해 줍니다
시나리오 조회 (list_scenarios)	만든 시나리오와 검증 결과를 불러봅니다
테스트 계정·환경 설정 (specnote_upsert_test_account, specnote_upsert_test_environment)	검증에 쓸 테스트 계정과 환경 정보를 등록합니다

코드 동기화는 한 방향이에요. 내 PC에서 Specnote로 코드를 보내기만 합니다. Specnote가 내 코드를 거꾸로 바꾸는 일은 없어요. 그래서 안심하고 연결하셔도 됩니다.

첫 동기화는 100개 파일 기준 3060초 정도 걸려요. 그 다음부터는 바뀐 부분만 보내므로 보통 510초면 끝납니다.

테스트 전용 시크릿

검증을 하려면 로그인이 필요한 경우가 많아요. 이때 운영 비밀번호를 넣을 필요는 전혀 없습니다. 대신 테스트 전용 시크릿만 따로 등록하시면 돼요. 테스트용 계정이나 샌드박스(연습용 가짜 결제 환경) 키처럼, 새어 나가도 실제 손해가 없는 값들이죠.

등록한 값은 즉시 암호화되어 보관됩니다(KMS라는 전용 보관 장치를 씁니다). 본인만 열어 볼 수 있고, 화면에서 "값 보기"를 눌러도 5초만 보인 뒤 다시 가려져요. 운영 비밀과는 완전히 분리되어 있으니, 테스트에 필요한 최소한의 값만 안심하고 넣으시면 됩니다.

자주 막히는 곳

• 연결이 안 돼요. 브라우저 인증이라면 AI 도구에서 다시 한 번 "허용"을 눌러 인증을 새로 해 주세요. 토큰 방식이라면 마이페이지에서 토큰이 폐기되지 않았는지 확인하고, 필요하면 새로 발급받으세요.
• 동기화가 너무 느려요. 첫 동기화는 원래 3060초가 걸립니다. 그 뒤에도 계속 느리다면, 보내는 파일이 많지는 않은지 살펴보세요. 보통 두 번째부터는 바뀐 부분만 보내 510초면 끝나요.

더 궁금한 점은 자주 묻는 질문에서 확인하시거나, support@specnote.io로 보내 주세요.