KLASSLAB API / V1

선생님 개발 가이드

선생님의 아이디어를, 우리 수업만의 도구로.

API 버전

내 수업에 필요한 도구를 직접 만들어 보세요.

Codex에 KlassLab을 연결한 뒤, 필요한 화면과 기능을 설명하며 개발하는 가이드입니다. Claude Code·Gemini CLI 등에서도 같은 API·MCP를 활용할 수 있습니다.

01 계정과 개발 환경 준비하기

API 콘솔에서 활성 API 구독과 사용할 기능의 권한을 준비하세요. 일반 무료 계정의 AI 도우미 제공량과 외부 API·MCP 구독은 별도입니다. 가입 조건과 요금은 빠른 시작에서 확인할 수 있습니다.

Codex를 설치하고 OpenAI 계정으로 로그인한 뒤, 새 프로젝트 폴더를 열어 주세요. 처음에는 실제 학생 데이터가 없는 빈 폴더에서 시작하면 됩니다. 설치와 지원 환경은 Codex 공식 시작 안내 ↗를 확인하세요. Codex 등 AI 서비스의 이용 조건과 비용은 KlassLab과 별도입니다.

02 Codex에 KlassLab 연결하기

Codex의 MCP 서버 설정에서 아래 주소를 Streamable HTTP 서버로 등록하고, OAuth 로그인을 진행하세요. 설정 화면의 이름은 사용하는 앱·확장 프로그램 버전에 따라 달라질 수 있습니다.

MCP 서버 주소

https://api.klasslab.com/mcp/v1

GPT 화면에서 플러그인으로 연결하기

GPT에서 플러그인 메뉴를 엽니다.
추가를 누르고 사용자 지정 MCP 서버 추가를 선택합니다.
아래 표에 맞춰 이름과 연결 주소를 입력하고, 인증 방식으로 OAuth를 선택합니다.

입력 항목	설정할 값
이름	KlassLab
연결 주소	`https://api.klasslab.com/mcp/v1`
인증	OAuth

플러그인으로 생성을 누릅니다.
KlassLab 로그인·권한 동의 화면이 표시되면 사용할 계정으로 로그인하고, 연결할 기능의 권한을 확인한 뒤 동의합니다.
생성이 완료되면 새 대화에서 KlassLab 플러그인을 선택하고, 아래의 조회 요청으로 연결 확인하기를 진행합니다.

앱 버전에 따라 메뉴 이름이나 위치가 다를 수 있습니다. 인증 방식은 OAuth로 선택하고, API 키나 비밀번호를 대화창에 입력하지 마세요.

Codex CLI에서 연결하기

Codex CLI가 설치되어 있다면 터미널에서 다음 명령으로 등록하고 로그인할 수 있습니다.

CODEX CLI

codex mcp add klasslab --url https://api.klasslab.com/mcp/v1
codex mcp login klasslab
codex mcp list

브라우저에서 KlassLab 계정으로 로그인하고, 연결할 계정과 요청 권한을 확인한 뒤 동의하세요. 처음에는 조회 권한으로 시작하고 필요한 변경 권한을 추가하세요. 설정 후 새 대화를 열고 연결 상태를 확인합니다.

비밀번호나 API 키를 대화에 붙여 넣을 필요는 없습니다. 인증이 완료되지 않으면 MCP 연결 문제 해결을 확인하세요.

03 조회 요청으로 연결 확인하기

아래 요청을 복사해 Codex에 입력하세요. 연결 표시와 함께 실제 조회 결과까지 확인해야 합니다.

첫 요청

KlassLab 연결을 확인하고, 내가 조회할 수 있는 수강반 목록을 보여줘.
실제 조회 결과의 반 이름과 담당 선생님을 정리해줘.
데이터를 등록하거나 변경하지 마.

조회되지 않으면 API 구독 상태와 연결 권한을 확인하세요. 필요한 기능이 없다면 API 레퍼런스에서 필요한 기능을 확인할 수 있습니다. 웹 관리 기능은 API 구독 외에 해당 웹 구독 등급과 관리자 권한도 필요합니다. 기존 API 키·MCP 연결에 새 기능의 권한이 없다면 새 키 발급 또는 MCP 재연결 후 필요한 권한에 동의하세요.

04 내 수업에 맞는 화면 만들기

