MCP 서비스 계정

AI 에이전트, 봇, CI 작업 또는 백엔드 서비스가 OAuth 로그인을 완료하기 위해 브라우저에서 사용자 없이 Amplitude MCP를 호출해야 할 때 MCP 서비스 계정을 사용하십시오. 서비스 계정은 고유한 클라이언트 ID와 클라이언트 비밀을 가진 조직 소유의 ID입니다. 귀하의 서비스는 이러한 자격 증명을 OAuth 2.0 클라이언트 자격 증명 흐름과 교환한 다음 해당 토큰을 MCP 서버로 전송합니다.

가용성: MCP 서비스 계정은 MCP 액세스가 활성화된 Enterprise 요금제에 있는 조직에서 사용할 수 있습니다.

사용자 OAuth 대신 서비스 계정을 사용하는 시기

사전 조건

  • Org 관리자에게 설정을 완료하도록 하십시오. Org 관리자는 기본적으로 서비스 계정을 관리할 수 있습니다.
  • 귀하의 조직은 Enterprise 요금제를 사용하고 있으며 MCP 액세스가 활성화되어 있습니다.
  • 설정에 서비스 계정이 누락된 경우, Amplitude 팀에 문의하여 조직의 활성화를 확인하십시오.
  • MCP 클라이언트 또는 서비스는 Streamable HTTP를 통해 원격 MCP를 지원하며 사용자 지정 Authorization 헤더를 설정할 수 있습니다.
  • 서비스는 현재 토큰이 만료되기 전에 새로운 액세스 토큰을 요청하고 클라이언트의 인증 헤더를 업데이트할 수 있습니다.

서비스 계정 생성

  1. Amplitude에서 설정 > 권한 관리 > 서비스 계정으로 이동합니다.
  2. 서비스 계정 생성을 클릭합니다.
  3. 설명적인 이름을 입력합니다(예: support-bot-prod).
  4. 계정에는 ALL_READ로 표시된 읽기 액세스 권한이 포함됩니다. 설정을 통해 생성된 고객 계정은 현재 읽기 전용입니다.
  5. 조직에서 권한 그룹을 사용하는 경우 서비스에 필요한 프로젝트에 액세스 권한을 부여하는 그룹을 선택합니다. 나중에 멤버 및 그룹에서 그룹을 할당할 수도 있습니다.
  6. 생성을 클릭한 다음 클라이언트 ID와 클라이언트 시크릿을 복사합니다.

지금 두 자격 증명을 모두 저장하십시오

Amplitude는 클라이언트 시크릿을 한 번만 표시합니다. 패널을 닫기 전에 Secret Manager에 저장하십시오. 분실한 경우 교체를 사용하여 대체 자격 증명을 생성하십시오.

설정을 통해 서비스 계정을 생성하기 위해 개인 액세스 토큰(PAT)은 필요하지 않습니다.

역할 및 권한 관리 할당

새 서비스 계정은 멤버로 생성됩니다. 만드는 관리자의 권한 관리를 상속받지 않습니다. 해당 프로젝트 및 데이터 액세스 권한은 조직의 역할과 권한 그룹에 따라 다릅니다.

  1. 설정 > 권한 관리 > 멤버 및 그룹(또는 조직에서 그룹을 사용하지 않는 경우 멤버)을 엽니다.
  2. **SA: <name>**이라는 계정을 찾습니다(예: SA: support-bot-prod).
  3. 멤버에게 할당하는 것처럼 이 서비스에 필요한 데이터 액세스 권한을 부여하는 권한 그룹 또는 프로젝트 역할을 할당하십시오. 사용자 지정 역할이 필요한 경우 역할 관리에서 정의한 다음 계정 또는 해당 그룹에 할당하십시오.
  4. 연결 후 get_amplitude_context을(를) 인수 없이 호출하여 반환된 프로젝트 목록을 확인하십시오.

OAuth 범위는 계정이 사용할 수 있는 도구의 종류를 제한합니다. 프로젝트 역할과 권한은 해당 도구가 액세스할 수 있는 프로젝트 데이터를 제어합니다. 자동화된 서비스와 자격 증명을 공유하기 전에 두 가지 모두를 검토하십시오.

액세스 토큰 받기

해당 지역의 토큰 엔드포인트에서 클라이언트 ID와 비밀을 교환하십시오. 위치 표시자를 설정의 자격 증명으로 바꿉니다.

shell
curl -X POST https://mcp.amplitude.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=CLIENT_ID" \
  --data-urlencode "client_secret=CLIENT_SECRET" \
  --data-urlencode "scope=all:read"

