본문으로 건너뛰기

lookup-user-by-email MCP Tool

개요​

lookup-user-by-email MCP Tool은 사용자의 이메일 주소로 사용자 ID를 조회하는 도구입니다. 이메일 주소만 알고 있을 때 해당 사용자의 시스템 내 고유 ID를 찾아주어 다른 사용자 관련 작업을 수행할 수 있게 해줍니다.

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

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

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

도구 정보​

  • 이름: lookup_user_by_email
  • 설명: 이메일 주소로 사용자 ID를 조회하는 도구
  • 카테고리: 사용자 관리 도구

파라미터​

필수 파라미터​

파라미터타입설명제약사항
emailstring조회할 사용자의 이메일 주소유효한 이메일 형식 (예: user@example.com)

이메일 형식 검증​

email은 다음 형식을 따라야 합니다:

  • 유효한 이메일 주소 형식
  • @ 기호 포함
  • 도메인 부분 포함
  • 예시: user@example.com, test.user@company.co.kr

LLM AI Chat에서의 사용법​

LLM AI Chat에서는 자연어로 이메일 주소를 이용한 사용자 조회를 요청할 수 있습니다.

기본 사용자 조회​

이메일 주소 user@example.com의 사용자 ID를 찾아주세요.

또는

user@example.com으로 등록된 사용자의 ID를 조회해주세요.

문제 해결 목적 조회​

고객이 이메일 user@example.com으로 문의했는데, 이 사용자의 ID를 찾아주세요.
이메일 user@example.com의 사용자 정보를 확인하고 싶습니다. 먼저 사용자 ID를 조회해주세요.

사용자 관리 목적 조회​

이메일 user@example.com의 사용자 ID를 조회한 후 상태를 확인해주세요.
user@example.com 사용자의 계정 상태를 확인하기 위해 먼저 사용자 ID를 찾아주세요.

자연어 응답 예시​

요청: "이메일 주소 swcbok@gmail.com의 사용자 ID를 찾아주세요."

응답: "이메일 주소로 사용자 ID를 조회했습니다.

📧 사용자 조회 결과:

  • 이메일: swcbok@gmail.com
  • 사용자 ID: 3a5822e5-595e-4bd5-b06a-f46104a34bd5
  • 상태: 조회 성공

해당 이메일 주소로 등록된 사용자를 찾았습니다. 이 사용자 ID를 사용하여 추가적인 사용자 상태 조회나 다른 작업을 수행할 수 있습니다."

사용 예시 (JSON 형식)​

기본 사용자 조회​

{
  "tool": "lookup_user_by_email",
  "arguments": {
    "email": "user@example.com"
  }
}

특정 도메인 사용자 조회​

{
  "tool": "lookup_user_by_email",
  "arguments": {
    "email": "test.user@company.co.kr"
  }
}

응답 형식​

성공 응답 예시​

{
  "content": [
    {
      "type": "text",
      "text": "User lookup successful:\n\nEmail: swcbok@gmail.com\nUser ID: 3a5822e5-595e-4bd5-b06a-f46104a34bd5\nStatus: Found"
    }
  ]
}

응답 데이터 구조​

필드설명
Email조회에 사용된 이메일 주소
User ID찾은 사용자의 고유 ID (UUID 형식)
Status조회 결과 상태 (Found/Not Found)

사용 시나리오​

시나리오 1: 고객 문의 처리​

LLM AI Chat:

고객이 이메일 customer@example.com으로 문의했습니다.
이 사용자의 계정 상태를 확인하기 위해 먼저 사용자 ID를 조회해주세요.

JSON 형식:

{
  "tool": "lookup_user_by_email",
  "arguments": {
    "email": "customer@example.com"
  }
}

시나리오 2: 사용자 계정 관리​

LLM AI Chat:

이메일 admin@company.com의 사용자 ID를 찾아서
해당 사용자의 상태를 확인해주세요.

JSON 형식:

{
  "tool": "lookup_user_by_email",
  "arguments": {
    "email": "admin@company.com"
  }
}

시나리오 3: 데이터 분석​

LLM AI Chat:

