People API MCP 서버 구성

People API는 AI 에이전트가 Google Workspace 프로필 및 연락처 데이터와 안전하게 상호작용할 수 있도록 지원하는 원격 모델 컨텍스트 프로토콜 (MCP) 서버를 제공합니다. People API MCP 서버를 구성하면 Google Antigravity 및 Claude와 같은 AI 애플리케이션이 People API를 사용하여 작업을 실행할 수 있습니다.

People API MCP 서버는 AI 에이전트가 다음 작업을 실행할 수 있는 표준화된 방법을 제공합니다.

  • 데이터 읽기: 사용자 프로필을 가져오고 연락처 또는 디렉터리 사용자를 검색합니다.
  • 보안 준수: 사용자와 동일한 권한 및 데이터 거버넌스 제어를 상속합니다.

기본 요건

People API MCP 서버 구성

People API MCP 서버를 사용하려면 Google Cloud 프로젝트에서 People API MCP 서버를 사용 설정한 후 MCP 클라이언트를 구성하여 People API MCP 서버에 연결해야 합니다.

API 및 MCP 서비스 사용 설정

People API MCP 서버를 사용하려면 Google Cloud 프로젝트에서 다음 서비스를 사용 설정해야 합니다.

  • People API

CLI

gcloud services enable people.googleapis.com --project=PROJECT_ID

PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

콘솔

Google Cloud 콘솔에서 API를 사용 설정합니다.

API 사용 설정

People API MCP 서버는 인증 및 승인에 OAuth 2.0을 사용합니다. OAuth 클라이언트 ID를 만들려면 먼저 OAuth 동의 화면을 구성해야 합니다.

  1. Google Cloud 콘솔에서 Google 인증 플랫폼 > 브랜딩 으로 이동합니다.

    브랜딩으로 이동

  2. 이미 Google 인증 플랫폼을 구성한 경우 브랜딩, 대상, 데이터 액세스에서 다음 OAuth 동의 화면 설정을 구성할 수 있습니다. Google 인증 플랫폼이 아직 구성되지 않음이라는 메시지가 표시되면 시작하기를 클릭합니다.

    1. 앱 정보의 앱 이름에 People API MCP Server를 입력합니다.
    2. **사용자 지원 이메일** 에서 이메일 주소 또는 적절한 Google 그룹을 선택합니다.
    3. 다음 을 클릭합니다.
    4. **대상** 에서 **내부** 를 선택합니다. 내부를 선택할 수 없는 경우 외부를 선택합니다.
    5. 다음 을 클릭합니다.
    6. 연락처 정보에서 프로젝트 변경사항에 관한 알림을 받을 수 있는 이메일 주소를 입력합니다.
    7. 다음 을 클릭합니다.
    8. 완료에서 Google API 서비스 사용자 데이터 정책 을 검토하고 동의하는 경우 Google API 서비스: 사용자 데이터 정책에 동의합니다를 선택합니다.
    9. 계속 을 클릭합니다.
    10. 만들기 를 클릭합니다.
    11. 사용자 유형으로 외부 를 선택한 경우 테스트 사용자를 추가합니다.
      1. 잠재고객 을 클릭합니다.
      2. **테스트 사용자** 에서 **사용자 추가** 를 클릭합니다.
      3. 이메일 주소와 기타 승인된 테스트 사용자를 입력한 후 저장 을 클릭합니다.

  3. 데이터 액세스 > 범위 추가 또는 삭제 를 클릭합니다. Google Cloud 프로젝트에서 사용 설정한 각 API의 범위 목록이 포함된 패널이 표시됩니다.

    1. 직접 범위 추가에서 People API MCP 서버의 범위를 붙여넣습니다.

      • https://www.googleapis.com/auth/directory.readonly
      • https://www.googleapis.com/auth/userinfo.profile
      • https://www.googleapis.com/auth/contacts.readonly

    2. 테이블에 추가 를 클릭합니다.

    3. 업데이트 를 클릭합니다.

    4. 앱에 필요한 범위를 선택한 후 데이터 액세스 페이지에서 저장 을 클릭합니다.

MCP 클라이언트 구성

MCP 클라이언트에 People API 원격 MCP 서버를 추가하려면 클라이언트의 안내를 따르세요.

Antigravity

