Waafir
이 페이지는 사람의 검토를 기다리는 기계 번역입니다. 오류가 있을 수 있습니다.

설정

AI 어시스턴트를 Waafir에 연결하는 데는 URL 하나면 됩니다. 어시스턴트에 URL을 붙여넣고, 요청이 오면 Waafir에 로그인하세요. 토큰을 생성하거나 복사할 필요가 없습니다. 이 페이지에서는 로그인 과정, 어시스턴트별 서버 추가 단계, 그리고 어시스턴트가 로그인할 수 없을 때 대신 개인 액세스 토큰으로 연결하는 방법을 설명합니다.

기본 사항

URL. 하나의 URL로 모든 Waafir 도구를 사용할 수 있습니다.

https://app.waafir.io/api/mcp/waafir

추가 기능 → 설정 → AI 어시스턴트에 사용 중인 배포 환경의 URL이 복사 버튼과 함께 표시됩니다. 다른 배포 환경을 사용하는 경우 https://app.waafir.io를 바꾸세요.

로그인. 어시스턴트가 이 URL을 처음 사용하면 브라우저에서 Waafir가 열립니다. 평소처럼 로그인한 다음 동의 화면을 검토하세요.

  • 어떤 조직인지: 여러 조직에 속해 있는 경우 어시스턴트가 작업할 조직.
  • 어떤 데이터룸인지: 모든 데이터룸에 접근할지, 선택한 데이터룸에만 접근할지.
  • 무엇을 할 수 있는지: 읽기, 쓰기 또는 관리자 권한(본인의 역할이 허용하는 범위를 넘지 않음), 그리고 문서 서명이나 조직 외부로의 전송을 허용할지 여부.
  • 본인 확인. 2단계 인증을 설정한 경우, 토큰을 생성할 때와 마찬가지로 승인할 때마다 먼저 코드를 요청합니다.

승인하면 브라우저가 다시 어시스턴트로 돌아갑니다. 연결은 추가 기능 → 설정 → AI 어시스턴트에 표시되며, 여기에서 접근할 수 있는 항목을 확인하고 연결을 취소할 수 있습니다. 연결을 참조하세요.

Unverified app "…". 자신이 관리하는 웹 주소로 자신을 식별하는 어시스턴트는 claude.ai처럼 그 주소로 표시됩니다. 스스로 정한 이름으로 자체 등록한 어시스턴트는 Unverified app "<its name>"으로 표시됩니다. Waafir는 누가 만들었는지 확인할 수 없으므로, 본인이 직접 연결을 시작한 경우에만 승인하세요.

도구 목록에 표시되는 내용. 도구 이름은 해당 영역으로 시작합니다: dataroom_, esign_, redact_, translate_. 목록에는 연결과 조직이 사용할 수 있는 도구만 표시됩니다. 읽기 전용 연결에는 쓰기 도구가 표시되지 않으며, 전자 서명 도구는 조직이 E-Signatures 추가 기능이나 활성 구독을 보유한 경우에만 나타납니다. 연결의 목록에는 서명이나 조직 외부 전송처럼 부여하지 않은 권한이 필요한 도구도 포함됩니다. 어시스턴트가 그런 도구를 호출하면 Waafir는 호출을 거부하고, 어시스턴트는 이번에는 해당 권한을 선택지로 제시하며 다시 승인을 요청합니다. 토큰은 다시 요청할 수 없으므로 토큰의 목록에는 그러한 도구가 빠져 있습니다. 목록에 없는 도구라도 어시스턴트가 굳이 호출하면 그 이유와 함께 거부됩니다.

어시스턴트 연결

아래 각 섹션에서는 어시스턴트별 서버 추가 단계와 해당 문서 링크를 안내합니다(각 링크는 2026년 10월 23일에 마지막으로 확인됨). 이 어시스턴트들은 아직 Waafir 로그인으로 테스트되지 않았으므로, 각 섹션에 토큰을 이용한 대체 방법을 함께 안내합니다.

