MCP 연동

RooQuiz는 MCP(Model Context Protocol) 서버를 제공하므로 Claude Desktop, Claude Code, Cursor, Codex 같은 AI 클라이언트가 팀 안의 퀴즈를 다룰 수 있습니다. 편집기에서 모든 것을 직접 만드는 대신, 자연어로 지식 퀴즈, 점수 퀴즈, 결과 유형 퀴즈를 만들고, 문항을 추가하고, 항목 순서를 바꾸고, 리포트 차원이나 결과 유형을 구성할 수 있습니다. 퀴즈 복제 / 삭제, 번역과 응답자 관리, 제출 기록·통계·전환 퍼널 조회도 가능합니다.

MCP는 고급 사용자를 위한 기능으로, MCP를 지원하는 AI 클라이언트가 필요합니다. 기본적인 시각적 퀴즈 제작에는 여전히 편집기를 권장합니다.

동작 방식

AI 클라이언트는 두 가지 인증 방식 중 하나로 RooQuiz의 MCP 엔드포인트(/api/mcp)에 연결합니다. OAuth 인증(권장 — 지원 클라이언트는 브라우저에서 로그인하기만 하면 됨) 또는 개인 API 토큰입니다.
어느 방식이든 AI는 현재 활성화된 팀 안에서 나로서 동작합니다.
모든 작업은 관리 화면과 같은 접근 권한 검사를 거치며, 쓰기 작업은 감사 로그에도 기록됩니다.
따라서 AI가 할 수 있는 일은 해당 팀에서의 내 역할과 권한으로 완전히 제한되며, 이를 넘어설 수 없습니다.

방법 1: OAuth 인증(권장)

MCP OAuth를 지원하는 클라이언트(claude.ai와 Claude Code)는 토큰을 직접 만들 필요가 없습니다. 엔드포인트 URL만 입력하면 클라이언트가 인증 서버를 자동으로 찾아 브라우저를 열고, 그곳에서 RooQuiz에 로그인한 뒤 인증할 팀을 고르고 "인증"을 클릭하면 됩니다.

claude.ai의 Settings → Connectors → Add custom connector를 엽니다.

