MCP 서버

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 동의창이 한 번 열립니다.

Claude Code

CLI 한 줄로 등록 · 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

터미널에 한 줄:

bash

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 에 추가:

json

{
  "mcpServers": {
    "qanote": {
      "url": "https://qanote.app/api/mcp"
    }
  }
}

headers 를 쓰지 않습니다. 처음 도구 호출 시 Cursor가 브라우저 OAuth 창을 띄워 줍니다.

Codex (OpenAI)

Codex CLI 설정 파일의 mcpServers 에 동일하게 추가:

json

{
  "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

bash

claude mcp add qanote -- npx -y @qanote/mcp-server

Cursor / Codex

json

{
  "mcpServers": {
    "qanote": {
      "command": "npx",
      "args": ["-y", "@qanote/mcp-server"]
    }
  }
}

인증 플로우

MCP 서버 최초 실행 시 저장된 크레덴셜이 없으면 브라우저가 자동으로 열립니다
QA Note 계정으로 로그인 (이미 로그인되어 있으면 동의만 진행)
발급된 토큰이 ~/.qanote/credentials.json 에 chmod 600 으로 저장됩니다 (기본 30일 유효)
이후 실행부터는 저장된 토큰을 자동 재사용하고, 만료 시 다시 브라우저가 열립니다

자격증명을 초기화하려면:

bash

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 부착

bash

claude mcp add --transport http qanote https://qanote.app/api/mcp \
  --header "Authorization: Bearer qn_발급한_키"

Cursor / Codex JSON:

json

{
  "mcpServers": {
    "qanote": {
      "url": "https://qanote.app/api/mcp",
      "headers": { "Authorization": "Bearer qn_발급한_키" }
    }
  }
}

stdio 바이너리에 API Key 부착

json

{
  "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에서 프로젝트 목록 보여줘

프로젝트 목록이 정상적으로 출력되면 설정 완료입니다.

트러블슈팅

OAuth 브라우저 창이 뜨지 않음 (Remote HTTP)

방화벽/팝업 차단 환경에서는 Claude Code 가 터미널에 출력하는 authorize URL 을 직접 브라우저에 붙여넣어 로그인 · 동의를 마치면 됩니다. 완료되면 토큰이 자동 저장됩니다.
회사 프록시가 .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 에 올바르게 포함됐는지 확인

토큰/세션 초기화

bash

# 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 주입이 가장 안전합니다.

MCP란?

한 번에 설치

사용 중인 MCP 클라이언트를 고르면 복사 또는 설치 링크가 바로 실행됩니다. 처음 연결 시 브라우저 OAuth 동의창이 한 번 열립니다.

사용 중인 MCP 클라이언트 하나만 고르세요

아래 카드에서 복사 또는 설치 액션 한 번이면 QA Note MCP 가 붙습니다. 처음 연결 시 브라우저 OAuth 동의창이 한 번 열립니다.

Claude Code

CLI 한 줄로 등록 · 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

터미널에 한 줄:

bash

claude mcp add --transport http qanote https://qanote.app/api/mcp

Cursor

~/.cursor/mcp.json 에 추가:

json

{
  "mcpServers": {
    "qanote": {
      "url": "https://qanote.app/api/mcp"
    }
  }
}

headers 를 쓰지 않습니다. 처음 도구 호출 시 Cursor가 브라우저 OAuth 창을 띄워 줍니다.

Codex (OpenAI)

Codex CLI 설정 파일의 mcpServers 에 동일하게 추가:

json

{
  "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 으로 세션이 조용히 갱신됨

방법 B. 로컬 바이너리 (stdio · npx)

Claude Code

bash

claude mcp add qanote -- npx -y @qanote/mcp-server

Cursor / Codex

json

{
  "mcpServers": {
    "qanote": {
      "command": "npx",
      "args": ["-y", "@qanote/mcp-server"]
    }
  }
}

인증 플로우

MCP 서버 최초 실행 시 저장된 크레덴셜이 없으면 브라우저가 자동으로 열립니다
QA Note 계정으로 로그인 (이미 로그인되어 있으면 동의만 진행)
발급된 토큰이 ~/.qanote/credentials.json 에 chmod 600 으로 저장됩니다 (기본 30일 유효)
이후 실행부터는 저장된 토큰을 자동 재사용하고, 만료 시 다시 브라우저가 열립니다

자격증명을 초기화하려면:

bash

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 부착

bash

claude mcp add --transport http qanote https://qanote.app/api/mcp \
  --header "Authorization: Bearer qn_발급한_키"

Cursor / Codex JSON:

json

{
  "mcpServers": {
    "qanote": {
      "url": "https://qanote.app/api/mcp",
      "headers": { "Authorization": "Bearer qn_발급한_키" }
    }
  }
}

stdio 바이너리에 API Key 부착

json

{
  "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에서 프로젝트 목록 보여줘

프로젝트 목록이 정상적으로 출력되면 설정 완료입니다.

트러블슈팅

OAuth 브라우저 창이 뜨지 않음 (Remote HTTP)

방화벽/팝업 차단 환경에서는 Claude Code 가 터미널에 출력하는 authorize URL 을 직접 브라우저에 붙여넣어 로그인 · 동의를 마치면 됩니다. 완료되면 토큰이 자동 저장됩니다.
회사 프록시가 .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 에 올바르게 포함됐는지 확인

토큰/세션 초기화

bash

# 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 주입이 가장 안전합니다.

MCP란?

한 번에 설치

사용 중인 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란?

한 번에 설치

사용 중인 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 등 브라우저 불가 환경