만들고 싶은 화면, 필요한 데이터, 실행 환경을 함께 설명하세요. 먼저 예시 데이터로 화면을 확인한 뒤 실제 API를 연결하는 순서가 좋습니다.

개발 요청 예시

이 폴더에 우리 수업용 수강반 대시보드를 만들어줘.
반 이름과 담당 선생님을 카드로 보여주고, 반 이름 검색을 넣어줘.
먼저 예시 데이터로 화면을 만들고 로컬에서 실행하는 방법을 알려줘.
확인 후 KlassLab 공개 API 문서의 실제 입력·응답 규격으로 연결해줘.
API 키는 서버 환경변수에만 보관하고 브라우저 코드에 넣지 마.
기존 학생·수강반 데이터는 변경하지 마.

MCP는 Codex가 개발 중 데이터를 조회하고 업무를 요청하는 연결입니다. 완성한 웹 서비스가 계속 데이터를 조회하려면 서비스의 서버에서 REST API를 호출하도록 구현하세요. MCP 연결만으로 완성한 앱의 인증이나 배포까지 자동 설정되지는 않습니다.

Codex가 안내하는 로컬 실행 명령으로 화면을 열어 확인하고, 수정할 점을 이어서 요청하세요. 서버 API 연결은 첫 요청 예제와 API 키 안내를 참고하면 됩니다.

05 업무 실행과 채점까지 확인하기

등록·수정은 테스트용 데이터를 대상으로 시작하세요. 대상 이름, 담당 선생님, 날짜 등 필요한 정보를 실제 조회 결과에서 확인하고, 변경할 내용을 검토한 후 실행하도록 요청하세요.

업무 요청 예시

테스트용 수강반을 만들고 싶어. 사용할 수 있는 담당 선생님 목록부터 조회해줘.
등록에 필요한 값이 없으면 나에게 물어보고 임의로 채우지 마.
실행 전 반 이름, 담당 선생님과 입력 내용을 보여주고 내 확인을 기다려줘.
기존 수강반은 변경하지 마.

OMR은 양식 조회 → 답안 파일 첨부 → 시험 선택 → 장수·차감 크레딧 확인 → 채점 → 결과 확인 순서로 진행합니다. 파일 첨부·전달 지원 여부는 AI 도구에 따라 다릅니다. 상세 흐름은 OMR 채점 가이드를 참고하세요.

직접 만드는 프로그램의 변경 요청에는 중복 방지 키와 재시도 규칙도 적용하세요. 배포 전에는 실제 계정 권한, 오류 안내, 사용량과 변경 결과를 확인합니다.

Claude Code·Gemini에서도 사용할 수 있나요?

네. Claude Code·Gemini CLI처럼 원격 MCP와 OAuth 인증을 지원하는 도구에서는 같은 KlassLab 서버 주소로 연결해 같은 업무와 개발 요청을 할 수 있습니다. 각 서비스에서 KlassLab 연결과 권한 동의를 따로 진행하세요. 설정 명령, 도구 승인 방식과 파일 첨부 지원은 서로 다를 수 있습니다.

Claude Code MCP 공식 안내 ↗: 원격 HTTP 서버를 추가하고 OAuth 인증을 진행합니다.
Gemini CLI MCP 공식 안내 ↗: HTTP MCP 서버를 설정하고 OAuth 인증을 진행합니다.

Gemini 일반 채팅 등 모든 화면이 원격 MCP를 지원하는 것은 아닙니다. 사용하는 제품·버전의 연결 지원 여부를 확인하세요. REST API를 직접 연결하는 개발 환경에서는 동일한 공개 API 규격을 사용할 수 있습니다.

클래스랩과 협업 신청

수업에 필요한 도구를 만들고 있거나, 만든 서비스를 KlassLab과 함께 발전시키고 싶다면 알려 주세요. 만들고 싶은 기능, 사용할 공개 API, 현재 진행 상황, 화면이나 데모 링크를 남겨 주시면 내용을 검토하고 답변드리겠습니다.

클래스랩과 협업 신청 →

로그인 후 기존 문의 접수 화면에서 신청하며, 답변과 처리 상태도 같은 곳에서 확인할 수 있습니다. 학생 개인정보와 API 키는 포함하지 마세요.

Codex 설정 참고: OpenAI 공식 MCP 문서 ↗