MCP로 문서를 질의 가능한 에이전트 인터페이스로 설계하는 법

문서를 에이전트가 전문 스크래핑으로 읽게 하면 컨텍스트를 크게 소모할 뿐 아니라, 여러 버전이 섞인 문단 가운데 오래된 내용을 현재 사양처럼 근거로 삼을 수 있다. 문서 페이지를 MCP 서버로 감싸 도구 호출 대상으로 만드는 흐름은 이 문제를 문서 인터페이스의 문제로 다룬다.

같은 시기 x64dbg-MCP Server처럼 기존 도구를 MCP로 노출하는 사례도 커뮤니티에 등장했다. 문서는 더 이상 사람만 읽는 참조 자료가 아니라, 에이전트가 필요한 근거를 요청하는 기계 인터페이스가 되고 있다.

문서가 반환해야 할 것은 페이지가 아니라 답변 조각이다

문서 조각은 개념 설명, 절차, 인자 표, 예제처럼 하나의 질문에 답할 수 있는 단위로 나눈다. 페이지 전체에는 여러 주제가 함께 들어가는 경우가 많으므로, 페이지 단위 반환은 관련 없는 내용까지 응답에 포함시킨다.

도구에는 검색어만 넣지 말고 제품 버전, 조각 유형, 최대 반환 수를 인자로 노출한다. 자유 문자열 하나로 질의를 받으면 모델이 의도를 표현할 자리가 부족해지고, 결과적으로 요청 자체가 뭉개질 수 있다.

버전이 중요한 문서라면 요청한 버전에 해당하는 조각만 반환해야 한다. 버전이 지정되지 않았을 때는 어떤 기본 버전을 사용했는지 알려야 하며, 서로 다른 버전의 조각을 한 응답에 섞지 않는다. 여러 문단이 함께 오면 에이전트가 임의의 문단을 선택할 수 있기 때문이다.

응답에는 조각 수와 총 길이의 상한이 필요하다. 상한을 넘는다면 요약과 링크로 대신해 한 번의 도구 호출이 컨텍스트를 소진하지 않도록 한다. 모든 조각에는 원문 링크와 갱신 시각도 붙인다. 이 정보가 없으면 사람이 답변을 검증하기 어렵고, 에이전트도 인용을 만들어낼 여지가 생긴다.

⤢✕

색인과 권한 경계까지 함께 운영한다

색인 갱신은 주기적인 크롤링에만 맡기지 않고 문서 배포 파이프라인에 연결한다. 문서가 배포된 즉시 색인이 반영되어야 하며, 갱신 지연은 곧 오답이 지속되는 기간이 된다.

비공개 문서는 호출자 자격에 따라 반환 범위를 제한한다. 공개 색인과 비공개 색인을 하나로 합치면 필터 실수 하나가 유출로 이어질 수 있으므로 분리해 두는 편이 안전하다.

질의 로그는 운영 로그에 그치지 않는다. 어떤 요청이 답을 찾지 못했는지 집계하면 문서에서 비어 있는 부분을 확인할 수 있다. 무응답과 부정확 응답을 나눠 기록하고, 원인을 문서 공백과 색인 문제로 구분해야 다음 조치의 대상을 판단할 수 있다.

노출 범위를 넓히기 전에 검증할 항목

처음부터 전체 문서를 열기보다 에이전트 질의 빈도가 높은 API 레퍼런스와 설정 문서부터 대상으로 삼는다. 조각 규칙을 확인하지 않은 상태에서 범위만 키우면 정확도가 떨어질 수 있다.

문서 유형별로 분할 기준과 조각 최소·최대 길이를 정하고, 문단 경계와 의미 경계가 어긋나는 문서는 먼저 구조를 정리한다. 검색, 조회, 목록화처럼 도구를 목적에 따라 나누는 것도 필요하다. 도구 설명이 모호하면 모델이 잘못된 도구를 선택한다.

변경 사항이 색인에 도달하는 경로와 지연 시간을 확인하고, 지연 상한을 넘을 때 경보를 내도록 한다. 실패 질의 상위 항목은 정기적인 문서 개선 과제로 편성하며, 개선 뒤에는 같은 질의가 성공하는지 회귀 절차로 확인한다. 비공개 문서의 노출 범위 변경은 승인 대상으로 두고, 질의량·실패율·갱신 지연을 정기 보고 항목으로 관리한다.

전문 스크래핑과 도구 노출이 갈리는 지점

구분	MCP 도구 노출	전문 스크래핑
답변 정확도	높음	중간
컨텍스트 소모	적음	많음
버전 구분	가능	어려움
접근 통제	가능	없음
구축 비용	큼	없음
질의 관측	가능	불가

도구 노출은 질문에 맞는 조각만 반환하므로 컨텍스트를 아끼고, 버전 구분으로 오래된 문단의 오인용을 줄일 수 있다. 호출자 자격에 따른 비공개 문서 통제와 질의 로그 기반의 문서 공백 분석도 가능하다. 반면 서버 구축과 색인 유지 비용이 들며, 조각 분할이 부정확하면 문맥이 끊겨 답변 품질이 오히려 나빠질 수 있다.

전문 스크래핑은 별도 구축 없이 문서 전체를 바로 적용할 수 있고 문맥이 보존된다. 그러나 페이지 전체가 컨텍스트를 크게 차지하며, 여러 버전이 섞인 문단은 오답을 유발할 수 있다. 비공개 영역을 구분하기도 어렵고, 어떤 질의가 실패했는지 관측할 수 없다.

질의가 반복되고 여러 버전이 존재하는 제품 문서라면 도구 노출의 이득이 구축 비용을 넘어선다. 문단 단위로 반환하되 상위 절 제목과 인접 조각 링크를 함께 제공하면, 정밀도와 문맥 손실을 함께 다룰 수 있다. 공개 문서는 검색 색인에 위임하고 비공개·버전 민감 문서만 자체 운영하는 구성도 통제와 비용 사이의 절충점이 된다.

문서 관리 체계로 보는 MCP 인터페이스

조각 단위 구조화와 질의 로그 기반의 문서 공백 분석은 지식 자산을 재사용하고 보완하는 활동이다. 도구 인자 스키마와 응답 규격은 인터페이스 명세와 계약 관리의 대상이 된다.

배포 파이프라인과 색인 갱신의 연결은 연계 자동화와 정합성 유지 설계에 해당한다. 버전별 응답 분기와 갱신 시각 표기는 문서 버전 통제와 유효성 관리 요건이며, 비공개 문서의 접근 통제는 문서 등급에 따른 배포 제한 조치로 볼 수 있다.

제품 문서와 함께 MCP 엔드포인트를 제공하는 방식, 질의 로그를 문서 품질 지표의 1차 데이터로 쓰는 방식, 조각 분할과 출처 반환 규격이 수렴하는 흐름이 이어지고 있다. 에이전트 유입이 문서 트래픽에서 차지하는 비중이 커질수록 문서 작성 기준은 사람의 독해뿐 아니라 기계 소비까지 함께 고려하게 된다.