create-access-code MCP Tool

개요

create-access-code MCP Tool은 사용자 등록을 위한 액세스 코드를 생성하는 도구입니다. 이 도구를 통해 다양한 유형의 사용자를 위한 초대 코드를 간편하게 생성할 수 있습니다.

이 문서에서는 다음 사용 방법을 다룹니다:

• JSON 형식: 구조화된 데이터로 정확한 제어가 필요한 경우
• LLM AI Chat: 자연어로 간편하게 사용하고 싶은 경우

두 방법 모두 같은 결과를 제공하며, 사용자의 선호도와 상황에 따라 선택할 수 있습니다.

도구 정보

• 이름: create-access-code
• 설명: 사용자 등록을 위한 액세스 코드를 생성하는 도구
• 카테고리: 유틸리티 도구
• 지원 타입: STANDARD, ADMIN, RESEARCH, BETA, VIP

파라미터

필수 파라미터

없음 (모든 파라미터가 선택사항)

선택 파라미터

파라미터	타입	기본값	설명	예시
type	string	"STANDARD"	액세스 코드 타입	"RESEARCH"
creatorId	string	Service Account ID	생성자 ID	"creator-123"
treatmentPeriod	number	90	치료 기간 (일)	120
usagePeriod	number	130	코드 유효 기간 (일)	150
issuerAccountId	string	-	발급 계정 ID	"issuer-456"
sourceSiteId	string	-	소스 사이트 ID	"site-789"
email	string	-	코드 전송 이메일	"user@example.com"
deliveryMethod	string	-	전송 방법	"EMAIL"
registrationChannel	string	-	등록 채널	"research-portal"
randomizationCode	string	-	무작위화 코드	"RCT-2024-001"
privacyConsent	boolean	true	개인정보 동의 여부	true
useTimeMachine	boolean	false	테스트용 시간 조작	false
virtualTimeStartDate	number	-	가상 시작 시간 (ms)	1706745600000

코드 타입 (type)

• STANDARD: 일반 사용자용 코드
• ADMIN: 관리자용 코드
• RESEARCH: 연구 참여자용 코드
• BETA: 베타 테스터용 코드
• VIP: VIP 사용자용 코드

전송 방법 (deliveryMethod)

• EMAIL: 이메일로 전송
• SMS: SMS로 전송
• IN_APP: 앱 내 알림
• MANUAL: 수동 전달

LLM AI Chat에서의 사용법

LLM AI Chat에서는 자연어로 액세스 코드 생성을 요청할 수 있습니다. 다음과 같은 방식으로 사용할 수 있습니다:

기본 코드 생성 요청

액세스 코드를 생성해주세요.

또는

새로운 사용자를 위한 초대 코드를 만들어주세요.

특정 조건으로 코드 생성

연구 참여자용 액세스 코드를 생성해주세요. 
- 타입: RESEARCH
- 이메일: participant@university.edu
- 치료 기간: 120일
- 유효 기간: 150일

베타 테스터용 코드를 만들어주세요.
- 이메일로 전송
- 등록 채널: beta-program

관리자 코드 생성

관리자용 액세스 코드를 생성해주세요.
- 1년 동안 사용 가능
- 이메일: admin@organization.com
- 수동 전달 방식

대량 코드 생성

표준 사용자용 액세스 코드를 10개 생성해주세요.

사용자 정의 설정

다음 조건으로 액세스 코드를 생성해주세요:
- 타입: VIP
- 치료 기간: 180일
- 유효 기간: 200일
- 등록 채널: vip-program
- 개인정보 동의: true

자연어 응답 예시

요청: "연구 참여자용 코드를 생성해주세요."

응답: "연구 참여자용 액세스 코드가 성공적으로 생성되었습니다.

생성된 코드 정보:

• ID: 608543de-4411-49f0-bd8c-c0fce5fc51b6
• 코드: L3GFAL8EGDAE4UK4
• 타입: RESEARCH
• 상태: PENDING
• 치료 기간: 90일
• 유효 기간: 130일
• 시작일: 2025-07-08T08:29:10.380Z
• 만료일: 2025-11-15T08:29:10.380Z
• 생성 시각: 2025-07-08T08:29:10.395Z

이 코드는 연구 참여자가 앱에 등록할 때 사용할 수 있습니다."

팁과 모범 사례