이메일 researcher@university.edu 사용자의 설문 응답 데이터를 조회하고 싶습니다.
먼저 사용자 ID를 찾아주세요.

JSON 형식:

{
  "tool": "lookup_user_by_email",
  "arguments": {
    "email": "researcher@university.edu"
  }
}

시나리오 4: 사용자 지원​

LLM AI Chat:

이메일 support@helpdesk.com의 사용자가 로그인 문제를 신고했습니다.
사용자 ID를 찾아서 최근 로그를 확인해주세요.

JSON 형식:

{
  "tool": "lookup_user_by_email",
  "arguments": {
    "email": "support@helpdesk.com"
  }
}

시나리오 5: 다른 도구와 연계 사용​

LLM AI Chat:

이메일 test@example.com의 사용자 ID를 찾은 후,
해당 사용자의 현재 상태를 조회해주세요.

JSON 형식 (순차 실행):

// 1단계: 사용자 ID 조회
{
  "tool": "lookup_user_by_email",
  "arguments": {
    "email": "test@example.com"
  }
}

// 2단계: 조회된 사용자 ID로 상태 확인
{
  "tool": "get_user_state",
  "arguments": {
    "userId": "조회된-사용자-ID"
  }
}

문제 해결​

일반적인 문제​

  1. 이메일 형식 오류: 잘못된 이메일 형식 입력
  2. 사용자 미존재: 시스템에 등록되지 않은 이메일 주소
  3. 권한 부족: 사용자 조회 권한 없음
  4. 네트워크 오류: API 호출 실패

에러 응답 예시​

이메일 형식 오류:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Invalid email format. Please provide a valid email address\nEmail: invalid-email"
    }
  ],
  "isError": true
}

사용자 미존재:

{
  "content": [
    {
      "type": "text",
      "text": "User lookup failed:\n\nEmail: notfound@example.com\nStatus: Not Found\nMessage: No user found with this email address"
    }
  ],
  "isError": true
}

권한 부족:

{
  "content": [
    {
      "type": "text",
      "text": "Error looking up user:\n\nStatus Code: 403\nError Code: ACCESS_DENIED\nMessage: Access denied: Insufficient permissions\nEmail: restricted@example.com"
    }
  ],
  "isError": true
}

문제 해결 가이드​

  1. 이메일 형식 확인: 올바른 이메일 형식인지 확인
  2. 사용자 등록 확인: 해당 이메일로 등록된 사용자가 있는지 확인
  3. 권한 확인: 사용자 조회 권한이 있는지 확인
  4. API 상태 확인: 사용자 관리 API 서비스 상태 확인

모니터링 및 추적​

1. 조회 이력 추적​

LLM AI Chat:

최근 24시간 동안 사용자 조회 관련 로그를 확인해주세요.

JSON 형식:

{
  "tool": "query_recent_errors",
  "arguments": {
    "hours": 24,
    "serviceName": "user-lookup"
  }
}

2. 조회 실패 분석​

LLM AI Chat:

사용자 조회 실패 관련 에러 패턴을 분석해주세요.

JSON 형식:

{
  "tool": "analyze_error_patterns",
  "arguments": {
    "startTime": "2024-01-01T00:00:00.000Z",
    "endTime": "2024-01-08T00:00:00.000Z",
    "serviceName": "user-lookup"
  }
}

성능 고려사항​

  1. 캐싱: 자주 조회되는 이메일-사용자 ID 매핑은 캐시 활용
  2. 인증: Service Account 토큰 사용으로 보안 강화
  3. 검증: 이메일 형식 검증으로 불필요한 API 호출 방지
  4. 에러 처리: 명확한 에러 메시지 제공

보안 및 프라이버시​

  • Service Account 토큰 인증 필요
  • 이메일 주소 정보 보호 준수
  • 권한이 있는 사용자만 조회 가능
  • 개인정보 취급 규정 준수
  • 로그 기록을 통한 접근 추적

관련 도구​

  • get-user-state: 조회된 사용자 ID로 상태 확인
  • questionnaire_data_query: 사용자 설문 데이터 조회
  • query-recent-errors: 사용자 관련 오류 조회

관련 문서​