FAQ
자주 묻는 질문
연결
claude.ai 웹에서 커넥터로 추가할 수 있나요?
현재는 불가합니다. claude.ai 커스텀 커넥터는 OAuth만 지원하고 커스텀 헤더를 보낼 수 없습니다. Goono MCP 서버는 X-Goono-Key 헤더 인증만 제공합니다.
Claude Desktop에서 왜 mcp-remote가 필요한가요?
Claude Desktop은 원격 HTTP 서버에 커스텀 헤더를 직접 붙이지 못합니다. mcp-remote가 로컬 stdio 서버처럼 동작하면서 헤더를 붙여 중계합니다. 클라이언트 등록의 Claude Desktop 탭을 참고하세요.
워크스페이스가 여러 개면?
키는 워크스페이스 + 사용자 단위라, 워크스페이스마다 키를 발급해 서버를 따로 등록합니다(예: goono-lab-a, goono-lab-b).
401이 계속 납니다.
헤더 이름이 X-Goono-Key인지, 키가 gno_live_ 또는 gno_test_로 시작하는지, 만료·폐기되지 않았는지 순서로 확인하세요. 서버는 헤더 존재와 접두사만 검사하고 유효성 판정은 Goono 백엔드가 합니다.
도구
노트 내용을 읽으려면?
get_note_file이 유일한 경로입니다. OCR 텍스트는 노출되지 않습니다.
512KB를 넘는 파일은? 내용을 읽을 방법이 없습니다. 도구는 에러 대신 크기만 담은 결과를 돌려주고 LLM이 "N바이트라 읽을 수 없다"고 답합니다. 크기는 저장된 암호문 기준입니다.
태그로 필터했는데 결과가 비어 있어요.
태그 목록 API가 없어 LLM이 추측한 값을 넣었을 수 있습니다. list_notes 결과의 tags에서 정확한 값을 골라 다시 필터합니다. 태그 필터는 부분일치입니다.
목록에서 본 노트가 404로 나옵니다.
노트는 Goono 화면이나 다른 도구로 다른 폴더·프로젝트로 옮겨질 수 있습니다. 옮겨져도 noteId는 같지만 projectId·folderId가 바뀝니다. search로 현재 위치를 다시 찾으세요.
폴더 삭제가 409로 거부됩니다.
빈 폴더만 지울 수 있습니다. 안의 노트를 move_note로 먼저 옮기고 GitHub 저장소 연동이 있으면 해제한 뒤 다시 시도합니다.
LLM이 쓰기 작업 전에 계속 확인을 요청합니다. 의도된 동작입니다. 폴더 쓰기와 노트 이동은 사용자에게 보이는 상태를 바꾸므로, 서버 instructions와 도구 description이 "계획을 먼저 제시하고 승인받은 뒤 호출"을 요구합니다.
운영
Rate limit에 자주 걸립니다.
대부분 content 버킷(분당 60회)입니다. 파일을 병렬로 읽지 말고 필요한 것만 순차로 읽으세요. Rate limit에 다른 요령이 있습니다.
응답에 모르는 필드가 있습니다. MCP 서버는 Goono 백엔드 JSON을 가공 없이 전달합니다. 백엔드가 하위호환으로 필드·열거형 값을 추가할 수 있으니 모르는 값은 무시하세요.
로컬에서 서버를 직접 띄울 수 있나요?
npm 패키지는 배포되지 않습니다. 저장소를 받아 pnpm install && pnpm dev로 띄우고(http://localhost:3000/mcp) 백엔드 없이 데모만 보려면 GOONO_MOCK=1 pnpm dev로 예시 데이터 모드를 씁니다.