Scouter MCP server
AI 클라이언트가 관측성 데이터를 탐색하고 근본 원인을 진단할 수 있도록 Scouter APM 메트릭, XLogs, 카운터 및 객체를 조회합니다.
다른 이름 335/scouter-mcp, scouter-mcp
- 스타
- 2
- Tools
- 14
- 다운로드, 30일
- —
- 최신 버전
- 0.3.5
- 마지막 커밋
- 2026년 7월 8일
- 라이선스
- Apache-2.0
Scouter MCP란?
AI 클라이언트가 관측성 데이터를 탐색하고 근본 원인을 진단할 수 있도록 Scouter APM 메트릭, XLogs, 카운터 및 객체를 조회합니다. 14개 도구를 제공합니다. 예: list_objects, search_xlog, get_service_summary.
프로젝트 README에서 생성된 요약
Scouter MCP server 정보
Scouter MCP를 사용하면 AI 클라이언트에서 직접 Scouter APM 메트릭을 조회하여 애플리케이션 성능 문제를 진단할 수 있습니다. 이 stdio server는 TCP를 통해 Scouter Collector에 연결하며, 개발자가 XLogs, 카운터 및 객체를 탐색하여 지연 시간이나 오류의 근본 원인을 식별할 수 있도록 지원합니다. txid 또는 gxid와 같은 식별자를 사용하여 Datadog 또는 OpenSearch와 같은 다른 도구와 관측성 데이터를 교차 분석해야 하는 엔지니어를 위해 설계되었습니다.
사용자는 SCOUTER_COLLECTOR_HOST, SCOUTER_USER, SCOUTER_PASSWORD와 같은 환경 변수를 통해 인증 정보를 제공하여 서버를 설정합니다. 서버는 클라이언트 설정 파일에 별도의 항목을 추가하여 여러 collector를 지원하며, 각 항목은 독립된 환경 설정을 가집니다. 시스템 안정성을 보장하기 위해 collector에 수행되는 모든 작업은 읽기 전용입니다.
민감한 정보를 보호하기 위해 서버에는 JVM 시스템 속성의 비밀 정보를 마스킹하거나 SQL 바인드 파라미터를 제거하는 선택적 킬 스위치와 같은 보안 기능이 내장되어 있습니다. 또한 collector와 AI 클라이언트에 과도한 부하가 걸리는 것을 방지하기 위해 XLog 검색 결과 제한 및 대규모 스택 트레이스 절단과 같은 엄격한 리소스 가드레일을 구현합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Scouter MCP 도구 14
README에서 감지됨list_objectssearch_xlogget_service_summaryget_summaryget_xlog_detailget_xlog_by_gxidget_counterget_counter_statlist_counterslist_alertsget_active_serviceslist_threads
| list_objects | — | |
| search_xlog | — | |
| get_service_summary | — | |
| get_summary | — | |
| get_xlog_detail | — | |
| get_xlog_by_gxid | — | |
| get_counter | — | |
| get_counter_stat | — | |
| list_counters | — | |
| list_alerts | — | |
| get_active_services | — | |
| list_threads | — |
도구 14개 모두 보기도구 수 줄이기
get_thread_detailget_object_env
| get_thread_detail | — | |
| get_object_env | — |
구성
SCOUTER_COLLECTOR_HOSTSCOUTER_COLLECTOR_PORTSCOUTER_PASSWORDSCOUTER_TZSCOUTER_USER
| 이름 | 설명 | 유형 |
|---|---|---|
| SCOUTER_COLLECTOR_HOST | — | |
| SCOUTER_COLLECTOR_PORT | — | |
| SCOUTER_PASSWORD | — | |
| SCOUTER_TZ | — | |
| SCOUTER_USER | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능335/scouter-mcp is public and reachablegithub.com/335/scouter-mcp ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-07-08github.com/335/scouter-mcp ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음14 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기scouter-mcp
한국어 문서는 README.ko.md 를 참고하세요.
A stdio MCP server that connects directly to a Scouter Collector over TCP and queries XLogs,
counters, and objects. Its purpose is to let an AI quickly explore Scouter metrics and diagnose
root causes. Each result carries txid / gxid / objName / endTimeIso, which you can use as
keys to cross-analyze with other observability tools such as OpenSearch or Datadog.
Architecture
Java 17. It reuses scouter-common and ports the scouter.webapp net/server classes into the
scouter.mcp.client package. MCP uses the Java SDK 2.0.0 stdio transport. All operations against
the Collector are read-only.
Build
./gradlew shadowJar
# output: build/libs/scouter-mcp-<version>-all.jar
The .mcpb bundle is produced only by the release CI (which wraps this jar); local builds just
produce the jar.
Registration (Claude Code, Claude Desktop, ...)
For a single collector, install the .mcpb bundle from the GitHub Release for a
one-click setup — or copy .mcp.json.example, point it at the fat jar (downloaded from the release or
built locally), and fill in the credentials. For multiple collectors, see
Multiple collectors.
| Env var | Description |
|---|---|
SCOUTER_COLLECTOR_HOST |
Collector host |
SCOUTER_COLLECTOR_PORT |
Collector TCP port (default 6100) |
SCOUTER_USER |
Login user |
SCOUTER_PASSWORD |
Login password |
SCOUTER_TZ |
Time zone (e.g. Asia/Seoul) |
SCOUTER_LOCALE |
User-facing message locale: en or ko. If unset, derived from the JVM default (Korean only when the JVM language is Korean, otherwise English) |
SCOUTER_INCLUDE_BIND_PARAMS |
Operator kill-switch for SQL bind parameters in get_xlog_detail (default true). Set to false to strip bind params server-side regardless of the per-call argument — an LLM cannot re-enable them. Use when bind values may contain PII. |
Multiple collectors
The official release ships one .mcpb bundle (one-click install, a single collector) plus the
standalone fat jar. A .mcpb defines exactly one server with one credential set, so it cannot register
two collectors at once. For multiple collectors — which usually differ in their whole connection set
(host/port and user/password) — use the jar directly and add one entry per collector:
- Download
scouter-mcp-<version>-all.jarfrom the GitHub Release. - Add one
mcpServersentry per collector to your client config (.mcp.json/claude_desktop_config.json), all pointing at that same jar, each with its own env set. This keeps each credential isolated:
{
"mcpServers": {
"scouter-prod": {
"command": "java",
"args": ["-jar", "/ABSOLUTE/PATH/scouter-mcp-<version>-all.jar"],
"env": {
"SCOUTER_COLLECTOR_HOST": "prod-collector", "SCOUTER_COLLECTOR_PORT": "6100",
"SCOUTER_USER": "prod-user", "SCOUTER_PASSWORD": "***", "SCOUTER_TZ": "Asia/Seoul"
}
},
"scouter-stg": {
"command": "java",
"args": ["-jar", "/ABSOLUTE/PATH/scouter-mcp-<version>-all.jar"],
"env": {
"SCOUTER_COLLECTOR_HOST": "stg-collector", "SCOUTER_COLLECTOR_PORT": "6100",
"SCOUTER_USER": "stg-user", "SCOUTER_PASSWORD": "***", "SCOUTER_TZ": "Asia/Seoul"
}
}
}
}
The AI then orchestrates across the collectors.
Tools (14)
| Name | Purpose | Key inputs |
|---|---|---|
list_objects |
List objects/agents | objType?, nameLike? (case-insensitive) |
search_xlog |
Search XLogs (latency/errors) | from, to, objNameLike?, objHash?, service?, login?, ip?, desc?, minElapsedMs?, onlyError?, limit? (default 20, max 200) |
get_service_summary |
Per-service aggregate (count/avg/max/p95/errorRate), top 50 | from, to, same filters as search_xlog |
get_summary |
Collector's daily pre-aggregated stats (top-50 SQL/service/error/... — no scanning) | category (service/sql/apiCall/ip/userAgent/error/alert), from, to (up to 31 days), objType?, objNameLike?, objHash? |
get_xlog_detail |
XLog detail (SQL/bind params) | txid, date?/at?, includeBindParams? (default true) |
get_xlog_by_gxid |
Distributed-transaction group | gxid, date?/at? |
get_counter |
Counter time series (same-day, full resolution) | objNameLike|objHashes|objType, counter, from, to |
get_counter_stat |
Long-range counter stats (5-min resolution, up to 31 days) | objNameLike|objHashes|objType, counter, from, to |
list_counters |
Available counters for an objType | objType |
list_alerts |
Past collector alerts | from, to, level?, object?, key?, limit? |
get_active_services |
Services running right now | objNameLike|objType|objHash |
list_threads |
JVM thread list (state histogram + top 50 by cpu) | objNameLike|objHash (max 5 alive instances) |
get_thread_detail |
Live thread of an ACTIVE transaction (stack/lock owner/current SQL) | txid (required, active), id?, objNameLike|objHash |
get_object_env |
Agent JVM system properties (secrets masked) | objNameLike|objHash, keyLike? |
Fuzzy targeting (objNameLike)
Users say app-name fragments ("shop-order-api"), but real objNames embed the k8s pod name
(/shop-order-api-deployment-5f4b8c7d9-abcde/shop-order-api1), so objHash changes on every deploy
and an app spans multiple instances. objNameLike solves this: a case-insensitive fragment is
resolved to all matching instances (alive first, capped at 20) and queried across them — no
objHash needed, ever. For XLog search/summary the resolution also unions the collector's daily
object DB, so pods replaced by a deploy during the queried window are still found. If nothing
matches, the error is NOT_FOUND with a candidates hint listing actual objNames so the caller
can self-correct in one step.
Sloppy service queries
Scouter service names look like /api/order/.../search-order-info-grade<POST>, but users type
"GET orderDetail" or "order info grade". The service filter normalizes such input: an HTTP method is
extracted from any position (GET x, x POST, pasted <POST>), whitespace-separated words fall back
to the longest token server-side, and explicit * patterns pass through untouched. Server-side
matching is still case-sensitive — so when a pattern matches nothing, the same window is re-scanned
(bounded) without the service filter and real service names matching the query tokens
case-insensitively are returned as serviceCandidates, ordered by traffic. One retry with an exact
name resolves it.
service/login/ip/desc use substring match by default (server-side StrMatch), so a short token
like search-order-info-grade matches /api/order/ext/order-info/search-order-info-grade<POST>.
objNameLike/login/ip/desc count as server-side filters, so they relax the 5-minute
unfiltered-window cap. list_counters also accepts objNameLike and derives the objType, so users
never need to know Scouter's type taxonomy.
All tools are advertised with readOnlyHint. A diagnose_root_cause MCP prompt exposes the
recommended tool order for latency/error investigations.
Resource / token safety policy
Production Scouter can produce hundreds of thousands of XLogs in five minutes, so search_xlog
enforces guardrails (see scouter.mcp.policy.Limits):
- During streaming, it stops once the
limitor the scan cap (5,000 examined packs) is reached and closes the socket, which also stops the Collector's scan/transfer — bounding server load, network, and MCP heap together. - Without a
serviceorobjHashfilter, only windows up to 5 minutes are allowed; the absolute window cap is 24 hours. limitdefaults to 20 and is capped at 200. Results includetruncated/scanCapReachedand ahintso the caller can narrow filters instead of refetching.get_service_summaryretains no rows (only per-service counters), so it uses a higher scan cap (200,000) to cover wider windows cheaply; it reportsscanCapReached/examinedtoo.get_countercaps the per-objTypefan-out at 20 instances, and downsamples long series with a min/max scheme that preserves spikes/dips (summarymin/max/avgare computed from the full series).- Windows crossing midnight are split per calendar day (the collector partitions XLogs/counters/alerts by day), so no data is lost on either side of the boundary.
- Response text budgets: SQL text is cut at 1,500 chars, error messages at 500, thread stack traces at
4,000, env values at 500 — each with a truncation marker carrying the original length.
get_xlog_detailprofile steps are capped at 150, signalled viatotalSteps/stepsTruncated. - A single request may fan out to at most 40 collector round-trips (instances x day segments). When
client-side filters (
minElapsedMs/onlyError) discard over 99% of scanned rows, a low-selectivity hint steers the model toward server-side filters orget_summary. get_summary/get_counter_statread the collector's daily pre-aggregated data (no scanning), capped at 31 days; summary returns the top 50 rows per category.list_threadscaps at 5 alive instances and 50 thread rows each (the state histogram always covers all threads).- Per-request telemetry (passes/examined/kept/tookMs) is logged to stderr as structured
key=valuelines for post-hoc load analysis.
Internationalization
Only dynamic, user-facing output (tool error messages, result hints, notes) is localized, in English
and Korean, via messages.properties / messages_ko.properties. Static schema/tool descriptions and
structured stderr logs (key=value) remain English for a stable contract and log parsing.
Security notes
- Read-only against the Collector (no write commands are exposed).
- Credentials are injected via environment variables only (never in files or arguments as plaintext). Prefer a least-privilege / read-only Scouter account.
- Transport is plaintext TCP (the Scouter protocol has no TLS): the SHA-256 password digest, the session token, and all XLog/counter data cross the wire unencrypted. Run only inside a trusted network, or tunnel over SSH/VPN. Do not expose the collector port over the public internet.
get_xlog_detailbind parameters can contain PII. SetSCOUTER_INCLUDE_BIND_PARAMS=falseto strip them server-side (the LLM cannot re-enable them). See the env table above.get_thread_detail's live bind values (SQLActiveBindVar) obey the same kill-switch.get_object_envunconditionally masks values of keys matching password/secret/token/credential/ private — a server-side policy the LLM cannot opt out of.- stdout is reserved for JSON-RPC, so all logs go to stderr only.
License / Notice
The scouter.mcp.client package is ported from Scouter v2.20.0 client code (Apache License 2.0).
See NOTICE for details.
Known limitations
search_xlog/get_service_summaryminElapsedMs/onlyError/limitare applied client-side because the Collector has no native parameters for them.truncated=trueis a heuristic (returned count == limit) and can be a false positive.- On a session-expiry (
INVALID_SESSION) the client re-logs in once and retries the request; a second failure surfaces asSCOUTER_AUTH_FAILED(no infinite retry loop). The upstream 2-second time-delta refresh daemon is still not ported, so long-running processes may drift slightly for real-time relative queries. Absolute-epoch (historical) queries are unaffected. list_alerts/get_active_serviceswere ported from the upstream protocol and validated against a collector via the smoke tests (SmokeIT); field coverage may vary by collector version.
Scouter MCP 질문
Scouter MCP는 어떤 도구를 제공하나요?
14개 도구를 제공합니다. 예: list_objects, search_xlog, get_service_summary, get_summary, get_xlog_detail.
Scouter에 데이터를 쓰는 용도로 사용할 수 있나요?
아니요, Collector에 대한 모든 작업은 읽기 전용입니다.
SQL 바인드 파라미터의 PII를 어떻게 보호하나요?
SCOUTER_INCLUDE_BIND_PARAMS 환경 변수를 false로 설정하면 서버 측에서 바인드 파라미터를 제거할 수 있습니다.
Scouter Collector와의 연결은 안전한가요?
전송 시 TLS 없이 plaintext TCP를 사용하므로, 신뢰할 수 있는 네트워크 내부나 SSH/VPN 터널을 통해 실행하는 것을 권장합니다.
여러 개의 Scouter collector를 어떻게 처리하나요?
standalone fat jar를 사용하고 클라이언트 설정에 각 collector를 위한 별도의 항목을 추가하여 각각 고유한 환경 변수를 제공해야 합니다.