Antigravity에 People API 원격 MCP 서버를 추가하려면 mcp_config.json 파일에 서버 구성을 추가합니다. 이 안내는 Antigravity 2.0, Antigravity IDE, Antigravity CLI를 지원합니다.

  1. OAuth 2.0 클라이언트 ID 및 보안 비밀번호를 만듭니다.

    1. Google Cloud 콘솔에서 Google 인증 플랫폼 > 클라이언트 > 클라이언트 만들기 로 이동합니다.

      클라이언트 만들기로 이동

    2. 애플리케이션 유형으로 웹 애플리케이션 을 선택합니다.

    3. 이름 을 입력합니다.

    4. 승인된 리디렉션 URI 섹션에서 + URI 추가를 클릭한 후 https://antigravity.google/oauth-callback을(를) URI 필드에 추가합니다.

    5. 만들기 를 클릭하고 클라이언트 ID 및 클라이언트 보안 비밀번호 를 복사합니다.

  2. 구성 파일 ~/.gemini/antigravity/mcp_config.json을 열거나 만듭니다.

  3. mcp_config.json에 mcpServers 구성을 추가합니다.

    {
  "mcpServers": {
    "people": {
      "serverUrl": "https://people.googleapis.com/mcp/v1",
      "oauth": {
        "clientId": "OAUTH_CLIENT_ID",
        "clientSecret": "OAUTH_CLIENT_SECRET"
      }
    }
  }
}

    다음을 바꿉니다.

    • OAUTH_CLIENT_ID: 만든 클라이언트 ID입니다.
    • OAUTH_CLIENT_SECRET: 만든 클라이언트 보안 비밀번호입니다.

  4. mcp_config.json을 저장합니다.

  5. MCP 서버를 인증합니다. GUI 설정 또는 CLI를 사용하여 인증할 수 있습니다.

    • Antigravity IDE 또는 GUI (Antigravity 2.0)의 경우:

      1. 설정 화면을 엽니다 (예: 왼쪽 하단에서 설정 을 클릭하거나 Antigravity 사용자 설정 을 엽니다).
      2. 맞춤설정 으로 이동합니다.
      3. 설치된 MCP 서버에서 새로고침을 클릭합니다.
      4. 목록에서 people을 찾아 인증을 클릭하고 Google 계정에 로그인한 후 승인 코드를 복사하여 입력 대화상자에 붙여넣고 제출을 클릭합니다.

    • Antigravity CLI의 경우:

      1. Antigravity CLI를 시작합니다.

        agy

      2. 다음을 실행하여 대화형 MCP 관리 패널을 엽니다.

        /mcp

      3. 화살표 키를 사용하여 people을 선택하고 인증 작업으로 이동한 후 Enter 를 누릅니다. 브라우저에서 로그인 절차를 완료하고 승인 코드를 복사하여 터미널 프롬프트에 붙여넣고 Enter 를 누릅니다.

  6. 서버가 올바르게 구성되고 실행 중인지 확인합니다.

    • Antigravity IDE 또는 GUI의 경우: 맞춤설정 > 설치된 MCP 서버 아래 서버 옆에 로그아웃 버튼이 표시됩니다.
    • Antigravity CLI의 경우: /mcp 패널을 열어 구성된 MCP 서버를 확인합니다. 인증된 서버는 대화형 TUI 패널 내 이름 옆에 인증됨 이 표시됩니다. 대시보드 뷰에서 서버를 선택하여 상태를 검사하고 사용 가능한 모든 도구를 나열할 수 있습니다.

원격 MCP 서버를 Antigravity에서 사용할 수 있습니다.

Claude

Claude.ai 또는 Claude Desktop에서 People API 원격 MCP 서버를 사용하려면 Claude Enterprise, Pro, Max 또는 Team 요금제를 사용해야 합니다.

