MCP 서버
Claude Code, Cursor 등 AI 코딩 도구에서 QA Note 이슈를 OAuth 한 번으로 연결하고 조회·수정하세요
목차
- MCP란?
- 한 번에 설치
- 인증 방식 한눈에 보기
- 방법 A. Remote HTTP + OAuth 원클릭 (권장)
- Claude Code
- Cursor
- Codex (OpenAI)
- OAuth 플로우 상세
- 방법 B. 로컬 바이너리 (stdio · npx)
- Claude Code
- Cursor / Codex
- 인증 플로우
- 방법 C. API Key (CI · 헤드리스 · 대체 경로)
- Remote HTTP에 API Key 부착
- stdio 바이너리에 API Key 부착
- 환경변수 (stdio 바이너리용)
- 사용 가능한 도구
- 조회 도구
- 쓰기 도구
- 추천 워크플로우
- 동작 확인
- 트러블슈팅
- OAuth 브라우저 창이 뜨지 않음 (Remote HTTP)
- "Unauthorized" 에러
- MCP 서버가 연결되지 않음 (stdio 바이너리)
- 토큰/세션 초기화
- SSH · Docker 등 브라우저 불가 환경
MCP란?
MCP(Model Context Protocol)는 AI 코딩 도구가 외부 데이터에 접근할 수 있게 해주는 표준 프로토콜입니다. QA Note MCP 서버를 연결하면 Claude Code, Cursor, Codex 등에서 이슈 데이터를 직접 조회하고, 상태를 변경하고, 코멘트를 남길 수 있습니다.
QA Note가 수집하는 풍부한 기술 메타데이터(콘솔 로그, 네트워크 요청, JS 에러, 성능 메트릭, React 컴포넌트 트리, 유저 액션, 엘리먼트 스타일, DOM 스냅샷 등)를 AI에 구조화해서 전달하므로, 이슈 컨텍스트 기반 디버깅이 가능해집니다.
한 번에 설치
사용 중인 MCP 클라이언트를 고르면 복사 또는 설치 링크가 바로 실행됩니다. 처음 연결 시 브라우저 OAuth 동의창이 한 번 열립니다.
사용 중인 MCP 클라이언트 하나만 고르세요
아래 카드에서 복사 또는 설치 액션 한 번이면 QA Note MCP 가 붙습니다. 처음 연결 시 브라우저 OAuth 동의창이 한 번 열립니다.
Codex
CLI/IDE 공용 config.toml 등록 · OAuth 로그인
터미널에서 실행하면 서버 등록 후 OAuth 로그인 브라우저가 열립니다. IDE 확장도 같은 설정을 사용합니다.
공식 설치 가이드Claude Desktop
mcpServers 설정 JSON 복사
설정 파일 위치: macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json
공식 설치 가이드Cursor
Deep link 한 번 클릭으로 Cursor 에 등록
Cursor 미설치 환경이면 "설정 JSON 복사" 로 ~/.cursor/mcp.json 에 직접 붙여넣으세요.
공식 설치 가이드Windsurf
mcpServers 설정 JSON 복사 (serverUrl 키)
Windsurf → Cascade → MCP Servers → Add Server 에 붙여넣으세요.
공식 설치 가이드ChatGPT
Developer Mode connector URL 복사
ChatGPT → Settings → Connectors → Developer Mode 활성화 → Add MCP server 에 붙여넣으세요.
공식 설치 가이드인증 방식 한눈에 보기
| 방식 | 언제 쓰나 | 키 발급 | 추천도 |
|---|---|---|---|
| Remote HTTP + OAuth | 평소 데스크톱 환경 (Claude Code, Cursor, Codex 등) | 필요 없음 (브라우저 동의 한 번) | ★★★ 기본값 |
| stdio 로컬 바이너리 | 조직 프록시로 HTTP MCP가 막힌 경우 · 오프라인 캐시가 필요한 경우 | 필요 없음 (동일한 OAuth) | ★★ |
| API Key | CI/CD · 헤드리스 서버 · OAuth 미지원 클라이언트 | 대시보드에서 qn_... 수동 발급 | ★ (대체 경로) |
기본은 OAuth 원클릭입니다. Authorization 헤더를 손으로 붙일 필요가 없습니다. Claude Code는 표준 MCP 디스커버리(
/.well-known/oauth-protected-resource)를 통해 QA Note 인증 서버를 자동 발견하고, Dynamic Client Registration(RFC 7591) → Authorization Code + PKCE S256 → Access/Refresh Token 교환을 수행합니다.
방법 A. Remote HTTP + OAuth 원클릭 (권장)
QA Note가 호스팅하는 HTTP MCP 엔드포인트(https://qanote.app/api/mcp)에 바로 연결합니다. 별도 바이너리 설치도, API Key 복사 붙여넣기도 없습니다.
Claude Code
터미널에 한 줄:
claude mcp add --transport http qanote https://qanote.app/api/mcp
등록 직후 Claude Code에서 /mcp 를 실행하면 브라우저가 자동으로 열리고, QA Note 로그인 · 동의(consent) 화면 한 번으로 인증이 끝납니다. 발급된 access/refresh token은 Claude Code 쪽에 안전하게 저장되며, 이후부터는 투명하게 갱신됩니다.
Cursor
~/.cursor/mcp.json 에 추가:
{
"mcpServers": {
"qanote": {
"url": "https://qanote.app/api/mcp"
}
}
}
headers 를 쓰지 않습니다. 처음 도구 호출 시 Cursor가 브라우저 OAuth 창을 띄워 줍니다.
Codex (OpenAI)
Codex CLI 설정 파일의 mcpServers 에 동일하게 추가:
{
"mcpServers": {
"qanote": {
"url": "https://qanote.app/api/mcp"
}
}
}
OAuth 플로우 상세
- 클라이언트가
https://qanote.app/api/mcp호출 →401 Unauthorized+WWW-Authenticate: Bearer resource_metadata=...응답 - 클라이언트가
/.well-known/oauth-protected-resource(RFC 9728) →/.well-known/oauth-authorization-server(RFC 8414) 를 차례로 읽어 인증 서버 메타데이터 획득 - Dynamic Client Registration (RFC 7591) 로
client_id자동 발급 (사용자 조치 불필요) - Authorization Code + PKCE S256 플로우로 브라우저에서 로그인 + MCP 접근 동의
/api/oauth/token에서 access token (mcp·offline_access스코프,aud=https://qanote.app/api/mcp바인딩 — RFC 8707) + refresh token 교환- 이후 요청에서 refresh token rotation 으로 세션이 조용히 갱신됨
이슈 상세 페이지의 "MCP 프롬프트" 버튼으로 복사한 프롬프트에는 이슈 permalink가 포함되어, LLM이 resolve_by_url 도구 하나로 전체 컨텍스트를 당겨옵니다.
방법 B. 로컬 바이너리 (stdio · npx)
조직 네트워크에서 HTTP MCP가 막혀 있거나, 오프라인/SSH 환경에서도 자격증명을 로컬 캐시해 쓰고 싶을 때 사용합니다. 인증 자체는 동일한 OAuth 브라우저 로그인입니다.
Claude Code
claude mcp add qanote -- npx -y @qanote/mcp-server
Cursor / Codex
{
"mcpServers": {
"qanote": {
"command": "npx",
"args": ["-y", "@qanote/mcp-server"]
}
}
}
인증 플로우
- MCP 서버 최초 실행 시 저장된 크레덴셜이 없으면 브라우저가 자동으로 열립니다
- QA Note 계정으로 로그인 (이미 로그인되어 있으면 동의만 진행)
- 발급된 토큰이
~/.qanote/credentials.json에chmod 600으로 저장됩니다 (기본 30일 유효) - 이후 실행부터는 저장된 토큰을 자동 재사용하고, 만료 시 다시 브라우저가 열립니다
자격증명을 초기화하려면:
rm ~/.qanote/credentials.json
방법 C. API Key (CI · 헤드리스 · 대체 경로)
브라우저를 띄울 수 없는 환경(CI/CD, 컨테이너, 원격 서버)이나 OAuth 를 지원하지 않는 MCP 클라이언트에서만 사용하세요.
- QA Note 대시보드 → 조직 설정 → API Keys 탭
- "새 API Key" → 이름(예:
Claude Code MCP) · 만료일 선택 → "생성" - 표시되는 키(
qn_...)를 복사하여 안전한 곳에 저장 (한 번만 노출됨)
Remote HTTP에 API Key 부착
claude mcp add --transport http qanote https://qanote.app/api/mcp \
--header "Authorization: Bearer qn_발급한_키"
Cursor / Codex JSON:
{
"mcpServers": {
"qanote": {
"url": "https://qanote.app/api/mcp",
"headers": { "Authorization": "Bearer qn_발급한_키" }
}
}
}
stdio 바이너리에 API Key 부착
{
"mcpServers": {
"qanote": {
"command": "npx",
"args": ["-y", "@qanote/mcp-server"],
"env": {
"QANOTE_API_KEY": "qn_발급한_키"
}
}
}
}
환경변수 (stdio 바이너리용)
| 변수 | 필수 | 설명 | 기본값 |
|---|---|---|---|
QANOTE_API_KEY | 선택 | API Key (qn_...). 미설정 시 OAuth 브라우저 로그인 사용 | — |
QANOTE_URL | 선택 | QA Note 서버 URL | https://qanote.app |
Remote HTTP 방식은 클라이언트가 직접 url 을 지정하므로 환경변수가 필요 없습니다.
사용 가능한 도구
조회 도구
| 도구 | 설명 |
|---|---|
resolve_by_url | 이슈 permalink 하나로 이슈 + 기술 컨텍스트를 한 번에 조회 (권장 진입점) |
list_projects | 접근 가능한 프로젝트 목록 |
search_issues | 이슈 검색 및 필터링 (상태·우선순위·라벨·검색어) |
get_issue | 이슈 상세 + 메타데이터 요약 |
get_console_logs | 브라우저 콘솔 로그 (에러/경고 우선 정렬) |
get_network_logs | 네트워크 요청 로그 (기본 에러만, 전체 조회 가능) |
get_user_actions | 이슈 발생 전 사용자 행동을 자연어로 변환 |
get_tech_context | JS 에러·성능·React 트리·환경 정보 통합 조회 |
get_element_styles | computed style · 박스 모델 · parent/sibling gap |
get_performance_metrics | Web Vitals · Navigation Timing |
get_environment_info | 브라우저·OS·네트워크·GPU·폰트 등 |
get_js_errors | 런타임 에러 + stack trace |
get_react_component_tree | React 컴포넌트 트리 스냅샷 |
get_storage | localStorage · sessionStorage · cookies (마스킹) |
get_dom_snapshot | DOM outerHTML (스크립트·입력값 마스킹) |
get_screenshots | 스크린샷 URL + 이미지 콘텐츠 embed |
쓰기 도구
| 도구 | 설명 |
|---|---|
update_issue | 이슈 상태·우선순위 변경 |
add_comment | 이슈에 코멘트 추가 |
추천 워크플로우
AI 코딩 도구에서 자연어로 요청하면 됩니다:
# 이슈 검색
"QA Note에서 critical 이슈 찾아줘"
# 디버깅 컨텍스트 확인
"이슈 #42의 콘솔 에러와 네트워크 로그 보여줘"
# 유저 행동 재현
"이슈 #15에서 사용자가 어떤 행동을 했는지 알려줘"
# 이슈 업데이트
"이슈 #42를 resolved로 변경하고, 수정 내용을 코멘트로 남겨줘"
최적의 디버깅 순서:
- 이슈 상세 페이지의 "MCP 프롬프트" 버튼으로 permalink 포함 프롬프트 복사 →
resolve_by_url한 방 - 보조로
get_tech_context·get_console_logs·get_network_logs로 깊이 파기 - 해결 후
update_issue로 상태 변경 +add_comment로 원인/수정 기록
동작 확인
설정 후 AI 도구에서:
QA Note에서 프로젝트 목록 보여줘
프로젝트 목록이 정상적으로 출력되면 설정 완료입니다.
트러블슈팅
OAuth 브라우저 창이 뜨지 않음 (Remote HTTP)
- 방화벽/팝업 차단 환경에서는 Claude Code 가 터미널에 출력하는
authorizeURL 을 직접 브라우저에 붙여넣어 로그인 · 동의를 마치면 됩니다. 완료되면 토큰이 자동 저장됩니다. - 회사 프록시가
.well-known/oauth-*디스커버리를 막는 경우 → 방법 B 의 stdio 바이너리로 전환하거나, 방법 C 의 API Key 로 우회하세요.
"Unauthorized" 에러
- OAuth 방식: 저장된 토큰이 만료/폐기된 경우입니다. MCP 서버를 재시작하면 브라우저 로그인이 다시 시작됩니다. stdio 바이너리는
~/.qanote/credentials.json을 삭제. - API Key 방식: 키가
qn_로 시작하는지, 대시보드에서 폐기되지 않았는지 확인. 다른 조직의 리소스에 접근하려면 해당 조직에서 별도 키를 발급하세요.
MCP 서버가 연결되지 않음 (stdio 바이너리)
npx -y @qanote/mcp-server를 터미널에서 직접 실행하여 정상 기동 여부 확인- Node.js 20 이상 필요
QANOTE_URL·QANOTE_API_KEY가 MCP 설정의env에 올바르게 포함됐는지 확인
토큰/세션 초기화
# stdio 바이너리
rm ~/.qanote/credentials.json
# Remote HTTP (Claude Code)
claude mcp remove qanote
claude mcp add --transport http qanote https://qanote.app/api/mcp
SSH · Docker 등 브라우저 불가 환경
→ 방법 C (API Key) 를 사용하세요. CI/CD 에서는 환경변수 또는 --header 주입이 가장 안전합니다.