Claude (claude.ai 및 Claude Desktop)

아직 Waafir에서 테스트하지 않았습니다. Customize → Connectors를 열고 Add → Add custom connector를 선택한 다음, 이름을 지정하고 URL을 붙여넣은 후 계속합니다. 로그인은 켜 둔 채로 두고, Claude가 요청하면 Waafir에 로그인하세요. 채팅에서 사용하려면 + → Connectors에서 켜세요. Team 또는 Enterprise 플랜에서는 소유자가 Organization settings → Connectors에서 커넥터를 추가합니다. (Claude 가이드)

로그인이 되지 않으면 대신 토큰을 사용한 요청 헤더 Authorization: Bearer <token>을 추가하세요(대신 토큰으로 연결 참조).

ChatGPT

아직 Waafir에서 테스트하지 않았습니다. ChatGPT에서 원격 MCP 서버를 추가하는 위치는 앱에 따라 다릅니다. 데스크톱 앱에서는 Settings → MCP servers → Add server를 열고 URL을 붙여넣은 다음, 요청이 오면 Waafir에 로그인하세요. (OpenAI 가이드)

ChatGPT가 로그인할 수 없으면 대신 토큰을 사용하세요.

Claude Code

아직 Waafir에서 테스트하지 않았습니다.

claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir

그런 다음 Claude Code 안에서 /mcp를 실행하고(또는 셸에서 claude mcp login waafir 실행) 브라우저에서 Waafir에 로그인하세요. 모든 프로젝트에서 사용하려면 --scope user를 추가하세요. 추가 기능 → 설정 → AI 어시스턴트에 이 명령이 바로 복사할 수 있도록 준비되어 있습니다. (Claude Code 가이드)

Cursor

아직 Waafir에서 테스트하지 않았습니다. URL을 .cursor/mcp.json(모든 프로젝트에서 사용하려면 ~/.cursor/mcp.json)에 추가한 다음, Cursor가 요청하면 Waafir에 로그인하세요.

{
  "mcpServers": {
    "waafir": {
      "url": "https://app.waafir.io/api/mcp/waafir"
    }
  }
}

(Cursor 가이드)

Cursor가 로그인할 수 없으면 대신 토큰으로 연결에 나와 있는 토큰 헤더를 추가하세요.

VS Code

아직 Waafir에서 테스트하지 않았습니다. 명령 팔레트에서 MCP: Add Server를 실행하고 HTTP를 선택한 다음, URL을 붙여넣고 id를 waafir로 지정하세요. VS Code가 요청하면 Waafir에 로그인하세요. (VS Code 가이드)

Gemini CLI

아직 Waafir에서 테스트하지 않았습니다.

gemini mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir

그런 다음 /mcp auth waafir를 실행하고 브라우저에서 로그인하세요. 로그인에는 로컬 브라우저가 필요하므로 대부분의 원격 SSH 세션에서는 작동하지 않습니다. 이 경우에는 토큰을 사용하세요. (Gemini CLI 가이드)

Codex

아직 Waafir에서 테스트하지 않았습니다.

codex mcp add waafir --url https://app.waafir.io/api/mcp/waafir
codex mcp login waafir

(Codex 가이드)

대신 토큰으로 연결

어시스턴트가 로그인할 수 없거나 스크립트를 사용하는 경우 개인 액세스 토큰을 사용하세요. 모든 요청은 Authorization 헤더에 토큰을 bearer 토큰으로 담아 보냅니다.

Authorization: Bearer waafir_pat_...

실제 토큰을 공유 파일이나 저장소에 커밋하지 마세요. 비밀번호처럼 취급해야 합니다. 추가 기능 → 설정 → API 토큰에 바로 복사할 수 있는 스니펫이 있습니다.