Claude에 People API 원격 MCP 서버를 추가하려면 OAuth 클라이언트 ID 및 보안 비밀번호로 커스텀 커넥터를 구성합니다.

  1. OAuth 2.0 클라이언트 ID 및 보안 비밀번호를 만듭니다.

    1. Google Cloud 콘솔에서 Google 인증 플랫폼 > 클라이언트 > 클라이언트 만들기 로 이동합니다.

      클라이언트 만들기로 이동

    2. 애플리케이션 유형으로 웹 애플리케이션 을 선택합니다.

    3. 이름 을 입력합니다.

    4. 승인된 리디렉션 URI 섹션에서 + URI 추가를 클릭한 후 https://claude.ai/api/mcp/auth_callbackURI 필드에 추가합니다.

    5. 만들기 를 클릭하고 클라이언트 ID 및 클라이언트 보안 비밀번호 를 복사합니다.

  2. Claude에서 MCP 서버를 구성합니다.

    1. Claude.ai 또는 Claude Desktop에서 설정(또는 관리자 설정) > 커넥터 로 이동합니다.
    2. 커스텀 커넥터 추가 를 클릭합니다.
    3. People API 제품의 연결 세부정보를 입력합니다.
      • 서버 이름: people.
      • 원격 MCP 서버 URL: https://people.googleapis.com/mcp/v1
    4. 고급 설정에서 OAuth 클라이언트 ID 및 OAuth 클라이언트 보안 비밀번호를 입력합니다.
    5. 추가 를 클릭합니다.

기타

많은 AI 애플리케이션에는 원격 MCP 서버에 연결하는 방법이 있습니다. 일반적으로 서버 이름, 엔드포인트, 전송 프로토콜, 인증 방법과 같은 서버에 관한 세부정보를 입력해야 합니다. People API 원격 MCP 서버의 경우 다음을 입력합니다.

  • 서버 이름: people

  • 서버 URL: https://people.googleapis.com/mcp/v1

  • 전송: HTTP

  • 인증: People API 원격 MCP 서버는 OAuth 2.0을 사용합니다. 자세한 내용은 인증 및 승인 알아보기

다양한 유형의 클라이언트를 연결하는 방법에 관한 자세한 내용은 AI 애플리케이션에서 MCP 구성을 참고하세요.

People API MCP 서버 테스트

MCP 클라이언트를 구성한 후 일부 테스트 프롬프트를 실행하여 연결을 확인할 수 있습니다.

MCP 클라이언트에게 다음 질문을 해보세요.

  • "내 Google 프로필에 따르면 내 이름이 뭐야?"

    클라이언트는 people.get_user_profile을 사용하여 Google Workspace 프로필 정보를 가져옵니다.

도구가 성공적으로 실행되고 관련 응답을 받으면 People API MCP 서버가 올바르게 구성된 것입니다.

문제 해결

MCP 서버에 연결하는 데 문제가 발생하면 OAuth 로그에서 오류를 확인할 수 있습니다. 관리자에게 OAuth 로그 이벤트를 보안 조사 도구에서 확인해 달라고 요청하세요.

도구 참조

People API MCP 서버에는 다음과 같은 도구가 제공됩니다.

  • get_user_profile
  • search_contacts
  • search_directory_people

중요 보안 고려사항: 간접 프롬프트 인젝션

신뢰할 수 없는 데이터에 언어 모델을 노출하면 간접 프롬프트 인젝션 공격의 위험이 있습니다. Google Antigravity와 같은 MCP 호스트는 People API MCP 서버를 통해 강력한 도구와 API에 액세스할 수 있으므로 Google 계정에서 데이터를 읽을 수 있습니다.

이러한 위험을 완화하려면 악성 콘텐츠 또는 프롬프트 삽입 공격에 대해 프롬프트와 응답을 검사해야 합니다. Google에서 제공하는 Model Armor를 사용하거나 사용자가 위험을 수용할 수 있도록 문서화하는 경우 자체 솔루션을 사용할 수 있습니다. 자세한 내용은 Google Workspace MCP 서버의 보안 구성을 참고하세요.

다음의 권장사항을 따르세요.

  • 신뢰할 수 있는 도구만 사용하세요. 신뢰할 수 없거나 인증되지 않은 애플리케이션에 People API MCP 서버를 연결하지 마세요.
  • 신뢰할 수 없는 입력에 주의하세요. 인증되지 않은 소스의 리소스를 처리하도록 MCP 클라이언트에게 요청하지 마세요. 이러한 입력에는 세션을 가로채 공격자가 데이터를 수정, 도용 또는 삭제할 수 있는 숨겨진 안내가 포함될 수 있습니다.
  • 모든 작업을 검토하세요. AI 클라이언트가 사용자를 대신하여 취한 작업을 항상 주의 깊게 검토하여 올바르고 의도와 일치하는지 확인하세요.