접근 통제
Powerduck은 독자가 문서에 접근하는 방식과 클라이언트가 MCP 엔드포인트에 접근하는 방식을 분리합니다. 소비 방식이 다르기 때문입니다. 또한 MCP 서버가 상류 API에 어떻게 인증하는지 구성합니다.
각 관문(순서)
공개 면이 열리는지를 결정하는 조건은 여러 개입니다. 전체 목록을 알면 흔한 "왜 문서를 열 수 없지?"에 답할 수 있습니다.
- 문서 상태——
ACTIVE(일시정지, 보관, 삭제 아님)여야 함. - 모드 활성——문서는
documentationEnabled, MCP는mcpEnabled. - 접근 자격 증명——구성 시 문서는 보기 비밀번호, MCP는 접근 키.
- 유효 기간——문서 보기는 지정 시각에 만료 가능.
모드 뒷단의 게시된 결과물은 버전 추가나 노출 변경 후 자동 구축돼 게시가 보통 수동 조작이 아닙니다.
각 모드는 독립적입니다. MCP를 비활성화해도 문서에 영향 없고 문서 비밀번호가 MCP를 보호하지 않습니다.
문서 보기 비밀번호
보기 비밀번호는 렌더링 문서와 제공되는 스펙 데이터를 보호합니다.
- 비밀번호는 비밀번호별 무작위 솔트로 scrypt 해시. 평문 저장 안 함.
- 설정 후 독자는 문서 제공 전 입력해야 함.
- 비밀번호는 문서 전용. MCP 엔드포인트는 자체 접근 키를 쓰고 보기 비밀번호를 건너뜀.
보기 유효 기간도 설정 가능. 만료 후 올바른 비밀번호여도 거부됩니다. 비밀번호나 기간을 지우면 제한이 해제됩니다.
MCP 엔드포인트 접근 키
MCP 엔드포인트는 자체 접근 키로 보호됩니다.
- 키 생성(또는 교체). 전체 키는 한 번만 반환되고 이후 마지막 네 글자만 표시.
- 구성 후 모든 MCP 요청은
Bearer토큰으로 제시해야 함. - 제공 키는 상수 시간 비교되고 누락/오류는
401.
키를 삭제하면 문서가 활성이고 MCP 활성인 경우 MCP 엔드포인트가 개방됩니다.
MCP 상류 인증
엔드포인트 보호 외에 MCP 서버가 스펙이 기술하는 상류 API에 어떻게 인증하는지 구성할 수 있습니다. 지원 인증 유형:
authType | 구성 |
|---|---|
NONE | 상류 인증 없음 |
BEARER | Bearer 토큰 |
BASIC | Basic 사용자 이름과 비밀번호 |
APIKEY | API 키 이름(헤더/쿼리)과 값 |
Bearer 토큰, Basic 비밀번호, API 키 값 등 기밀은 쓸 수 있지만 읽히지 않고 구성은 설정 여부만 보 고합니다.
다른 MCP 구성:
- 베이스 URL 재정의——스펙 대신 상류 베이스 URL 덮어쓰기.
- 요청 시간 초과——MCP 서버가 상류 API 호출 시 사용하는 시간 초과.
권장 설정
- 공개 문서: 문서 활성. 개방 API는 비밀번호 없이, 또는 통제 공유를 위해 비밀번호와 기간 설정.
- 자신의 에이전트용 MCP: MCP 활성화와 접근 키 생성으로 자신의 클라이언트만 호출 가능.
- 상류 인증: MCP 서버 인증을 실제 API 요구에 맞추고 누가 MCP 엔드포인트를 호출할 수 있는지와 독립적으로 유지.
관련: 노출 작업、문서와 버전、사용자 지정 도메인.