영역 서버. waafir 외에 네 개의 영역 서버도 계속 제공되므로 기존 구성이 그대로 작동합니다. 각 영역 서버는 자기 영역의 도구만 같은 방식으로 필터링하여 표시하며, 기존의 도구 이름(dataroom_list_files가 아닌 list_files)을 유지합니다. waafir에 연결한다면 이 서버들은 필요하지 않습니다.

서버URL
waafir-redacthttps://app.waafir.io/api/mcp/waafir-redact
waafir-translatehttps://app.waafir.io/api/mcp/waafir-translate
waafir-dataroomhttps://app.waafir.io/api/mcp/waafir-dataroom
waafir-esignhttps://app.waafir.io/api/mcp/waafir-esign

서버 이름이 없는 /api/mcp 엔드포인트는 없습니다. 서버 이름 세그먼트는 필수이며, 이것이 없는 요청은 404를 반환합니다. waafir-esign은 유료 서비스입니다. E-Signatures 추가 기능이나 활성 구독이 없으면 해당 URL은 ADDON_NOT_PURCHASED 오류로 응답합니다. waafir에서는 같은 조직에 esign_ 도구가 단순히 표시되지 않습니다.

Claude Code. 셸 기록에 남지 않도록 먼저 토큰을 환경 변수에 넣으세요.

export WAAFIR_PAT=...   # the token you copied at issuance
claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir \
  --header "Authorization: Bearer $WAAFIR_PAT"

프로젝트와 설정을 공유하려면 같은 항목을 프로젝트의 .mcp.json에 넣으세요. Claude Code는 각 사용자의 환경에서 ${WAAFIR_PAT}를 확장하므로 토큰 없이 파일을 커밋할 수 있습니다.

{
  "mcpServers": {
    "waafir": {
      "type": "http",
      "url": "https://app.waafir.io/api/mcp/waafir",
      "headers": {
        "Authorization": "Bearer ${WAAFIR_PAT}"
      }
    }
  }
}

Claude Desktop 구성 파일. claude_desktop_config.json은 로컬 서버를 시작합니다. 각 항목은 원격 url이 아니라 실행할 command입니다. 이 파일에서 Waafir에 접근하려면 mcp-remote 브리지(Node.js 필요)를 실행하세요. 이 브리지는 원격 서버로 요청을 전달하고 토큰을 헤더로 추가합니다.

{
  "mcpServers": {
    "waafir": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.waafir.io/api/mcp/waafir",
        "--header",
        "Authorization:${WAAFIR_AUTH}"
      ],
      "env": {
        "WAAFIR_AUTH": "Bearer YOUR_WAAFIR_PAT"
      }
    }
  }
}

Authorization:${WAAFIR_AUTH} 인수에 공백이 없도록 한 다음 Claude Desktop을 다시 시작하세요.

Cursor 및 URL과 헤더를 받는 기타 클라이언트.

{
  "mcpServers": {
    "waafir": {
      "url": "https://app.waafir.io/api/mcp/waafir",
      "headers": {
        "Authorization": "Bearer YOUR_WAAFIR_PAT"
      }
    }
  }
}

영역 서버도 같은 방식으로 추가하며, 항목 키와 URL만 바꾸면 됩니다.

도구 호출

연결되면 클라이언트가 서버의 도구 목록을 가져오고(MCP tools/list) 사용자를 대신해 도구를 호출합니다. 도구를 직접 호출할 필요는 없습니다. AI 클라이언트에 작업을 요청하면("이 데이터룸의 파일 목록을 보여 줘", "이 단락을 프랑스어로 번역해 줘") 클라이언트가 알맞은 도구를 선택해 호출하고, 각 서버 참조 문서에 설명된 인수를 전달합니다. 도구 사양은 waafir-redact, waafir-translate, waafir-dataroom, waafir-esign 참조를 확인하세요.

문제가 발생했을 때