1. 간단한 요청부터 시작: 복잡한 조건보다는 기본 요청부터 시작하여 필요에 따라 세부 조건을 추가하세요.

2. 명확한 용도 명시: 코드의 용도를 명확히 하면 AI가 적절한 기본값을 선택할 수 있습니다.

3. 이메일 주소 포함: 코드를 특정 사용자에게 전달해야 하는 경우 이메일 주소를 포함하세요.

4. 기간 설정: 특별한 요구사항이 있는 경우 치료 기간과 유효 기간을 명시하세요.

5. 에러 시 재시도: 에러가 발생하면 조건을 단순화하여 다시 시도하세요.

사용 예시 (JSON 형식)

최소 구성으로 생성

모든 매개변수가 선택사항이므로 매개변수 없이도 액세스 코드를 생성할 수 있습니다:

{
  "tool": "create-access-code",
  "arguments": {}
}

이 경우 다음 기본값들이 사용됩니다:

• type: "STANDARD"
• creatorId: Service Account ID (자동 설정)
• treatmentPeriod: 90일
• usagePeriod: 130일
• privacyConsent: true

사용자 지정 구성

{
  "tool": "create-access-code",
  "arguments": {
    "type": "RESEARCH",
    "treatmentPeriod": 120,
    "usagePeriod": 150,
    "email": "participant@research.org",
    "deliveryMethod": "EMAIL",
    "registrationChannel": "research-portal",
    "randomizationCode": "RCT-2024-001"
  }
}

응답 형식

성공적으로 액세스 코드가 생성되면 다음과 같은 정보가 반환됩니다:

{
  "content": [
    {
      "type": "text",
      "text": "Access code created successfully:\n\nID: 608543de-4411-49f0-bd8c-c0fce5fc51b6\nCode: L3GFAL8EGDAE4UK4\nType: STANDARD\nStatus: PENDING\nTreatment Period: 90 days\nUsage Period: 130 days\nStart Date: 2025-07-08T08:29:10.380Z\nExpiration Date: 2025-11-15T08:29:10.380Z\nCreated At: 2025-07-08T08:29:10.395Z\nCreator ID: 32a15ae5-9f5d-4a25-a8c0-f134f253d925\nIssuer Account ID: 8f81e538-3a42-47fb-9f2c-d1df305ac1ad\nSource Site ID: 366b062a-d0b4-4fd1-ab2d-105110a52396\nRegistration Channel: N/A\nPrivacy Consent: true"
    }
  ]
}

사용 시나리오

시나리오 1: 연구 참여자 초대

LLM AI Chat:

임상 연구 참여자를 위한 액세스 코드를 생성해주세요.
- 이메일: participant@university.edu
- 치료 기간: 84일
- 유효 기간: 120일
- 등록 채널: clinical-trial
- 무작위화 코드: CT-2024-PSY-001

JSON 형식:

{
  "tool": "create-access-code",
  "arguments": {
    "type": "RESEARCH",
    "email": "participant@university.edu",
    "treatmentPeriod": 84,
    "usagePeriod": 120,
    "registrationChannel": "clinical-trial",
    "randomizationCode": "CT-2024-PSY-001"
  }
}

시나리오 2: 베타 테스터 초대

LLM AI Chat:

베타 테스터를 위한 액세스 코드를 만들어주세요.
- 이메일: betatester@company.com
- 이메일로 전송
- 등록 채널: beta-program

JSON 형식:

{
  "tool": "create-access-code",
  "arguments": {
    "type": "BETA",
    "email": "betatester@company.com",
    "deliveryMethod": "EMAIL",
    "registrationChannel": "beta-program"
  }
}

시나리오 3: 관리자 계정 생성

LLM AI Chat:

관리자용 액세스 코드를 생성해주세요.
- 이메일: admin@organization.com  
- 1년 동안 사용 가능
- 수동 전달 방식

JSON 형식:

{
  "tool": "create-access-code",
  "arguments": {
    "type": "ADMIN",
    "email": "admin@organization.com",
    "treatmentPeriod": 365,
    "usagePeriod": 400,
    "deliveryMethod": "MANUAL"
  }
}

시나리오 4: 대량 코드 생성

LLM AI Chat:

표준 사용자용 액세스 코드를 10개 생성해주세요.
- 등록 채널: bulk-generation-20240108

