FairValid

개발자

MCP로 AI 에이전트 연결

ChatGPT, Claude, Hermes, Grok 또는 Codex를 설정하고, 연결을 확인하며, 검증 지출을 관리하세요.

API 키 관리API 레퍼런스

클라이언트 선택

엔드포인트: https://mcp.fairvalid.com/mcp. 전송 방식: Streamable HTTP.

API 키 또는 OAuth 로그인으로 연결하세요. 조건을 충족하는 ChatGPT, Claude 및 Grok 연결은 OAuth를 사용할 수 있습니다. 아래에서 사용 중인 클라이언트의 계정 및 역할 요구 사항을 확인하세요. Codex, Claude Code 및 Hermes는 API 키를 통한 직접 연결도 지원합니다.

API 키 클라이언트의 경우, 워크스페이스 Owner 또는 Manager 권한으로 API 키에서 라벨을 지정한 Test 키를 생성하세요. 키는 클라이언트의 보호된 자격 증명 또는 문서화된 환경 설정에 저장하세요. 키를 프롬프트, 도구 인수, URL 또는 커밋된 구성에 절대 넣지 마세요.

OAuth 흐름은 로그인과 동의를 위해 fairvalid.com을(를) 엽니다. 요청된 권한을 포함하는 기존 Live API 키를 선택하고, 해당 키의 워크스페이스와 전체 기간 한도를 검토합니다. 승인하면 해당 키의 범위 내에서 요청된 권한이 함께 부여됩니다. AI 클라이언트에 키를 붙여 넣을 필요는 없습니다. 선택한 키를 폐기하면 해당 연결도 종료됩니다. OAuth는 라이브 키를 사용하므로, 샌드박스에는 Test 키를 직접 연결하세요.

클라이언트 안내는 2026년 10월 23일에 검토되었습니다. 호스팅된 MCP 프로토콜은 공식 SDK를 사용한 프로덕션 인수 테스트를 통과했습니다. 이것이 명시된 모든 클라이언트가 테스트되었다는 의미는 아니므로, 사용하기 전에 해당 클라이언트에서 연결 확인을 완료하세요.

ChatGPT

아래 OAuth 설정을 사용하세요. 현재 맞춤 MCP 연결에는 웹의 ChatGPT Business 또는 Enterprise/Edu와 MCP로 플러그인을 만들 수 있는 권한이 필요합니다. Business는 관리자 또는 소유자가 필요하며, Enterprise/Edu는 선택한 멤버에게 권한을 부여할 수 있습니다.

  1. Plugins를 열고 더하기 버튼을 선택한 다음 Add custom MCP server를 선택하세요. 현재 Plugins 흐름에서는 Developer Mode가 필요하지 않습니다.
  2. 연결 이름을 FairValid로 지정하고 공개 HTTPS 엔드포인트로 https://mcp.fairvalid.com/mcp를 입력하세요.
  3. 자동 클라이언트 등록을 지원하는 OAuth를 선택하세요. FairValid는 공개 클라이언트 등록을 사용하므로 클라이언트 ID나 클라이언트 시크릿을 입력할 필요가 없습니다. 어느 필드에도 API 키를 입력하지 마세요.
  4. 위에 설명된 FairValid 로그인 및 동의 절차를 완료하세요. ChatGPT의 경고를 검토한 후 플러그인으로 생성을 선택하고 검색된 6개의 도구를 확인하세요.
  5. 플러그인을 설치하고 새 대화를 연 다음, @를 입력해 FairValid를 선택하세요. 실제 검증을 요청하기 전에 아래의 읽기 전용 연결 확인을 실행하세요.

공식 문서: OpenAI: 사용자 지정 MCP 서버 연결 · OpenAI: OAuth 인증

Claude 웹 및 데스크톱

OAuth를 사용하는 원격 맞춤 커넥터를 이용하세요. Claude 웹과 Desktop에서 동일하게 계정 기반으로 연결되며, Anthropic 서버를 통해 실행됩니다. Team 및 Enterprise에서는 조직 Owner가 먼저 커넥터를 추가해야 합니다. 조직 라이브러리를 관리하는 맞춤 역할이 있는 Enterprise 멤버도 추가할 수 있습니다.

