Docs는 AI 에이전트가 Docs 데이터와 안전하게 상호작용할 수 있는 원격 모델 컨텍스트 프로토콜(MCP) 서버를 제공합니다. Docs MCP 서버를 구성하면 Google Antigravity 및 Claude와 같은 AI 애플리케이션이 Docs에서 작업을 수행할 수 있습니다.
Docs MCP 서버는 AI 에이전트가 다음 작업을 수행할 수 있는 표준화된 방법을 제공합니다.
- 데이터 읽기: 문서 구조 정보 및 텍스트 콘텐츠를 읽습니다.
- 조치 취하기: 일괄 업데이트를 사용하여 문서 스타일과 구조를 업데이트합니다.
- 보안 준수: 사용자와 동일한 권한 및 데이터 거버넌스 제어를 상속합니다.
기본 요건
Google Cloud 프로젝트 프로젝트를 만들려면 프로젝트 만들기를 참조하세요.
Google Antigravity 또는 Claude와 같은 AI 애플리케이션인 MCP 호스트 AI 애플리케이션은 각 MCP 서버에 대해 MCP 클라이언트 연결을 만듭니다.
이 페이지에서 명령어를 실행하려면 다음 개발 환경 중 하나에서 gcloud CLI를 설정하세요.
Cloud Shell
gcloud CLI로 이미 설정된 온라인 터미널을 사용하려면 Cloud Shell을 활성화하세요.
로컬 셸
로컬 개발 환경을 사용하려면 다음 단계를 수행합니다.
- Google Cloud CLI를 설치합니다.
이전에 gcloud CLI를 설치한 경우
gcloud components update를 실행하여 최신 버전이 설치되어 있는지 확인합니다. - 외부 ID 공급업체(IdP)를 사용하는 경우 제휴 ID로 gcloud CLI에 로그인합니다. 자세한 내용은 제휴 ID로 gcloud CLI에 로그인을 참조하세요.
- gcloud CLI를 초기화합니다.
- Google Cloud CLI를 설치합니다.
이전에 gcloud CLI를 설치한 경우
Docs MCP 서버 구성
Docs MCP 서버를 사용하려면 Google Cloud 프로젝트에서 사용 설정하고 연결하도록 AI 애플리케이션을 구성합니다.
API 사용 설정
Docs MCP 서버를 사용하려면 Google Cloud 프로젝트에서 다음 API를 사용 설정하세요.
Google Docs API
CLI
gcloud services enable docs.googleapis.com --project=PROJECT_ID
PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
콘솔
Google Cloud 콘솔에서 API를 사용 설정합니다.
MCP 서비스 사용 설정
Docs용 MCP 구성요소를 사용 설정하려면 Google Cloud 프로젝트에서 다음 서비스를 사용 설정합니다.
Docs MCP API
CLI
gcloud services enable docsmcp.googleapis.com --project=PROJECT_ID
PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
콘솔
Google Cloud 콘솔에서 MCP 서비스를 사용 설정합니다.
OAuth 동의 화면 설정
Docs MCP 서버는 인증 및 승인에 OAuth 2.0을 사용합니다. OAuth 클라이언트 ID를 만들려면 먼저 OAuth 동의 화면을 구성해야 합니다.
Google Cloud 콘솔에서 Google 인증 플랫폼 > 브랜딩으로 이동합니다.
이미 Google 인증 플랫폼을 구성한 경우 브랜딩, 대상, 데이터 액세스에서 다음 OAuth 동의 화면 설정을 구성할 수 있습니다. Google 인증 플랫폼이 아직 구성되지 않음이라는 메시지가 표시되면 시작하기를 클릭합니다.
- 앱 정보의 앱 이름에
Docs MCP Server를 입력합니다. - 사용자 지원 이메일에서 이메일 주소 또는 적절한 Google 그룹을 선택합니다.
- 다음을 클릭합니다.
- 대상에서 내부를 선택합니다. 내부를 선택할 수 없는 경우 외부를 선택합니다.
- 다음을 클릭합니다.
- 연락처 정보에서 프로젝트 변경사항에 대한 알림을 받을 수 있는 이메일 주소를 입력합니다.
- 다음을 클릭합니다.
- 완료에서 Google API 서비스 사용자 데이터 정책을 검토하고 동의하는 경우 Google API 서비스: 사용자 데이터 정책에 동의합니다를 선택합니다.
- 계속을 클릭합니다.
- 만들기를 클릭합니다.
- 사용자 유형으로 외부를 선택한 경우 테스트 사용자를 추가합니다.
- 잠재고객을 클릭합니다.
- 테스트 사용자에서 사용자 추가를 클릭합니다.
- 이메일 주소와 기타 승인된 테스트 사용자를 입력한 후 저장을 클릭합니다.
- 앱 정보의 앱 이름에
데이터 액세스 > 범위 추가 또는 삭제를 클릭합니다. Google Cloud 프로젝트에서 사용 설정한 각 API의 범위 목록이 포함된 패널이 표시됩니다.
직접 범위 추가에서 Docs MCP 서버의 범위를 붙여넣습니다.
https://www.googleapis.com/auth/drive.readonlyhttps://www.googleapis.com/auth/drive.filehttps://www.googleapis.com/auth/documents.readonlyhttps://www.googleapis.com/auth/documents
표에 추가를 클릭합니다.
업데이트를 클릭합니다.
앱에 필요한 범위를 선택한 후 데이터 액세스 페이지에서 저장을 클릭합니다.
AI 애플리케이션 구성
AI 애플리케이션에 Docs 원격 MCP 서버를 추가하려면 애플리케이션 안내를 따르세요.
Docs MCP 서버를 호출하는 사용자 위임 OAuth 2.0 클라이언트 ID는 Google 인증 플랫폼 > 클라이언트에서 AI 기반 에이전트에 이 클라이언트 사용을 선택해야 합니다. 기존 OAuth 2.0 클라이언트 ID를 업데이트하려면 OAuth 클라이언트 관리에 설명된 대로 Google Auth Platform > 클라이언트에서 이 설정을 선택합니다. 기존 클라이언트에서 이 설정을 변경할 수 없거나 클라이언트가 에이전트가 아닌 기능도 지원하는 경우 AI 에이전트의 새 OAuth 2.0 클라이언트 ID를 만듭니다. 거부된 요청, 도메인 전체 위임이 있는 서비스 계정 또는 Google Apps Script는 문제 해결을 참고하세요.
Antigravity
Docs 원격 MCP 서버를 Antigravity에 추가하려면 서버 구성을 mcp_config.json 파일에 추가합니다. 이 안내는 Antigravity 2.0, Antigravity IDE, Antigravity CLI를 지원합니다.
OAuth 2.0 클라이언트 ID 및 보안 비밀을 만듭니다.
Google Cloud 콘솔에서 Google 인증 플랫폼 > 클라이언트 > 클라이언트 만들기로 이동합니다.
애플리케이션 유형으로 웹 애플리케이션을 선택합니다.
이름을 입력합니다.
승인된 리디렉션 URI 섹션에서 + URI 추가를 클릭한 후 URI 필드에
https://antigravity.google/oauth-callback를 추가합니다.AI 기반 에이전트에 이 클라이언트 사용을 선택합니다.
만들기를 클릭하고 클라이언트 ID와 클라이언트 보안 비밀번호를 복사합니다.
구성 파일
~/.gemini/config/mcp_config.json을 열거나 만듭니다.mcpServers구성을mcp_config.json에 추가합니다.{ "mcpServers": { "docs": { "serverUrl": "https://docsmcp.googleapis.com/mcp/v1", "oauth": { "clientId": "OAUTH_CLIENT_ID", "clientSecret": "OAUTH_CLIENT_SECRET" } } } }다음을 바꿉니다.
OAUTH_CLIENT_ID: 생성한 클라이언트 ID입니다.OAUTH_CLIENT_SECRET: 생성한 클라이언트 보안 비밀번호입니다.
mcp_config.json할인을 받으세요.MCP 서버를 인증합니다. GUI 설정 또는 CLI를 사용하여 인증할 수 있습니다.
Antigravity IDE 또는 GUI(Antigravity 2.0)의 경우:
- 설정 화면을 엽니다(예: 왼쪽 하단에서 설정을 클릭하거나 Antigravity 사용자 설정을 엽니다).
- 사용자 정의로 이동하세요.
- 설치된 MCP 서버에서 새로고침을 클릭합니다.
- 목록에서
docs를 찾아 인증을 클릭하고 Google 계정에 로그인한 후 승인 코드를 복사하여 입력 대화상자에 붙여넣고 제출을 클릭합니다.
Antigravity CLI:
Antigravity CLI를 시작합니다.
agy다음 명령어를 실행하여 대화형 MCP 관리 패널을 엽니다.
/mcp화살표 키를 사용하여
docs를 선택하고 인증 작업으로 이동한 후 Enter를 누릅니다. 브라우저에서 로그인 과정을 완료하고 승인 코드를 복사하여 터미널 프롬프트에 붙여넣은 후 Enter를 누릅니다.
서버가 올바르게 구성되고 실행 중인지 확인합니다.
- Antigravity IDE 또는 GUI: Customizations(맞춤설정) > Installed MCP Servers(설치된 MCP 서버)에서 서버 옆에 Sign out(로그아웃) 버튼이 표시됩니다.
- Antigravity CLI:
/mcp패널을 열어 구성된 MCP 서버를 확인합니다. 확인 및 인증된 서버는 대화형 TUI 패널 내에서 이름 옆에 Authed를 표시합니다. 대시보드 뷰에서 서버를 선택하여 상태를 검사하고 사용 가능한 모든 도구를 나열할 수 있습니다.
이제 Antigravity에서 원격 MCP 서버를 사용할 수 있습니다.
Claude
Claude.ai 또는 Claude Desktop에서 Docs 원격 MCP 서버를 사용하려면 Claude Enterprise, Pro, Max 또는 Team 요금제가 있어야 합니다.
Docs 원격 MCP 서버를 Claude에 추가하려면 OAuth 클라이언트 ID와 보안 비밀번호를 사용하여 커스텀 커넥터를 구성합니다.
OAuth 2.0 클라이언트 ID 및 보안 비밀을 만듭니다.
Google Cloud 콘솔에서 Google 인증 플랫폼 > 클라이언트 > 클라이언트 만들기로 이동합니다.
애플리케이션 유형으로 웹 애플리케이션을 선택합니다.
이름을 입력합니다.
승인된 리디렉션 URI 섹션에서 + URI 추가를 클릭한 후 URI 필드에
https://claude.ai/api/mcp/auth_callback를 추가합니다.AI 기반 에이전트에 이 클라이언트 사용을 선택합니다.
만들기를 클릭하고 클라이언트 ID와 클라이언트 보안 비밀번호를 복사합니다.
Claude에서 MCP 서버를 구성합니다.
- Claude.ai 또는 Claude Desktop에서 설정 > 커넥터 또는 관리자 설정 > 커넥터로 이동합니다.
- 커스텀 커넥터 추가를 클릭합니다.
- Docs 제품의 연결 세부정보를 입력합니다.
- 서버 이름:
Docs. - 원격 MCP 서버 URL:
https://docsmcp.googleapis.com/mcp/v1
- 서버 이름:
- 고급 설정에서 OAuth 클라이언트 ID 및 OAuth 클라이언트 보안 비밀번호를 입력합니다.
- 추가를 클릭합니다.
기타
많은 AI 애플리케이션에는 원격 MCP 서버에 연결하는 방법이 있습니다. 일반적으로 이름, 엔드포인트, 전송 프로토콜, 인증 방법과 같은 서버에 대한 세부정보를 입력해야 합니다. Docs 원격 MCP 서버의 경우 다음을 입력합니다.
서버 이름:
docs서버 URL:
https://docsmcp.googleapis.com/mcp/v1전송: 스트리밍 가능한 HTTP
인증: Docs 원격 MCP 서버는 OAuth 2.0을 사용합니다. OAuth 2.0 클라이언트를 만들 때 AI 기반 에이전트에 이 클라이언트 사용을 선택합니다. 자세한 내용은 인증 및 승인 알아보기를 참고하세요.
웹 애플리케이션 OAuth 클라이언트를 사용하여 시간당 로그인 메시지가 표시되지 않도록 하려면
access_type=offline또는offline_access범위를 사용하여 오프라인 액세스를 요청하도록 MCP 클라이언트를 구성하세요. 자세한 내용은 매시간 반복되는 로그인 메시지를 참고하세요.
다양한 유형의 AI 애플리케이션을 연결하는 방법에 관한 자세한 내용은 AI 애플리케이션에서 MCP 구성을 참고하세요.
Docs MCP 서버 테스트
AI 애플리케이션을 구성한 후에는 몇 가지 테스트 프롬프트를 실행하여 연결을 확인할 수 있습니다.
AI 애플리케이션에 다음과 같은 질문을 해보세요.
"Google Docs
abcd123의 구조적 콘텐츠를 보여 줘."클라이언트는
docs.read_doc를 사용하여 문서 구조와 콘텐츠를 가져옵니다."Google 문서
abcd123에 '내 마케팅 계획'이라는 제목을 삽입해 줘."클라이언트는
docs.update_doc를 실행하여 구조 요소를 업데이트하고 텍스트를 삽입합니다.
도구가 성공적으로 실행되고 관련 응답을 받으면 Docs MCP 서버가 올바르게 구성된 것입니다.
문제 해결
다음 섹션을 참고하여 Docs MCP 서버의 일반적인 인증 및 연결 문제를 해결하세요.
OAuth 로그 이벤트 확인하기
MCP 서버에 연결하는 데 문제가 발생하면 OAuth 로그에서 오류를 확인합니다. Google Workspace 관리자에게 보안 조사 도구에서 OAuth 로그 이벤트를 검토하도록 요청합니다.
사용자가 위임한 OAuth 클라이언트의 거부된 요청
MCP 서버에 대한 요청이 거부되면 3-legged OAuth 흐름의 사용자 위임 OAuth 2.0 클라이언트 ID에 Google Auth Platform > 클라이언트에서 AI 기반 에이전트에 이 클라이언트 사용이 선택되어 있는지 확인하세요.
- 기존 클라이언트가 설정을 지원하는 경우: 기존 OAuth 클라이언트에서 AI 기반 에이전트에 이 클라이언트 사용을 선택합니다.
- 기존 클라이언트를 업데이트할 수 없음: AI 기반 에이전트에 이 클라이언트 사용을 선택한 상태로 새 OAuth 클라이언트를 만들고 이를 사용하도록 앱을 업데이트합니다.
- 기존 클라이언트가 에이전트가 아닌 기능도 지원하는 경우: AI 에이전트에 별도의 OAuth 클라이언트를 만들고 에이전트가 아닌 기능에 기존 클라이언트를 유지합니다.
자세한 내용은 AI 애플리케이션 구성 및 OAuth 클라이언트 관리를 참조하세요.
도메인 전체 위임이 부여된 서비스 계정
앱에서 2-legged OAuth에 도메인 전체 위임이 있는 서비스 계정을 사용하는 경우 서비스 계정은 Google Auth Platform > 클라이언트에서 관리되지 않으므로 AI 기반 에이전트에 이 클라이언트 사용을 선택할 수 없습니다.
- 액세스 제어: 이러한 서비스 계정에서 MCP 서버로 전송되는 요청은 에이전트 설정이 누락되어도 거부되지 않습니다. 대신 Google Workspace 관리자가 관리하는 도메인 전체 위임 설정에 따라 액세스가 제어됩니다. 관리자 설정에 대한 자세한 내용은 도메인 전체 위임으로 API 액세스 제어를 참조하세요.
- 민감한 작업: Google Workspace MCP 서버는 도메인 전체 위임 사용자 가장을 통해 이루어진 민감한 도구 호출에 대해 휴먼인더루프 확인을 위한 양식 유도 프롬프트를 계속 반환합니다.
Apps Script의 요청
Apps Script에서 MCP 서버를 호출하는 경우 Apps Script가 스크립트를 위해 만들고 관리하는 기본 OAuth 클라이언트에서 AI 기반 에이전트에 이 클라이언트 사용을 선택할 수 없습니다. 이는 스크립트가 표준 Google Cloud 프로젝트를 사용하는 경우에도 적용됩니다.
Apps Script에서 MCP 서버를 호출하려면 다음 단계를 따르세요.
- Google Cloud 콘솔에서 Google 인증 플랫폼 > 클라이언트로 이동하여 OAuth 클라이언트를 만들고 AI 기반 에이전트에 이 클라이언트 사용을 선택합니다.
- 스크립트에서 Apps Script용 OAuth2 라이브러리를 사용하여 해당 OAuth 클라이언트로 사용자를 승인합니다.
- MCP 서버를 호출할 때
ScriptApp.getOAuthToken의 토큰 대신 라이브러리에서 반환하는 액세스 토큰을 전송합니다.
Google Workspace MCP 서버를 호출하지 않는 Apps Script 프로젝트는 영향을 받지 않습니다.
시간별 로그인 메시지 반복
약 1시간마다 다시 로그인하라는 메시지가 표시되면 MCP 클라이언트가 갱신 토큰을 수신하거나 사용하지 않는 것입니다. 이 문제는 일반적으로 다음과 같은 상황에서 발생합니다.
- 웹 애플리케이션 OAuth 클라이언트에 오프라인 액세스 누락: 데스크톱 앱 OAuth 클라이언트와 달리 웹 애플리케이션 OAuth 클라이언트는 기본적으로 온라인 액세스로 설정됩니다. 갱신 토큰을 요청하려면
access_type=offline를 포함하거나 하나 이상의 API 범위와 함께 OpenID Connect(OIDC)offline_access범위를 포함하고access_type=online를 설정하지 마세요. - 이미 동의한 앱 재승인: Google의 OAuth 2.0 서버는 사용자가 오프라인 액세스를 처음 부여할 때 갱신 토큰을 발급합니다. 사용자가
오프라인 액세스 없이 이미 OAuth 클라이언트를 승인했거나 MCP 클라이언트가
저장된 갱신 토큰을 분실한 경우 후속 로그인에서 새 갱신 토큰이
반환되지 않을 수 있습니다. 승인 요청에
prompt=consent를 포함하거나 Google 계정 연결에서 앱의 액세스 권한을 삭제하고 다시 로그인하세요. - 정적 Bearer 토큰:
gcloud auth print-access-token의 출력과 같은 원시 액세스 토큰을Authorization헤더에 전달하는 경우 클라이언트가 새로고침하지 않는 한 토큰은 1시간 후에 만료됩니다.
자세한 내용은 액세스 토큰 새로고침을 참고하세요.
도구 참조
Docs MCP 서버에서 사용할 수 있는 도구는 다음과 같습니다. 입력 및 출력 스키마는 Docs MCP 참조를 확인하세요.
중요한 보안 고려사항: 간접 프롬프트 인젝션
언어 모델을 신뢰할 수 없는 데이터에 노출하면 간접 프롬프트 인젝션 공격의 위험이 있습니다. Google Antigravity와 같은 AI 애플리케이션은 Docs MCP 서버를 통해 강력한 도구와 API에 액세스할 수 있으므로 Google 계정의 데이터를 읽고, 수정하고, 삭제할 수 있습니다.
이러한 위험을 완화하려면 악성 콘텐츠 또는 프롬프트 인젝션 공격에 대한 프롬프트와 대답을 선별해야 합니다. Google에서 제공하는 Model Armor를 사용하거나, 사용자가 위험을 수용할 수 있도록 문서화하는 경우 자체 솔루션을 사용할 수 있습니다. 자세한 내용은 Google Workspace MCP 서버의 보안 구성을 참고하세요.
다음의 권장사항을 따르세요.
- 신뢰할 수 있는 도구만 사용하세요. Docs MCP 서버를 신뢰할 수 없거나 확인되지 않은 애플리케이션에 연결하지 마세요.
- 신뢰할 수 없는 입력에 주의하세요. AI 애플리케이션에 확인되지 않은 소스의 문서나 기타 리소스를 처리하도록 요청하지 마세요. 이러한 입력에는 세션을 가로채고 공격자가 데이터를 수정, 도용 또는 삭제할 수 있는 숨겨진 명령어가 포함될 수 있습니다.
- 모든 작업을 검토합니다. AI 애플리케이션이 사용자를 대신하여 수행하는 작업이 정확하고 사용자의 의도와 일치하는지 항상 신중하게 검토하세요.