JSON 형식 (반복 실행):

# 10개의 표준 코드 생성
for i in {1..10}; do
  {
    "tool": "create-access-code",
    "arguments": {
      "type": "STANDARD",
      "registrationChannel": "bulk-generation-$(date +%Y%m%d)"
    }
  }
done

시나리오 5: VIP 사용자 초대

LLM AI Chat:

VIP 사용자를 위한 특별한 액세스 코드를 생성해주세요.
- 이메일: vip@premium.com
- 치료 기간: 180일
- 유효 기간: 200일
- 등록 채널: vip-program

JSON 형식:

{
  "tool": "create-access-code",
  "arguments": {
    "type": "VIP",
    "email": "vip@premium.com",
    "treatmentPeriod": 180,
    "usagePeriod": 200,
    "registrationChannel": "vip-program"
  }
}

문제 해결

일반적인 오류

• 인증 실패: Service Account 토큰이 유효하지 않은 경우
• 권한 부족: 액세스 코드 생성 권한이 없는 경우
• 매개변수 오류: 잘못된 타입이나 범위의 값이 전달된 경우
• 서버 오류: API 서버에 문제가 있는 경우

에러 응답 예시

{
  "content": [
    {
      "type": "text",
      "text": "Error creating access code: Invalid treatment period. Minimum value is 1 day."
    }
  ],
  "isError": true
}

모니터링 및 추적

생성된 액세스 코드는 다음 방법으로 추적할 수 있습니다:

1. 로그 조회

LLM AI Chat:

오늘 생성된 액세스 코드와 관련된 로그를 조회해주세요.

또는

2024년 1월 15일 액세스 코드 생성 로그를 확인해주세요.

JSON 형식:

{
  "tool": "query-logs",
  "arguments": {
    "startTime": "2024-01-15T00:00:00.000Z",
    "endTime": "2024-01-15T23:59:59.999Z",
    "correlationId": "access-code-creation"
  }
}

2. 사용자 등록 확인

LLM AI Chat:

사용자 ID가 "registered-user-id"인 사용자의 설문 데이터를 조회해서 
액세스 코드 사용 여부를 확인해주세요.

또는

액세스 코드 "L3GFAL8EGDAE4UK4"를 사용한 사용자의 등록 상태를 확인해주세요.

JSON 형식:

{
  "tool": "questionnaire_data_query",
  "arguments": {
    "userId": "registered-user-id"
  }
}

3. 코드 사용 현황 조회

LLM AI Chat:

최근 7일간 생성된 액세스 코드의 사용 현황을 조회해주세요.

만료 예정인 액세스 코드가 있는지 확인해주세요.

4. 에러 발생 확인

LLM AI Chat:

액세스 코드 생성 시 발생한 에러를 확인해주세요.

최근 24시간 동안 액세스 코드 관련 에러가 있었는지 조회해주세요.

성능 고려사항

1. 대량 생성: 대량의 액세스 코드 생성 시 적절한 간격으로 요청하세요.
2. 이메일 전송: 이메일 전송 옵션 사용 시 전송 속도 제한을 고려하세요.
3. 데이터베이스 부하: 짧은 시간 내 많은 코드 생성 시 데이터베이스 부하를 고려하세요.

보안 및 프라이버시

• 생성된 코드는 안전한 채널을 통해서만 전달됩니다
• 적절한 usagePeriod 설정으로 보안 위험을 최소화합니다
• 코드 사용 여부를 정기적으로 모니터링합니다
• 코드 생성 권한을 필요한 사용자에게만 부여합니다
• 민감한 정보는 마스킹 처리됩니다
• 접근 권한이 있는 데이터만 조회 가능합니다

관련 도구

• query-logs: 액세스 코드 생성 로그 조회
• questionnaire_data_query: 사용자 등록 상태 확인
• query-recent-errors: 코드 생성 에러 조회
• analyze-error-patterns: 코드 생성 관련 에러 패턴 분석

관련 API

• Access Code API: REST API를 통한 액세스 코드 관리
• User Registration API: 생성된 코드를 사용한 사용자 등록

관련 문서

• MCP Tools 개요
• MCP Tools 가이드
• query-mobile-logs
• MCP Server 설정
• 에러 처리 가이드
• QA 가이드라인
• QA 규약