실패는 두 개의 서로 다른 계층에서 발생하며, 그 모습도 다릅니다. 이를 잘못 이해하는 것이 여기서 가장 흔한 통합 실수입니다. HTTP 상태로만 분기하는 클라이언트는 두 번째 유형의 실패를 모두 조용히 놓치게 됩니다.

계층 1 — 도구가 실행되기 전에 요청이 거부됨

이는 JSON-RPC 형식의 오류 본문을 가진 실제 HTTP 오류 상태입니다. 요청이 도구에 전혀 도달하지 않았다는 뜻입니다.

  • 404 — 알 수 없는 MCP 서버. URL의 서버 이름 세그먼트가 waafir, waafir-redact, waafir-translate, waafir-dataroom, waafir-esign 중 하나가 아닙니다. 대부분 오타이거나 서버 이름 없이 /api/mcp만 사용한 경우입니다. URL을 수정하세요.

  • 402 — 추가 기능 미구매. 해당 서버는 유료 서비스(현재는 waafir-esign)인데 조직이 추가 기능도 활성 구독도 보유하고 있지 않습니다. 조직 관리자는 결제 설정에서 추가 기능이나 플랜을 구매할 수 있습니다. 이용 자격이 없는 조직은 서버의 도구를 목록으로 조회하는 것조차 할 수 없습니다. waafir는 402로 응답하지 않습니다. 대신 유료 도구를 숨기며, 그런 도구를 호출하면 계층 2에서 QUOTA_EXCEEDED로 거부되고 해당 도구를 명시한 메시지가 반환되는데, 이 메시지에는 ADDON_NOT_PURCHASED도 포함됩니다.

  • 401 — 인증되지 않음. 자격 증명이 없거나, 형식이 잘못되었거나, 취소되었거나, 만료되었습니다. 연결의 경우 어시스턴트에서 다시 로그인하세요. 대부분의 어시스턴트는 401을 받으면 자동으로 이 작업을 수행하며, 취소되었거나 30일 동안 사용하지 않은 연결은 새로 로그인해야 합니다. 토큰의 경우 Authorization 헤더가 있는지, 그리고 토큰이 추가 기능 → 설정 → API 토큰에서 여전히 활성 상태인지 확인하세요. 토큰이 취소되었거나 만료되었다면 새 토큰을 발급하세요. 이 동작 이전의 배포 환경은 토큰이 없거나 형식이 잘못된 경우 대신 403 CSRF validation failed: missing Origin 오류로 응답합니다. 이 인터페이스에서는 이것 역시 토큰이 없거나 형식이 잘못되었다는 뜻입니다.

  • 403 — 금지됨. 자격 증명이 입구에서 거부되었습니다. 연결이나 PAT 대신 로그인된 브라우저 세션이 사용되었거나(이 인터페이스에서는 세션을 허용하지 않음), 조직이 IP 허용 목록을 적용하고 있는데 요청이 그 목록 밖의 주소에서 왔습니다.

  • 429 — 요청이 너무 많음. MCP 속도 제한에 도달했습니다. 여기서는 어떤 제한도 IP 주소나 조직을 기준으로 하지 않습니다. 한도는 토큰에 속하므로, 같은 조직의 동료나 같은 네트워크에 있는 두 번째 클라이언트가 이를 소모하지 않습니다. 한도는 토큰당 분당 60개 요청입니다. 토큰을 조회하기 전에 집계되므로 형식이 잘못되었거나 취소되었거나 만료된 토큰도 한도를 소모하며, 같은 토큰이 MCP 외부에서 Waafir API를 호출한 것도 같은 60개에 포함됩니다. 로그인한 연결의 60개는 연결 단위로도 집계되므로, 어시스턴트가 로그인을 갱신할 때 받는 새 토큰으로 60개가 새로 시작되지 않습니다.

    응답에는 Retry-After 헤더가 없고 구별할 수 있는 코드도 없습니다(이 인터페이스의 모든 429는 똑같아 보입니다). 따라서 계속 재시도하지 말고 자체 일정에 따라 백오프하세요. 토큰 하나로 여유가 부족하다면 두 번째 토큰을 발급하세요. 한도는 토큰 단위입니다.

