Scout Monitoring MCP

Scout Monitoring MCP

이 저장소에는 Scout의 API를 통해 https://www.scoutapm.com 데이터에 접근할 수 있는 MCP 서버를 로컬에서 실행하기 위한 코드가 포함되어 있습니다. AI Assistant가 Scout Monitoring 데이터에 접근할 수 있도록 pull하여 실행할 수 있는 Docker 이미지를 제공합니다.

이를 통해 Scout Monitoring의 성능 및 오류 데이터를 AI Assistant가 직접 활용할 수 있습니다. Rails, Django, FastAPI, Laravel 등에서 사용할 수 있습니다. AI가 편집기와 코드베이스에서 바로 수정 작업을 수행할 수 있도록 코드 라인 정보가 포함된 트레이스와 오류를 가져오는 데 사용하세요. N+1 쿼리, 느린 엔드포인트, 느린 쿼리, 메모리 팽창, 처리량 문제 등 여러분이 즐겨 찾는 모든 성능 문제가 여러분이 작업하는 바로 그곳에서 드러나고 설명됩니다.

이것이 여러분의 삶을 조금이라도 더 낫게 만든다면, :star:를 눌러주시는 건 어떨까요?!

설정 마법사

Scout MCP를 구성하고 사용을 시작하는 가장 간단한 방법은 대화형 설정 마법사를 이용하는 것입니다. 모든 사전 요구 사항과 설치 단계를 대신 처리해 줍니다.

npx로 실행:

npx @scout_apm/wizard

소스에서 빌드하고 실행:

cd ./wizard
npm install
npm run build
node dist/wizard.js

마법사가 안내하는 단계:

• AI 코딩 플랫폼 선택 (Cursor, Claude Code, Claude Desktop)
• Scout API 키 입력
• MCP 서버 설정 자동 구성

지원 플랫폼

현재 마법사가 지원하는 설정 대상:

• Cursor - MCP 설정을 자동으로 구성
• Claude Code (CLI) - 실행할 올바른 명령을 제공
• Claude Desktop - Windows/Mac용 구성 파일을 업데이트

그 외의 경우에는 AI Assistant의 MCP 구성에 복사/붙여넣기할 수 있는 JSON을 출력합니다.

사전 요구 사항

마법사는 시작하기에 좋은 방법이지만, 수동으로 설정할 수도 있습니다. Scout Monitoring 계정을 보유하거나 생성하고 API 키를 발급받아야 합니다.

1. https://scoutapm.com/users/sign_up?utm_source=github&utm_medium=github&utm_campaign=scout-mcp-local
2. 애플리케이션에 Scout Agent를 설치하고 Scout 데이터를 전송하세요!
   • Ruby
   • Python
   • PHP
   • 로컬에서 시험해 보는 경우, 최상의 경험을 위해 설정에 monitor: true, errors_enabled: true이(가) 설정되어 있는지 확인하세요
3. 설정을 방문하여 API 키를 확인하거나 생성하세요
   • 이것은 "Agent Key"가 아니며, Settings 페이지에서 생성할 수 있는 "API Key"입니다
   • 이는 계정의 데이터에만 접근할 수 있는 읽기 전용 키입니다
4. Docker를 설치하세요. 아래 지침은 Docker 컨테이너를 시작할 수 있다고 가정합니다

현재 MCP 서버는 환경 변수나 시작 시 명령줄 인자로 API 키가 설정되지 않으면 시작되지 않습니다.

설치

MCP 서버를 실행하려면 제공된 Docker 이미지를 사용할 것을 권장합니다. 이 이미지는 AI Assistant가 시작하고 Scout API 키로 구성하도록 설계되었습니다. 많은 로컬 클라이언트는 특정 위치에서 MCP 서버를 실행할 명령을 지정할 수 있게 해줍니다. 몇 가지 예시는 아래에 제공됩니다.

Docker 이미지는 Docker Hub에서 사용할 수 있습니다.

물론 이 저장소를 클론하여 MCP 서버를 직접 실행할 수도 있습니다. uv 또는 다른 환경 관리 도구를 권장합니다.

로컬 클라이언트 구성 (예: Claude/Cursor/VS Code Copilot)

MCP를 수동으로 구성하려는 경우, 이는 보통 AI Assistant의 구성에 환경 변수로 API 키를 포함하여 MCP 서버를 실행할 명령을 제공하는 것을 의미합니다. 다음은 JSON의 형태입니다(최상위 키는 다를 수 있음):

{
  "mcpServers": {
    "scout-apm": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env", "SCOUT_API_KEY", "scoutapp/scout-mcp-local"],
      "env": { "SCOUT_API_KEY": "your_scout_api_key_here"}
    }
  }
}

claude mcp add scoutmcp -e SCOUT_API_KEY=your_scout_api_key_here -- docker run --rm -i -e SCOUT_API_KEY scoutapp/scout-mcp-local

{
  "mcpServers": {
    "scout-apm": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env", "SCOUT_API_KEY", "scoutapp/scout-mcp-local"],
      "env": { "SCOUT_API_KEY": "your_scout_api_key_here"}
    }
  }
}

Scout Monitoring MCP 사용하기

Scout의 MCP는 오류 및 성능 데이터를 AI Assistant의... 손에? 직접 쥐여주기 위한 것입니다. AI가 편집기에서 바로 수정 작업을 수행할 수 있도록 코드 라인 정보가 포함된 트레이스와 오류를 가져오는 데 사용하세요.

