Scouter MCP

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 carriestxid/gxid/objName/endTimeIso, which you can use as keys to cross-analyze with other observability tools such as OpenSearch or Datadog.

Java 17. It reusesscouter-commonand ports thescouter.webappnet/server classes into thescouter.mcp.clientpackage. MCP uses the Java SDK 2.0.0 stdio transport. All operations against the Collector are read-only.

./gradlew shadowJar # output: build/libs/scouter-mcp-<version>-all.jar

The.mcpbbundle 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.mcpbbundle from theGitHub Releasefor 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, seeMultiple collectors.

The official release shipsone.mcpbbundle (one-click install, a single collector) plus the standalone fat jar. A.mcpbdefines 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/portanduser/password) — use the jar directly and add one entry per collector:
- Downloadscouter-mcp-<version>-all.jarfrom theGitHub Release.
- Add onemcpServersentry 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.

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.objNameLikesolves this: a case-insensitive fragment is resolved toallmatching 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 isNOT_FOUNDwith acandidateshint listing actual objNames so the caller can self-correct in one step.

Scouter service names look like/api/order/.../search-order-info-grade<POST>, but users type "GET orderDetail" or "order info grade". Theservicefilter 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 asserviceCandidates, ordered by traffic. One retry with an exact name resolves it.

service/login/ip/descuse substring match by default (server-sideStrMatch), so a short token likesearch-order-info-gradematches/api/order/ext/order-info/search-order-info-grade<POST>.objNameLike/login/ip/desccount as server-side filters, so they relax the 5-minute unfiltered-window cap.list_countersalso acceptsobjNameLikeand derives the objType, so users never need to know Scouter's type taxonomy.

All tools are advertised withreadOnlyHint. Adiagnose_root_causeMCP prompt exposes the recommended tool order for latency/error investigations.

Production Scouter can produce hundreds of thousands of XLogs in five minutes, sosearch_xlogenforces guardrails (seescouter.mcp.policy.Limits):

- During streaming, it stops once thelimitor 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 aserviceorobjHashfilter, 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 structuredkey=valuelines for post-hoc load analysis.

Only dynamic, user-facing output (tool error messages, result hints, notes) is localized, in English and Korean, viamessages.properties/messages_ko.properties. Static schema/tool descriptions and structured stderr logs (key=value) remain English for a stable contract and log parsing.

- 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_envunconditionallymasks 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.

Thescouter.mcp.clientpackage is ported from Scouter v2.20.0 client code (Apache License 2.0). SeeNOTICEfor details.
- 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.

Get web performance tests and data in your AI workflow