계층 2 — 도구가 실행되었고 거부함

대부분의 거부는 이 계층에서 발생하며, 이는 HTTP 오류가 아닙니다. HTTP 응답은 200이고 JSON-RPC 엔벨로프는 성공 엔벨로프입니다. 실패는 도구 결과 안에 담겨 전달되며, 이 결과는 isError: true로 설정되고 텍스트 콘텐츠는 다음과 같습니다.

{ "error": { "code": "CONFLICT", "message": "…" } }

error.code로 분기하세요. 코드는 다음과 같습니다.

코드의미
INVALID_ARGUMENT인수가 없거나, 형식이 잘못되었거나, 유효한 id가 아님 — 수정 후 재시도
FORBIDDEN토큰은 유효하지만 이 호출이 허용되지 않음
NOT_FOUND해당 레코드가 없거나 본인의 것이 아님
CONFLICT이해되었고 허용되었지만, 데이터룸이 이를 수행할 수 있는 상태가 아님
TOO_LARGE입력이 크기 제한을 초과함 — 나누어 보내기
QUOTA_EXCEEDED계량 한도를 모두 사용함 — 누군가 구매하거나 업그레이드해야 함
UPSTREAM_ERROR / UNAVAILABLE일시적인 다운스트림 장애 — 나중에 재시도
INTERNAL예기치 않은 장애 — 재시도하지 말고 에스컬레이션

이 중 두 가지는 사람들이 자주 헷갈립니다.

  • 범위가 너무 낮을 때의 FORBIDDEN. read 연결이나 토큰에는 쓰기 도구가 표시되지 않지만, 그래도 이를 호출하는 클라이언트는 도구에 의해 거부되므로 HTTP 403이 아니라 페이로드 안의 FORBIDDEN으로 여기에 도착합니다. 특정 데이터룸으로 제한된 토큰이 허용 목록 밖의 데이터룸을 dataroom_id로 지정한 경우도 마찬가지입니다. 파일이나 폴더 id를 받는 대부분의 도구는 그런 데이터룸에 있는 항목에 대해 존재하지 않는 id와 정확히 같게 NOT_FOUND로 응답합니다. 어시스턴트에서 다시 로그인하여 올바른 범위나 데이터룸을 부여하거나, 올바른 범위를 가진 토큰을 발급하세요.
  • CONFLICT. 호출은 이해되었고 허용되었지만, 데이터룸이 이를 수행할 수 있는 상태가 아닙니다. 예를 들어 폴더 이름이 이미 사용 중이거나, 파일 이름을 그 후 다른 활성 파일이 차지했거나, 복원하려는 항목의 컨테이너가 아직 삭제된 상태이거나 업로드가 완료되지 않은 경우입니다. CONFLICT는 권한 부여 문제가 아니므로 다시 로그인하거나 토큰을 재발급해도 도움이 되지 않습니다. 차단하는 레코드가 있으면 메시지에 해당 레코드가 표시되므로, 이를 처리한 후 재시도할 수 있습니다. 각 도구가 반환할 수 있는 충돌은 waafir-dataroom 참조에 나와 있습니다.

아직 검사 중인 파일. Waafir는 새로 업로드된 모든 파일과 모든 새 버전을 콘텐츠를 제공하기 전에 검사합니다. 그때까지 파일의 콘텐츠를 읽는 도구는 error.reason: "ACTIVATION_PENDING" 및 메시지 This file is still being checked. Try again shortly.와 함께 UNAVAILABLE을 반환합니다. 이는 일시적이므로 잠시 기다린 후 다시 호출하세요.

어느 계층에서든 명확한 거부는 Waafir가 처리하지 않을 호출에 대한 예상된, 안전한 결과입니다. 요청한 것보다 적은 작업을 조용히 수행하는 대신 요청을 실패시킵니다.