Some organizations have a Request headers beta. For that alternative, choose No sign-in and add a required Authorization header with the full value Bearer <your FairValid API key>. If Request headers is absent, use OAuth or the Claude Code instructions below. The API key is not an OAuth client secret.

  1. Customize → Connectors → Add custom connector를 여세요. 관리형 조직의 경우 소유자 또는 해당 권한이 있는 Enterprise 역할 사용자가 Organization settings → Connectors → Add → Custom → Web에서 시작합니다.
  2. FairValid와 https://mcp.fairvalid.com/mcp를 입력하세요.
  3. 지금 로그인을 선택하세요. OAuth 클라이언트 선택 항목이 표시되면 자동 등록을 선택하세요. 수동 등록 클라이언트 ID 및 시크릿 필드는 비워 두세요.
  4. fairvalid.com에 로그인하여 선택한 라이브 키와 권한을 검토한 후 연결을 승인하세요. 대화의 커넥터 설정에서 FairValid를 활성화하세요.
  5. 아래의 읽기 전용 연결 검사를 실행하세요. 샌드박스 검사는 요청 헤더를 통해 테스트 API 키로 연결한 경우에만 사용하세요.

공식 문서: Anthropic: 사용자 지정 커넥터 및 인증 · Anthropic: 원격 커넥터 사용 가능 여부

Claude Code

Claude Code는 API 키를 통한 직접 연결을 지원합니다. Claude Code를 실행하는 환경에 FAIRVALID_API_KEY를 설정하고, 첫 검증에는 테스트 키를 사용하세요. 실제 시크릿은 프로젝트 파일에 포함하지 마세요.

  1. 아래 구성을 프로젝트의 .mcp.json에 병합하세요. 기존 서버는 그대로 유지하세요. 파일에는 환경 변수 참조를 그대로 넣고, 키 값은 넣지 마세요.
  2. FAIRVALID_API_KEY를 사용할 수 있는 상태에서 Claude Code를 실행하세요. 요청이 표시되면 프로젝트 MCP 구성을 승인하세요.
  3. claude mcp list를 실행한 다음 세션에서 /mcp를 확인하세요. FairValid가 연결되어 6개의 도구가 표시되는지 확인한 후 아래의 샌드박스 검사를 수행하세요.
{
  "mcpServers": {
    "fairvalid": {
      "type": "http",
      "url": "https://mcp.fairvalid.com/mcp",
      "headers": {
        "Authorization": "Bearer ${FAIRVALID_API_KEY}"
      }
    }
  }
}

공식 문서: Anthropic: Claude Code MCP 구성

Hermes Agent

이 안내는 NousResearch Hermes Agent용입니다. 원격 HTTP 전송은 bearer 헤더를 지원합니다. CLI는 활성 프로필의 .env에 키를 MCP_FAIRVALID_API_KEY로 저장하고, config.yaml에는 환경 변수 참조를 유지합니다.

  1. 아래의 add 명령을 실행하세요. 인증이 필요한지 묻는 질문에 yes로 답한 다음, 마스킹된 API key / Bearer token 프롬프트에 테스트 API 키를 입력하세요.
  2. 검색된 도구를 검토하고 필요한 FairValid 도구를 활성화하세요. 설정이 성공적으로 연결되어야 합니다. 오류가 발생한 후 비활성화된 연결을 저장하는 것은 설정에 성공한 것이 아닙니다.
  3. hermes mcp test fairvalid를 실행한 다음 새 세션을 시작하거나 /reload-mcp를 실행하세요. 그런 다음 아래의 샌드박스 검사를 수행하세요. Hermes는 도구 이름 앞에 서버 이름 접두사를 붙일 수 있습니다.
hermes mcp add fairvalid \
  --url https://mcp.fairvalid.com/mcp \
  --auth header

hermes mcp test fairvalid

공식 문서: NousResearch: MCP 구성 · NousResearch: MCP 연결 확인 · NousResearch: 헤더 인증 CLI 구현

Grok Bot 및 Grok

Grok Bot과 Grok.com은 설정하는 곳이 서로 다릅니다. 개인 Grok Bot에서는 아래 요청 문구로 Bot에게 FairValid를 추가해 달라고 요청하세요. 정보 창에 설정 섹션 없이 세부 정보, 라이브러리, 컴퓨터만 표시되는 경우에도 이 방법을 사용할 수 있습니다.

Team Bot의 경우 Bot 소유자 또는 관리자에게 정보 창 → 설정 → 플러그인 메뉴가 추가로 표시됩니다. 이 설정 화면을 이용하려면 데스크톱 앱에서 Team Bot 액세스 권한이 필요합니다. OAuth를 사용하는 경우 각 팀원은 자신의 계정으로 로그인합니다.

Grok.com에서는 grok.com/connectors → New Connector → Custom을 사용합니다. https://mcp.fairvalid.com/mcp를 입력하고 인증을 완료하세요. Business 및 Enterprise 팀은 관리자가 먼저 커넥터를 프로비저닝해야 할 수 있습니다. 이 연결은 Grok Bot 플러그인과는 별개입니다.