응답에서 access_token 및 expires_in을(를) 읽습니다. expires_in은(는) 토큰의 수명(초)입니다. 네트워크 지연에 대한 작은 마진을 허용하여 만료되기 전에 동일한 클라이언트 자격 증명을 사용하여 새 토큰을 요청하십시오.

계정의 범위와 일치시키십시오. 설정 레이블 ALL_READ은(는) 토큰 요청의 all:read에 해당합니다. MCP_READ이(가) 나열된 이전 계정의 경우 scope=mcp:read을(를) 요청합니다. 항상 해당 계정에 허용되는 명시적 범위를 전송하십시오.

에이전트 또는 MCP 클라이언트 연결

모든 MCP 요청에 대해 클라이언트 시크릿이 아닌 access_token를 Bearer 토큰으로 전송합니다. 다음 예제는 사용자 지정 헤더를 사용하는 mcpServers 구성을 허용하는 클라이언트를 위한 것입니다. 정확한 형식은 클라이언트의 문서를 확인하십시오.

json
{
  "mcpServers": {
    "amplitude": {
      "url": "https://mcp.amplitude.com/mcp",
      "headers": {
        "Authorization": "Bearer ACCESS_TOKEN"
      }
    }
  }
}

ACCESS_TOKEN을(를) 응답의 토큰으로 바꿉니다. 만료되기 전에 클라이언트 자격 증명 교환을 반복하고 MCP 클라이언트가 전송하는 헤더를 업데이트합니다. 정적 구성은 토큰을 자동으로 갱신하지 않습니다. 새 토큰을 적용하기 위해 필요한 경우 클라이언트를 다시 로드하거나 다시 연결합니다.

연결을 확인하려면 get_amplitude_context을(를) 인수 없이({}) 호출하십시오. 조직과 서비스 계정이 액세스할 수 있는 프로젝트를 반환해야 합니다.

지역

토큰 요청과 MCP 호출 모두에 조직의 데이터 영역과 일치하는 엔드포인트를 사용하십시오.

Scopes

설정을 통해 생성된 서비스 계정은 읽기 액세스 권한을 제공합니다.

새 서비스 계정은 all:read를 사용합니다. 기존 계정은 교체된 경우를 포함하여 mcp:read을(를) 유지합니다. 두 범위 모두 프로젝트 권한 관리에 따라 동일한 읽기 도구를 승인합니다. 토큰을 요청할 때 계정에 대해 나열된 범위를 사용하십시오. 기존 서비스 계정은 설정에서 다시 생성할 필요가 없습니다.

자격 증명 순환 또는 취소

  • 순환: 서비스 계정에서 계정 행의 순환을 클릭하고 확인합니다. Rotation은 새 클라이언트 ID와 클라이언트 비밀로 대체 계정을 생성한 다음 이전 계정을 해지합니다. 두 새 값을 모두 저장하고, 모든 클라이언트를 업데이트한 다음 새 액세스 토큰을 요청하십시오. 이전 자격 증명이나 토큰에는 유예 기간이 없습니다. 전환 후 프로젝트 액세스를 확인합니다.
  • Revoke: 계정의 행에서 Revoke를 클릭하고 확인합니다. 이 작업은 계정을 영구적으로 비활성화합니다. 해당 토큰을 사용하는 후속 MCP 요청은 거부됩니다. 계정은 Revoked 상태로 계속 표시됩니다.
  • 각 조직은 최대 10개의 활성 서비스 계정을 가질 수 있습니다. 사용하지 않는 계정을 비활성화하여 슬롯을 확보하세요.

계획된 전환의 경우, 별도의 계정을 생성하고, 권한 관리를 할당 및 확인하고, 서비스를 업데이트한 다음 이전 계정을 해지하십시오. 이를 위해서는 사용 가능한 계정 슬롯이 필요합니다.

보안 모범 사례

  • 서비스에 필요한 프로젝트와 데이터에만 액세스 권한을 부여합니다.
  • 다른 계정에 영향을 주지 않고 하나를 해지할 수 있도록 에이전트 또는 환경당 하나의 서비스 계정을 생성하십시오.
  • 클라이언트 시크릿과 액세스 토큰을 Secret Manager에 저장합니다. 절대로 커밋하거나 프롬프트에 붙여넣지 마십시오.
  • 정기적으로 그리고 액세스 권한이 있는 사람이 퇴사할 때 자격 증명을 순환하십시오. 순환하기 전에 클라이언트 업데이트를 계획하십시오.
  • 서비스 계정을 정기적으로 검토하고 사용하지 않는 계정을 해지하십시오.

문제 해결

토큰 요청의 경우 응답의 error 및 error_description을(를) 참조하십시오. 오류 코드만으로는 정확한 원인을 식별할 수 없습니다.

이 내용이 도움이 되었나요?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

이 페이지에서