원하는 이름을 지정합니다(예: RooQuiz).
원격 MCP 서버 URL로 엔드포인트(https://your-domain/api/mcp 형태)를 입력합니다.
저장하고 "Connect"를 클릭하면 브라우저가 RooQuiz 인증 페이지로 이동합니다. 로그인하고 팀을 고른 뒤 "인증"을 클릭하세요.

OAuth 연결에 대해:

인증할 때 고른 팀이 처음 활성 팀이 되며, AI는 이후 switch_active_tenant로 팀을 전환할 수 있습니다.
연결은 설정 → MCP 연동의 토큰 목록에 표시되며(OAuth 태그), 취소하면 해당 클라이언트의 연결이 끊깁니다. 토큰 5개 한도에는 포함되지 않습니다.
자격 증명은 자동으로 갱신되므로(액세스 토큰은 1시간 단위로 갱신되고, 연결 자체는 30일 동안 유효하며 사용할수록 연장됨) 직접 관리할 필요가 없습니다.

방법 2: 개인 토큰(PAT)

OAuth를 지원하지 않는 클라이언트(Cursor, Codex CLI, Claude Desktop)나 CI처럼 브라우저가 없는 환경에서는 개인 API 토큰으로 연결합니다.

토큰 만들기

설정 → MCP 연동으로 이동해 "토큰 만들기"를 클릭합니다.

알아보기 쉬운 이름을 지정합니다(예: Cursor - my Mac).
기본 팀을 선택합니다. 토큰은 기본적으로 이 팀에서 동작하며, AI는 나중에 switch_active_tenant 도구로 내가 속한 다른 팀으로 전환할 수 있습니다.
생성이 끝나면 rqp_live_로 시작하는 평문 토큰이 표시됩니다.

평문 토큰은 단 한 번만 표시됩니다. 페이지를 떠나면 다시 확인할 수 없습니다. 바로 복사하세요. 분실했다면 토큰을 취소하고 새로 만들어야 합니다.

제한 사항:

사용자마다 토큰은 최대 5개(취소된 토큰 포함, OAuth 연결은 제외)까지 보유할 수 있습니다. 더 만들려면 하나를 삭제해 자리를 비우세요("취소"는 비활성화만 할 뿐 자리를 비우지 않습니다).
토큰은 개인 자격 증명입니다. 절대 소스 코드 저장소에 커밋하거나 공개적으로 공유하지 마세요.

AI 클라이언트 구성

설정 → MCP 연동 페이지에서 클라이언트별로 바로 쓸 수 있는 구성 스니펫과 엔드포인트 URL(https://your-domain/api/mcp 형태)을 복사할 수 있습니다. 스니펫의 rqp_live_xxx...를 방금 생성한 토큰으로 바꾸세요.

Claude Code에서는 위의 OAuth 방식을 권장하며, 토큰 헤더는 CI처럼 브라우저가 없는 환경에서만 필요합니다.

claude mcp add --transport http rooquiz https://your-domain/api/mcp \
  --header "Authorization: Bearer rqp_live_xxx..."

프롬프트 예시

클라이언트를 연결했다면 평소 말하듯 지시하면 됩니다. 아래 예시는 각각 서버의 서로 다른 기능을 사용합니다.

템플릿으로 만들기

코칭 템플릿을 보여 주고, 준비도 템플릿으로 점수 퀴즈를 만든 다음, 예산에 관한 문항 두 개를 추가해 줘.

list_templates → create_form_from_template → add_question을 사용합니다.

리드 처리하기

이번 주에 Wheel of Life 퀴즈로 수집한 리드를 나열하고, 40점 미만인 사람에게 모두 follow-up 태그를 붙인 다음 나에게 배정해 줘.

list_leads → set_lead_tags → assign_leads를 사용합니다.

퍼널 진단하기

내 퀴즈 중 완료율이 가장 낮은 것은 무엇이고, 사람들이 정확히 어디에서 이탈하나요?

list_forms → get_form_stats → get_form_funnel을 사용합니다.

다국어로 확장하기

승진 준비도 퀴즈를 스페인어와 독일어로 번역해 줘. 문항 코드는 그대로 유지해.

list_form_translations → create_form_translation을 사용합니다.

응답자 이름, 이메일 주소, 전화번호는 마스킹된 상태로 반환됩니다 (j***[email protected]). 마스킹은 되돌릴 수 없으므로, 마스킹된 값을 프롬프트에 다시 붙여 넣지 말고 id로 응답자를 지칭하세요.

사용 가능한 도구

연결되면 AI 어시스턴트가 아래 도구를 호출할 수 있습니다. 모든 도구는 토큰이 현재 활성화된 팀에서 동작합니다.

팀(Tenant)

도구	기능
`list_my_tenants`	내가 속한 모든 팀을 나열하고 현재 활성 팀을 표시합니다.
`get_active_tenant`	토큰이 현재 활성화된 팀을 반환합니다. 모든 쓰기 작업은 기본적으로 이 팀에 적용됩니다.
`switch_active_tenant`	활성 팀을 전환합니다(세션 간에 유지되며, 대상은 내가 참여한 팀이어야 함).

퀴즈(Form)

도구	기능
`create_form`	퀴즈를 만듭니다(`knowledge_quiz` 시험, `scored_quiz`, 또는 `outcome_quiz` 유형 퀴즈). 왕복을 줄이도록 한 번의 호출로 문항 배열과 리포트 구성을 함께 받을 수 있습니다. 결과 유형 퀴즈는 생성할 때 `report.outcomes`(결과 유형 목록)를 반드시 포함해야 하며, 모든 선택지가 `outcomes`로 유형에 투표해야 합니다.
`list_forms`	현재 팀의 퀴즈를 나열합니다. 시나리오나 제목으로 필터링할 수 있습니다.
`get_form`	퀴즈의 전체 세부 정보(`fields[]` 문항 목록, 리포트 구성 등)를 봅니다. 편집하기 전에 먼저 호출해 각 문항의 `code`를 확인하세요. 결과 유형 퀴즈의 결과 유형 `code`는 `report.outcomeAnalysis.outcomes`에 있습니다.
`update_form`	제목, 설명, 공개/중지 상태를 수정하거나 `report` 구성을 하위 키 단위로 병합 교체합니다. 결과 유형 퀴즈에서는 `report.outcomes`를 전달해 `code` 기준으로 결과 유형(이름/설명/CTA)을 병합 업데이트합니다. 구성된 이미지는 유지되며, 문항 투표에서 아직 참조 중인 유형을 제거하는 것은 거부됩니다. 시나리오와 언어는 생성 후 고정됩니다.
`delete_form`	퀴즈를 휴지통으로 이동합니다(소프트 삭제). `list_forms`에서 숨겨지고 5일 동안 `restore_form`으로 복원할 수 있으며, 그 후 영구 삭제됩니다. 퀴즈 소유자 / 팀 소유자만 삭제할 수 있으며, 제출 기록은 영구 삭제 전까지 유지됩니다.
`restore_form`	`delete_form`으로 삭제된 퀴즈를 휴지통에서 복원합니다. 소유자 / 팀 소유자만 복원할 수 있으며, 휴지통에 없으면 오류가 발생합니다.
`duplicate_form`	퀴즈를 복제합니다. 문항 구조, 채점, 리포트, 시각 요소, 설정과 모든 언어 번역을 내가 소유한 새 퀴즈로 복제합니다(새 링크 발급). 제출 기록, 공유, 연동, 차단 상태는 복사하지 않습니다. `newTitle`은 선택 사항입니다.

문항(Question)

도구	기능
`add_question`	끝에 항목을 추가합니다. 문항(SingleCheck/MultiCheck/TrueFalse/FillBlank) 또는 페이지 나누기(`Breaker`)입니다. 결과 유형 퀴즈에서는 모든 선택지가 어떤 결과 유형에 투표할지 선언해야 합니다(TrueFalse는 `trueOutcomes` / `falseOutcomes` 사용).
`insert_question`	`after` / `before`로 기존 `code`를 참조해 특정 위치에 항목을 삽입합니다.
`move_question`	기존 문항이나 페이지 나누기를 `code`로 지정해 새 위치로 옮깁니다.
`update_question`	`code`로 지정한 문항의 질문, 메모, 해설, 필수 여부, 점수, 정답, FillBlank AI 채점을 수정합니다. 문항 유형이나 선택지 내용은 바꿀 수 없습니다.
`delete_question`	`code`로 지정한 문항이나 페이지 나누기를 삭제합니다.

리포트 차원

도구	기능
`set_dimension_analysis`	퀴즈의 다차원 분석(레이더 차트 차원)을 통째로 설정합니다. `knowledge_quiz`에서는 각 차원이 문항 `code`를 참조하고, `scored_quiz`에서는 각 차원이 수식을 사용합니다. 비우려면 빈 배열을 전달하세요. 결과 유형 퀴즈에는 적용되지 않습니다(차원이 없으므로 `report.outcomes`로 결과 유형을 구성하세요).

번역(FormTranslation)

퀴즈를 여러 언어로 제공합니다. 하나의 원본 퀴즈(기본 언어)와 다른 언어마다 하나씩의 번역으로 구성됩니다(번역은 원본과 같은 구조에 텍스트만 번역되며, 제출 기록은 항상 원본 퀴즈에 연결됩니다).

도구	기능
`create_form_translation`	퀴즈에 언어 버전을 추가합니다. 원본 문구를 초기 초안으로 복제하고(같은 `code`, 원본 언어 텍스트) 바로 번역할 수 있도록 그 내용을 반환합니다. 언어는 기본 언어와 달라야 하며 언어당 하나만 만들 수 있습니다.
`list_form_translations`	퀴즈의 기존 언어 버전(언어, 활성 여부, 공개 링크 등)을 나열합니다.
`get_form_translation`	그 자리에서 번역할 수 있도록 언어 버전 하나의 전체 내용(`fields[]`와 `report` 포함)을 읽습니다. 모든 `code`는 원본과 동일하게 유지해야 합니다.
`update_form_translation`	언어 버전의 번역 문구(title / description / fields / report / systemText)를 저장하거나 `isActive`로 일시 중지합니다. 구조는 원본에 의해 고정되며 텍스트만 바꿀 수 있고, 생략한 필드는 부분 번역으로 간주됩니다.
`delete_form_translation`	언어 버전 하나를 삭제합니다.

응답자(Examinees)

퀴즈에 응답하는 사람들입니다. 각 응답자는 하나의 팀에 묶여 있으며, 도구는 안전한 필드만 반환합니다. 비밀번호, 인증 코드, 재설정 토큰 등 민감한 필드는 절대 노출되지 않습니다.

도구	기능
`list_examinees`	현재 팀의 응답자를 나열합니다. 이메일 / 이름으로 유사 검색하고 상태(활성 / 비활성)로 필터링할 수 있습니다.
`get_examinee`	비즈니스 ID `examineeId`(예: `AB1234567890`, 목록에 표시됨)로 응답자의 세부 정보(사용자 정의 `customData` 포함)를 봅니다.
`update_examinee`	`examineeId`로 지정한 응답자의 이름 / 상태 / customData를 수정합니다(customData는 팀의 필드 정의에 따라 검증됨). 이메일과 팀은 바꿀 수 없습니다.

기록 및 분석

퀴즈 성과, 전환 퍼널, 리드를 읽어 AI가 제작 → 측정 → 개선 루프를 완성할 수 있게 합니다. 리드 도구는 응답자 정보(개인 식별 정보)를 반환합니다.

도구	기능
`get_form_stats`	최근 N일(기본 30일, 최대 180일) 동안의 퀴즈 통계를 읽습니다. KPI 개요, 일별 추세, 채널(utm_source), 로그인 유형, 기기, 문항별 응답 분포를 포함합니다.
`get_form_funnel`	최근 N일 동안의 퀴즈 전환 퍼널을 읽습니다. 조회 → 시작 → 제출 → 리드 확보 → 리포트 조회 → CTA 클릭 → 공유 단계와 채널별 퍼널, 이탈 지점을 포함합니다.
`list_records`	현재 팀의 제출 기록(리드)을 나열합니다. 응답자, 답변, 간단한 리포트 결과, UTM을 포함하며 퀴즈, 리포트 상태, 제출 시각으로 필터링할 수 있습니다.
`get_record`	`id`(`list_records`가 반환)로 기록 하나의 세부 정보를 봅니다. 전체 답변, 리포트 결과, 제출 메타데이터를 포함합니다.

이미지 업로드

도구	기능
`prepare_image_upload`	1단계: 표지/이미지용 직접 업로드 URL을 발급합니다(해당 URL로 파일을 PUT).
`finalize_image_upload`	2단계: 이미지를 검증하고 팀 미디어 라이브러리에 기록한 뒤 미디어 id를 반환합니다. `update_form`의 `flagImg` / `landingImage`에서 참조하세요.

일반적인 흐름:

시험 / 점수 퀴즈: create_form으로 퀴즈를 만들고 각 문항의 code를 받습니다 → update_form 또는 set_dimension_analysis로 code를 기준으로 리포트 수식 / 차원을 구성합니다.
결과 유형 퀴즈: report.outcomes(유형마다 직접 정한 고유 code 지정, 예: lion)와 각 선택지의 투표를 포함해 create_form을 한 번 호출합니다 → 제출 후 가장 많은 표를 받은 유형이 결과가 됩니다(동점이면 목록 순서로 결정). 유형 문구 / CTA는 나중에 update_form으로 다듬습니다.

현재 제한 사항

랜덤 지식 퀴즈는 지원하지 않습니다. 문항이 QuestionBank에 있으므로 편집기에서 관리하세요. MCP는 아직 이를 다루지 않습니다.
문항 유형이나 선택지를 직접 바꿀 수 없습니다. 유형을 바꾸거나 선택지를 편집하려면 delete_question 후 add_question으로 다시 만드세요. 결과 유형 퀴즈의 선택지-유형 투표 매핑도 마찬가지로, 투표를 바꾸려면 문항을 다시 만들어야 합니다.
점수 퀴즈의 선택지 채점은 선택지 점수(Option Scoring)를 사용합니다. 점수 퀴즈 시나리오에서 update_question은 score / correctAnswer / aiMatch를 거부합니다. 선택지 점수는 관리 화면에서 편집하거나, 삭제 후 다시 만드세요. 결과 유형 시나리오도 이 세 매개변수를 똑같이 거부합니다(투표로 결정하므로 채점이 없습니다).
결과 유형 퀴즈의 문항 유형: 투표 문항은 SingleCheck / MultiCheck / TrueFalse입니다(FillBlank는 지원하지 않음). 결과 유형 이미지는 아직 MCP로 업로드할 수 없으니 편집기에서 구성하세요(MCP가 report.outcomes를 업데이트해도 이미 구성된 이미지는 유지됨).
시나리오와 언어는 생성 후 고정되며 MCP로 바꿀 수 없습니다.
삭제는 소프트 삭제입니다. delete_form은 즉시 영구 삭제하는 것이 아니라 휴지통으로 이동합니다(5일 후 자동 영구 삭제). 영구적으로 제거하려면 관리 화면에서 다시 삭제하세요.
문항 수 제한: Free 플랜에서는 퀴즈 하나에 최대 50문항까지 넣을 수 있으며(페이지 나누기, 설명문, 이미지 캐러셀은 제외), 이를 넘으면 create_form, add_question, insert_question이 거부됩니다. duplicate_form과 create_form_from_template은 제한되지 않습니다. Pro는 제한이 없습니다. 문항 수 제한을 참고하세요.
복제는 데이터를 복사하지 않습니다. duplicate_form은 구조와 번역만 복제하며, 제출 기록, 공유 설정, 연동(시크릿 포함)은 복사하지 않습니다. 새 퀴즈는 깨끗한 상태로 시작합니다.
응답자 신원 필드는 변경할 수 없습니다. update_examinee로는 이메일, 팀, examineeId(인증 신원)를 바꿀 수 없습니다.
리드에는 개인 식별 정보가 포함됩니다. list_records / get_record는 응답자 이메일, 이름, 사용자 정의 필드 등을 반환하므로 책임감 있게 다루세요.
FillBlank AI 채점(aiMatch, 지식 퀴즈 시나리오 전용, Beta)은 팀의 AI 크레딧을 소모합니다.

보안 및 요청 속도 제한

OAuth든 토큰이든 AI는 나로서 동작하며, 기존 접근 권한 검사와 감사 로그가 적용됩니다(모든 쓰기 작업이 기록됨).
연결마다 분당 60회 요청으로 제한되며, 초과하면 속도 제한 오류를 반환합니다.
더 이상 필요 없으면 설정 → MCP 연동에서 취소(즉시 적용, OAuth 연결은 클라이언트 연결이 끊김)하거나 삭제(자리도 비워짐)하세요.
OAuth 흐름은 PKCE(S256) 를 강제하고, 인증 코드는 한 번만 사용할 수 있으며, 리프레시 토큰은 갱신할 때마다 교체되어 이전 토큰은 즉시 무효화됩니다.

이 페이지의 내용