대부분의 어시스턴트는 원시 도구 호출을 보여주고 분석을 수행합니다. 데스크톱 어시스턴트는 원하는 데이터를 탐색하기 위한 사용자 정의 JS 애플리케이션을 손쉽게 만들 수 있습니다. 코드 편집기에 통합된 어시스턴트는 트레이스 데이터와 오류 백트레이스를 사용하여 코드베이스에서 바로 수정할 수 있습니다.

Scout의 MCP를 AI Assistant의 다른 도구와 결합하여:

• 오류 및 성능 데이터를 기반으로 풍부한 GitHub/GitLab 이슈 생성
• JIRA를 재미있게 만들기 - AI Assistant가 모든 세부 정보를 담은 티켓을 생성하도록 하기
• 특정 오류와 성능 문제를 해결하는 PR 생성

도구

Scout MCP는 Scout APM 데이터에 접근하기 위한 다음 도구를 제공합니다:

• list_apps - 사용 가능한 Scout APM 애플리케이션 목록 (마지막 활성 날짜로 선택적 필터링 가능)
• get_app_metrics - 특정 애플리케이션의 개별 메트릭 데이터(response_time, throughput 등) 가져오기
• get_app_endpoints - 집계된 성능 메트릭과 함께 애플리케이션의 모든 엔드포인트 가져오기
• get_endpoint_metrics - 애플리케이션의 특정 엔드포인트에 대한 시계열 메트릭 가져오기
• get_app_endpoint_traces - 특정 엔드포인트로 필터링된 앱의 최근 트레이스 가져오기
• get_app_trace - 모든 스팬과 상세 실행 정보를 포함한 개별 트레이스 가져오기
• get_app_error_groups - 앱의 최근 오류 그룹 가져오기 (선택적으로 엔드포인트로 필터링 가능)
• get_app_insights - N+1 쿼리, 메모리 팽창, 느린 쿼리를 포함한 성능 인사이트 가져오기

리소스

Scout MCP는 AI Assistant가 읽고 적용할 수 있는 구성 템플릿을 리소스로 제공합니다:

• scoutapm://config-resources/{framework} - 지원되는 프레임워크 또는 라이브러리(rails, django, flask, fastapi)에 대한 설정 지침
• scoutapm://config-resources/list - 사용 가능한 모든 구성 템플릿 목록
• scoutapm://metrics - Scout APM에서 사용 가능한 모든 메트릭 목록

유용한 프롬프트

설정 및 구성

• "내 Rails 애플리케이션에 Scout 모니터링을 설정하도록 도와줘"
• "키 ABC123으로 내 Django 프로젝트에 대한 Scout APM 구성 파일을 만들어 줘"

성능 및 모니터링

• "Scout Monitoring MCP에서 사용 가능한 도구를 요약해 줘."
• "지난 7일 동안 앱 my-app-name의 가장 느린 엔드포인트를 찾아줘. 평균 응답 시간, 처리량, P95 응답 시간을 포함한 결과 표를 생성해 줘."
• "지난 24시간 동안 앱 Foo의 빈도가 가장 높은 오류를 보여줘. 최신 오류 세부 정보를 가져오고, 백트레이스를 검토하여 수정 방안을 제안해 줘."
• "앱 Bar의 최근 n+1 인사이트를 가져와 줘. ID로 특정 트레이스를 가져오고 백트레이스 데이터를 기반으로 최적화하도록 도와줘."

토큰 사용량

현재 우리는 MCP 도구의 응답 크기를 엄격하게 제어하는 것보다 사용 가능한 정보를 확장하는 데 더 관심이 있습니다. AI Assistant에 구성 가능한 토큰 한도가 있는 경우(예: Claude Code export MAX_MCP_OUTPUT_TOKENS=50000), 넉넉하게 높게 설정할 것을 권장합니다(예: 50,000 토큰).

로컬 개발

이 프로젝트의 환경을 관리하고 작업을 실행하기 위해 uv과(와) taskipy을(를) 사용합니다.

Inspector로 실행

uv run task dev

Inspector 내에서 연결하여 API 키를 추가하고 STDIO 전송으로 설정하세요

Docker 이미지 빌드

docker build -t scout-mcp-local .

릴리스

1. 브랜치를 만들고 uv run python bump_versions.py(으)로 버전을 올립니다
2. 병합합니다
3. 새 버전으로 GitHub 릴리스를 생성합니다 (gh release create v2025.11.3 --generate-notes --draft)

릴리스를 게시하면 v* 태그가 푸시되고, CI가 Docker 이미지, PyPI 패키지, 그리고 MCP Registry 항목을 게시합니다:

• server.json → com.scoutapm/scout-mcp-local (이 서버; 버전은 bump_versions.py에 의해 올라감)
• server.remote.json → com.scoutapm/scout-monitoring (https://scoutapm.com/mcp에서 호스팅되는 서버). 메타데이터를 변경할 때는 version을(를) 수동으로 올리세요. 변경되지 않은 버전은 건너뜁니다.

MCP Registry 키

레지스트리는 scoutapm.com apex에 있는 Ed25519 공개 키를 담은 DNS TXT 레코드를 통해 우리가 com.scoutapm/* 네임스페이스를 소유하고 있음을 검증합니다. CI는 MCP_REGISTRY_PRIVATE_KEY 저장소 시크릿의 일치하는 개인 키로 로그인합니다. 키를 교체하려면:

openssl genpkey -algorithm Ed25519 -out key.pem
# Public key for the TXT record: replace the existing v=MCPv1 record, don't add a second one
echo "v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)"
# Private key (hex) for the MCP_REGISTRY_PRIVATE_KEY secret
openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'

봇의 경우:

mcp-name: com.scoutapm/scout-mcp-local