Google Developer Knowledge는 프로젝트·인증 설정 후 공식 개발자 문서를 검색·회수·인용합니다.
이 글은 2026년 10월 10일 기준 Google 공식 Developer Knowledge 릴리스 노트와 API·MCP 문서를 대조한 뒤, 계정·프로젝트·API 키 없이 검색 결과를 근거 목록으로 바꾸는 자체 로컬 실습을 수행한 기록입니다. 직접 확인한 것은 로컬 fixture의 상태 변화와 파일 증거이며, Google Developer Knowledge API나 원격 MCP 서버의 실제 응답은 확인하지 않았습니다. 이 구분을 먼저 적는 이유는 문서에 나온 명령 예시와 실제 계정에서 받은 응답을 섞으면 재현성과 책임 범위가 흐려지기 때문입니다.
Developer Knowledge가 해결하는 문서 검색 문제
개발자가 AI 도구에 “Cloud Functions 배포 인증은 어디서 확인하나?”라고 묻는 상황을 생각해 보겠습니다. 일반 웹 검색은 검색 결과 제목과 본문 일부를 돌려주지만, 답변에 공식 문서를 인용하려면 어떤 문서가 선택됐는지, 그 문서의 리소스 이름이 무엇인지, 실제 인용 문장이 어디에서 왔는지를 별도로 보존해야 합니다. Developer Knowledge API는 Google의 공개 개발자 문서를 대상으로 검색 chunk를 찾고, 검색 결과의 parent를 사용해 문서 전체를 회수하는 흐름을 문서화합니다.
공식 API 문서는 `SearchDocumentChunks`가 검색어에 맞는 문서 조각과 parent 참조를 반환한다고 설명합니다. 그 parent는 후속 `GetDocument` 또는 `BatchGetDocuments`에서 사용할 리소스 이름입니다. 따라서 검색 결과를 곧바로 최종 답변으로 취급하지 않고, 검색 → 문서 회수 → 문장 인용이라는 세 단계를 로그에 남기는 것이 안전합니다. 검색 chunk의 짧은 문장만으로 권한·버전·예외 조건까지 단정해서는 안 됩니다.
2026년 9월 22일 릴리스 노트에는 `gcloud developer-knowledge` 명령이 GA가 됐고, `answer-query`, `documents describe`, `documents search-chunks` 세 명령을 사용할 수 있다고 적혀 있습니다. 이 사실은 CLI 경로가 공개됐다는 의미이지, 현재 컴퓨터에 gcloud가 설치되어 있거나 계정이 인증됐다는 뜻은 아닙니다. 이번 실행에서는 그 명령을 호출하지 않고, 공식 문서에 나온 출력 관계만 안전한 로컬 입력으로 옮겼습니다.
API·CLI·MCP 중 무엇을 고를까
| 경로 | 적합한 경우 | 먼저 확인할 경계 |
|---|---|---|
| REST API·클라이언트 라이브러리 | 검색 결과를 애플리케이션에서 가공하거나 필터링할 때 | API 활성화, API key·ADC, quota, 공개 corpus 범위 |
| gcloud CLI | 터미널에서 검색·문서 조회·답변 생성을 조합할 때 | gcloud 설치, 로그인한 계정, 프로젝트와 서비스 활성화 |
| MCP 서버 | AI 코딩 도구에 검색·문서 회수·답변 도구를 연결할 때 | 원격 endpoint, API key 또는 OAuth/ADC, 호스트의 MCP 지원 |
Google의 API 개요는 API·클라이언트 라이브러리·gcloud를 사용하면 결과를 모델에 넘기기 전에 직접 처리하거나 `data_source`, `update_time` 같은 메타데이터 필터와 field mask를 적용할 수 있다고 설명합니다. 반대로 MCP 서버는 별도 도구 정의를 작성하지 않고 AI 코딩 도구에 문서 검색을 연결하고 싶을 때 맞습니다. 필터가 필요하지만 MCP 호출만으로 해결하려고 하면, 원하는 문서 범위를 좁히지 못한 채 답변만 받아들이는 문제가 생길 수 있습니다.
MCP 문서는 `search_documents`, `get_documents`, `answer_query`를 핵심 도구로 소개합니다. `search_documents`의 짧은 결과만으로 충분하지 않으면 문서 이름을 `get_documents`에 넘겨 전체 Markdown 맥락을 읽고, 자연어 답변이 필요할 때만 `answer_query`를 선택하는 순서가 명확합니다. 도구 이름이 보인다고 해서 연결이 성공한 것은 아닙니다. HTTP 404는 API가 프로젝트에서 활성화되지 않은 경우, 401은 인증 누락 또는 잘못된 키, 429는 quota 초과와 연결될 수 있으므로 응답 상태와 오류 원인을 함께 기록해야 합니다.
인증과 공개 범위를 먼저 고정하기
Developer Knowledge API를 쓰려면 먼저 Google Cloud 프로젝트에서 API를 활성화해야 합니다. 공식 문서에는 REST 요청과 MCP에 API key를 사용할 수 있고, 클라이언트 라이브러리·운영 흐름에는 ADC·OAuth 2.0·서비스 계정을 사용할 수 있다고 적혀 있습니다. API key를 쓰는 경우에도 Developer Knowledge API로 제한하는 설정이 필요합니다. 이 과정은 비밀값을 문서나 캡처에 남기지 않는 별도의 운영 절차이며, 이번 로컬 실습에서는 어떤 키도 만들거나 읽지 않았습니다.
MCP 연결 문서는 원격 endpoint가 `https://developerknowledge.googleapis.com/mcp`라고 설명하면서 API key는 `X-Goog-Api-Key` 헤더로 전달하는 방식을 안내합니다. OAuth·ADC를 쓰는 환경에서는 quota project와 권한이 추가로 필요할 수 있습니다. 따라서 “MCP는 로그인 없이 된다”는 설명은 틀립니다. 공개 문서 corpus를 읽는 서비스라도 호출 주체·프로젝트·quota·네트워크가 확인돼야 실제 실행 증거가 됩니다.
공개 범위도 별도 항목입니다. MCP 문서는 공개적으로 이용 가능한 신뢰된 Google 문서만 corpus에 포함하고, 내부 문서·비공개 저장소·제3자 자료는 대상이 아니라고 설명합니다. 또한 문서에는 영어 중심의 범위와 원격 네트워크 의존성이 명시되어 있습니다. 한국어 질문을 입력해도 반환되는 자료의 언어와 원문 URL을 확인해야 하며, 검색 결과가 없다는 이유만으로 문서가 존재하지 않는다고 결론 내리면 안 됩니다.
직접 실행 결과: 계정 없는 로컬 검색 흐름
실제 Google 서비스에 접근하지 않고, 공식 문서가 설명하는 데이터 흐름만 검증하기 위해 고정된 브라우저 fixture를 작성했습니다. 시작 화면에는 질문, 세 개의 문서 후보, “문서 chunk 검색” 모드, `parent → 문서 URI → 인용 문장` 검증 조건이 표시됩니다. 실행 버튼을 누르면 결과 화면이 같은 세션에서 바뀌고, 검색 chunk 3개, 회수 문서 2개, 인용 준비 URL 2개와 발췌 3개가 나타납니다.
2026년 10월 10일 Windows 독립 Chromium 1200×675 viewport에서 이 버튼을 직접 실행했습니다. 네트워크 요청, Google Cloud 프로젝트, API key, OAuth, MCP 연결, 실제 문서 다운로드는 발생하지 않았습니다. 관찰 결과는 순수 JavaScript로 고정 입력을 분류한 로컬 모형이며, Developer Knowledge API의 검색 품질이나 `answer_query`의 실제 응답을 재현한 수치가 아닙니다. `capture_browser_evidence.cjs`로 같은 세션의 WebP 시작·결과 화면과 시작→결과 프레임 변화를 포함한 WebM을 저장하고 재생·SHA-256을 다시 확인했습니다.
검색 결과를 인용 가능한 기록으로 바꾸는 순서
첫째, 질문을 한 문장으로 고정합니다. “문서가 있나?”처럼 넓은 질문보다 “Cloud Functions 배포 인증을 공식 문서에서 어디서 확인하나?”처럼 제품과 목적을 함께 써야 결과를 비교하기 쉽습니다. query, 언어, 필터, page size, 실행 시각을 기록하면 다음 실행에서 같은 조건을 재현할 수 있습니다.
둘째, 검색과 회수를 분리합니다. `searchDocumentChunks` 또는 MCP의 `search_documents`가 반환한 parent·name·uri를 먼저 저장하고, 실제로 인용할 문서만 `documents.get`, `batchGet`, 또는 `get_documents`로 회수합니다. 전체 문서가 클 때는 basic view나 field mask로 제목·URI·업데이트 시각만 먼저 읽고, 필요한 문서만 content view로 가져오는 방식이 비용과 노이즈를 줄입니다.
셋째, 답변과 근거를 나눕니다. `answer_query`는 문서 corpus에서 자연어 답변을 만드는 도구이지만, 답변이 맞아 보인다는 사실만으로 인용이 검증된 것은 아닙니다. 답변에 포함된 references·citations 또는 회수 문서의 URI와 실제 문단을 대조하고, 지원되지 않는 주장·오래된 페이지·다른 제품의 문장이 섞이지 않았는지 확인해야 합니다. 최종 글에는 질문, 기준일, 공식 URL, 직접 관찰 범위를 함께 남기는 것이 좋습니다.
넷째, 실패를 정상 경로로 모델링합니다. 401이면 키나 인증 구성을 확인하고, 403이면 API 활성화·권한·API restriction을 확인하며, 404이면 문서 리소스 이름과 corpus 포함 여부를 확인합니다. 429는 quota 문제일 수 있으므로 무한 재시도하지 않습니다. MCP 도구가 없거나 원격 연결이 불가능할 때 REST API로 폴백하라는 공식 skill 안내도 있지만, 폴백 역시 같은 인증·quota·공개 범위를 가집니다.
한계와 실패 조건
이번 결과는 Google Developer Knowledge API의 실제 검색 응답이나 MCP 서버의 실제 세션을 사용한 결과가 아닙니다. 로컬 fixture의 세 문서 후보와 고정된 결과 카드를 브라우저에서 계산했을 뿐이며, “검색 chunk 3개”와 “회수 문서 2개”를 Google 서비스의 품질·정확도·비용 수치로 해석할 수 없습니다. 실제 프로젝트의 corpus, 언어, quota, 모델 응답은 별도 환경에서 다시 확인해야 합니다.
다음 조건이면 결과를 제품 실행 성공으로 기록하지 않습니다. API가 활성화됐는지 확인하지 않았을 때, API key·ADC·OAuth 주체가 불명확할 때, MCP endpoint는 보였지만 도구 호출의 저장된 응답을 읽지 못했을 때, parent와 문서 URI가 끊겼을 때, 답변만 있고 원문 인용이 없을 때, 오류 응답을 빈 검색 결과로 처리했을 때입니다. 특히 계정 없는 로컬 fixture를 실제 Google 문서 검색 결과처럼 캡처하거나, 공식 문서의 명령 예시를 직접 실행했다고 쓰는 것은 금지합니다.
검증 체크리스트
- 질문·필터·page size·기준일을 고정했는가?
- 검색 결과의 parent/name/URI를 회수 단계까지 보존했는가?
- 검색 chunk와 전체 문서 회수를 같은 결과로 혼동하지 않았는가?
- API key·ADC·OAuth·quota project의 책임 주체가 명확한가?
- 401·403·404·429를 빈 결과와 구분했는가?
- 답변 문장마다 공식 URL과 실제 원문을 대조했는가?
- 로컬 fixture 결과를 Google 제품 실행 결과로 과장하지 않았는가?
외부 상태를 바꾸기 전에 stage-only 실행과 사람 승인을 분리하는 방법은 이 사이트의 npm stage-only 토큰과 사람 승인 경계 점검 글에서 확인할 수 있습니다. 이 내부 링크는 Google 서비스의 결과가 아니라 외부 변경 전에 검토 경계를 고정한다는 운영 원칙을 연결합니다.
공식 출처와 검증일
공식 사실은 2026년 10월 10일 Google Developer Knowledge 릴리스 노트, API 개요, 문서 검색 가이드, MCP 연결 문서를 대조했습니다. 릴리스 노트는 2026년 9월 22일 gcloud 명령의 GA와 10월 8일 클라이언트 라이브러리 제공을 기록합니다. API 가이드는 검색 chunk·parent·문서 회수·페이지네이션·필터·문서 view를 설명하고, MCP 문서는 세 도구와 인증 방식·공개 corpus·오류 경계를 설명합니다. 직접 증거는 이 공식 내용을 바탕으로 만든 계정 없는 로컬 검색 흐름의 동작만을 보여 줍니다.