xAI API로 구축한 봇도 별개입니다. 해당 봇의 개발자가 서버 코드에서 원격 MCP 헤더를 구성합니다. 이 안내는 Grok Bot이 일반적인 Authorization 헤더 입력란을 제공한다고 주장하지 않습니다.

  1. 아래 요청을 사용해 Bot에게 사용자 지정 Remote HTTPS MCP 연결을 추가하도록 요청하세요. Team Bot의 경우 소유자나 관리자가 Setup → Plugins에서도 추가할 수 있습니다.
  2. When the Bot shows the FairValid authorization card, select Authorize to open OAuth sign-in. Keep API keys out of the request and any server command.
  3. fairvalid.com에서 FairValid 동의 절차를 완료하세요. 필요한 경우 팀원마다 각자의 계정을 연결해야 합니다.
  4. Bot에게 FairValid의 도구 목록을 보여 주고 아래의 읽기 전용 연결 확인을 실행하도록 요청하세요. 도구가 검색되었다고 해서 인증이 완료되었다는 의미는 아닙니다.
Add FairValid as a custom Remote HTTPS MCP server at
https://mcp.fairvalid.com/mcp using OAuth.
Show me the sign-in flow, then list its tools.
Do not submit any email verification yet.

공식 문서: xAI: Grok Bot 플러그인 및 원격 HTTPS · xAI: Grok.com 맞춤 커넥터 · xAI: API 개발자용 원격 MCP

Codex

Codex에서 API 키로 직접 연결하세요. Codex 프로세스에서 사용할 수 있는 환경에 FAIRVALID_API_KEY를 설정하고, 첫 검사에는 Test 키를 사용하세요. 별도로 실행한 데스크톱 앱은 터미널의 환경 변수를 상속하지 않을 수 있습니다.

  1. 아래 명령을 실행하여 원격 Streamable HTTP 서버를 등록하세요. 이 명령은 API 키가 아닌 환경 변수의 이름을 저장합니다.
  2. codex mcp list를 실행하고, 연결이 로드되도록 새 Codex 세션을 시작하세요. 세션의 MCP 도구에 FairValid가 표시되는지 확인하세요.
  3. Codex 앱을 사용하는 경우 해당 변수를 앱의 실행 호스트에서 사용할 수 있도록 설정하고, 필요에 따라 앱을 다시 시작하거나 새 세션을 여세요. CLI 설정에 성공했다고 해서 이미 실행 중인 앱의 환경이 바뀌었다고 가정하지 마세요.
  4. 발견된 도구 6개를 확인하고 아래의 샌드박스 점검을 수행하세요.
codex mcp add fairvalid \
  --url https://mcp.fairvalid.com/mcp \
  --bearer-token-env-var FAIRVALID_API_KEY

codex mcp list

공식 문서: OpenAI: Codex MCP 구성

작업을 제출하기 전에 연결을 확인하세요

아래에 나열된 6개 도구가 모두 검색되었는지 확인하세요. 클라이언트에 따라 도구 이름 앞에 자체 접두사가 붙을 수 있습니다. 검색은 연결을 확인할 뿐, 검증 성공을 의미하지는 않습니다.

OAuth 또는 Live API 키를 사용하는 경우 잔액 권한을 부여한 다음, 먼저 에이전트에게 인수 없이 fairvalid_get_balance을(를) 호출하도록 요청하세요. 잔액 조회에는 검증 크레딧이 사용되지 않습니다. 샌드박스 예시를 라이브 연결로 제출하지 마세요.

Test API 키를 사용하는 경우 아래 샌드박스 검사를 따르세요. 라이브 검증은 크레딧을 예약하고 사용할 수 있습니다. 검사 권한이 있는 주소를 선택하고 명시적으로 제출을 요청하세요.

연결에 실패하면 계정의 커넥터 권한, 엔드포인트, 누락된 환경 변수, 키 또는 권한 부여의 폐기 여부를 확인하세요. 권한 또는 지출 한도 오류의 경우 다시 시도하기 전에 부여된 범위나 한도를 검토하세요. 새 멱등성 키를 사용해도 원인은 해결되지 않습니다.

무료 샌드박스 검증으로 시작하세요

fv_test_ 키를 사용하여 아래 예시로 fairvalid_verify_email을 호출하세요. 테스트 키로 단일 주소를 검사하면 시뮬레이션 결과가 바로 반환됩니다. 제공업체 호출이나 실제 검증이 발생하지 않으며 크레딧도 사용되지 않습니다.

그 밖의 예약된 예시 주소는 undeliverable@example.com, risky@example.com, unknown@example.com, pending@example.com, error@example.com입니다. Pending과 error는 의도된 시뮬레이션이며 실제 메일함 확인이 아닙니다. 단일 주소 pending 예시에는 폴링할 작업이 없습니다.

{
  "email": "deliverable@example.com",
  "idempotency_key": "agent-demo-2026-10-23"
}

도구 및 권한

fairvalid_verify_email은 email과 idempotency_key를 받습니다. fairvalid_submit_job은 emails, idempotency_key, 선택적 name을 받으며 1~5,000개의 주소를 처리합니다. 라이브 제출에는 submit 범위가 필요합니다.

fairvalid_get_job은 job_id를 받아 상태를 조회합니다. fairvalid_get_results는 job_id와 선택적 cursor, filter, search를 받아 한 번에 최대 50개의 결과를 조회합니다. 라이브 조회에는 read 범위가 필요합니다.

fairvalid_cancel_job은 job_id를 받아 취소를 요청하며, 진행 중인 검사는 완료될 수 있습니다. 라이브 취소에는 submit 범위가 필요합니다. fairvalid_get_balance는 인수를 받지 않으며 balance 범위가 있는 라이브 키가 필요합니다. 테스트 키로는 라이브 크레딧 잔액을 조회할 수 없습니다.

키에 따라 워크스페이스가 결정됩니다. 도구는 API 키나 워크스페이스 인수를 받지 않습니다. 권한 범위 확인, 해지, 지출 한도 및 워크스페이스 크레딧 규정은 고객 API와 마찬가지로 MCP에도 동일하게 적용됩니다.

진행 중인 작업을 결과까지 따라가기

OAuth 또는 fv_live_ 키를 사용하면 단일 검증과 대량 검증 모두 비동기 작업으로 제출됩니다. accepted 응답과 job_id는 작업이 접수되었다는 의미일 뿐, 메일함 검사가 완료되었다는 의미는 아닙니다. 처리 시간은 대기열과 검증 제공업체에 따라 달라집니다.

작업 흐름을 샌드박스에서 미리 연습하려면 예약된 예시 주소로 fairvalid_submit_job을 호출하세요. 샌드박스 작업은 공급자 호출이나 크레딧 사용 없이 상태 조회, 결과, 취소 및 재전송을 지원합니다.

  1. 고정된 idempotency_key로 한 번만 제출하고 반환된 job_id를 보관하세요.
  2. 해당 job_id로 fairvalid_get_job을 호출하세요. 폴링 요청 간격을 두고, 일시적인 오류 시에는 간격을 늘리세요.
  3. 같은 job_id로 fairvalid_get_results를 호출하세요. next_cursor가 null이 될 때까지 각 next_cursor를 cursor로 다시 전달하세요. 커서는 원래의 필터와 검색 조건을 유지합니다.
  4. 작업 상태와 각 결과를 모두 확인하세요. 알 수 없음, 캐치올, 검증 중인 결과는 메일함이 유효하다는 근거가 아닙니다.

중복 작업 없이 재시도

두 제출 도구 모두 8~128자의 문자, 숫자, 마침표, 콜론, 밑줄 또는 하이픈으로 이루어진 idempotency_key가 필요합니다. 응답이 불확실하면 동일한 API 키 또는 OAuth 연결, idempotency_key, 변경되지 않은 입력으로 다시 시도하세요. 재실행은 기반이 되는 API 키 범위에서 적용됩니다. OAuth 액세스 토큰을 교체해도 해당 ID는 유지되지만, 다른 API 키를 선택해 다시 제출하면 별도의 실행이 생성될 수 있습니다. 기존 멱등성 키로 변경된 작업 페이로드를 보내면 거부됩니다. 의도적으로 새 실행을 시작할 때만 새 멱등성 키를 사용하세요.

결과를 읽기 전에 isError를 확인하세요. 고객 API에 도달한 호출은 structuredContent에 해당 응답과 HTTP 상태를 포함합니다. 인수 검증 오류는 텍스트 콘텐츠만 반환할 수 있습니다. API 오류의 code를 확인하고 재시도 안내가 있으면 따르세요. 시간 초과나 일시적 오류가 발생했다고 해서 원래 제출이 이루어지지 않았다는 의미는 아닙니다.

라이브 키는 워크스페이스 크레딧을 사용할 수 있습니다. 자율 에이전트를 연결하기 전에 전체 기간 한도를 설정하세요. 차감된 크레딧과 예약된 크레딧 모두 한도에 포함됩니다. 완료된 유효 및 무효 검사는 1크레딧을 사용하며, 알 수 없음, 미확인 캐치올 및 기술적 오류에는 최종적으로 검증 크레딧이 차감되지 않습니다.

도움이 더 필요하신가요?

비공개 지원 티켓을 시작하려면 로그인하세요.

고객 지원 문의