Scouter MCP Server

한국어

An MCP (Model Context Protocol) server that connects AI agents to Scouter APM, enabling natural-language queries against real-time application performance data.

Ask your AI assistant things like "What's the slowest SQL in the last hour?" or "Why is TPS dropping?" and get answers grounded in live monitoring data.

Features

• 32 tools covering the full Scouter API surface
• Dual protocol — connects via HTTP (REST API) or TCP (binary protocol)
• Automatic hash resolution — SQL queries, service names, and error messages are decoded from Scouter's internal hash IDs to human-readable text
• Executable SQL — transaction profiles include SQL with bind parameters substituted, ready for EXPLAIN ANALYZE
• Zero external dependencies — only @modelcontextprotocol/sdk and zod

Quick Start

Using npx (no install needed)

npx scouter-mcp-server

Or install from source

cd scouter.mcp
npm install
npm run build

Configure

Set environment variables to point at your Scouter collector:

| Variable | Description | Default | |----------|-------------|---------| | SCOUTER_API_URL | Scouter webapp REST API base URL | http://localhost:6180 | | SCOUTER_API_ID | API login ID | | | SCOUTER_API_PASSWORD | API login password | | | SCOUTER_TCP_HOST | TCP direct connection host | | | SCOUTER_TCP_PORT | TCP direct connection port | 6100 | | SCOUTER_ENABLE_WRITE | Set to true to enable write tools | (disabled) | | SCOUTER_MASK_PII | Set to false to disable PII masking in responses (IP, login, userAgent, SQL params) | true |

HTTP mode (recommended) — set SCOUTER_API_URL. Supports all 32 tools (write tools require SCOUTER_ENABLE_WRITE=true). TCP mode — set SCOUTER_TCP_HOST. Lightweight, no webapp needed, but some admin tools are unavailable.

Note: By default, only read-only tools (25) are registered. To enable write tools (set_configure, set_alert_scripting, manage_kv_store, manage_shortener, control_thread, remove_inactive_objects), set SCOUTER_ENABLE_WRITE=true.

3. Add to your MCP client

Claude Desktop (claude_desktop_config.json):

HTTP mode:

{
  "mcpServers": {
    "scouter": {
      "command": "npx",
      "args": ["-y", "scouter-mcp-server"],
      "env": {
        "SCOUTER_API_URL": "http://your-scouter-server:6180",
        "SCOUTER_API_ID": "admin",
        "SCOUTER_API_PASSWORD": "your-password"
      }
    }
  }
}

TCP mode:

{
  "mcpServers": {
    "scouter": {
      "command": "npx",
      "args": ["-y", "scouter-mcp-server"],
      "env": {
        "SCOUTER_TCP_HOST": "your-scouter-server",
        "SCOUTER_TCP_PORT": "6100",
        "SCOUTER_API_ID": "admin",
        "SCOUTER_API_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code (use -s user to register globally across all projects):

# HTTP mode
claude mcp add scouter -s user \
  -e SCOUTER_API_URL=http://your-scouter-server:6180 \
  -e SCOUTER_API_ID=admin \
  -e SCOUTER_API_PASSWORD=your-password \
  -- npx -y scouter-mcp-server

# TCP mode
claude mcp add scouter -s user \
  -e SCOUTER_TCP_HOST=your-scouter-server \
  -e SCOUTER_TCP_PORT=6100 \
  -e SCOUTER_API_ID=admin \
  -e SCOUTER_API_PASSWORD=your-password \
  -- npx -y scouter-mcp-server

To update the configuration later, edit ~/.claude.json directly or remove and re-add:

claude mcp remove scouter -s user
claude mcp add scouter -s user \
  -e SCOUTER_TCP_HOST=new-host \
  -e SCOUTER_TCP_PORT=6100 \
  -e SCOUTER_API_ID=admin \
  -e SCOUTER_API_PASSWORD=your-password \
  -- npx -y scouter-mcp-server

Tools

Performance Investigation

| Tool | Description | |------|-------------| | get_system_overview | Real-time snapshot — TPS, response time, CPU, heap, active services, alerts | | diagnose_performance | Automated multi-step diagnosis with severity-ranked findings | | get_counter_trend | Historical counter values (TPS, ElapsedTime, CPU, etc.) over time | | search_transactions | Find slow/error transactions by time range, service, IP, login | | get_transaction_detail | Full transaction profile with executable SQL and API call traces | | list_active_services | Currently running requests with thread state |

SQL & Database

| Tool | Description | |------|-------------| | get_sql_analysis | SQL performance ranking — count, elapsed, errors, % of total | | lookup_text | Resolve hash IDs to SQL/service/error text |

Error & Alert Analysis

| Tool | Description | |------|-------------| | get_error_summary | Errors ranked by frequency with per-service error rates | | get_alert_summary | Alert statistics within a time range | | get_alert_scripting | Read alert rule scripts | | set_alert_scripting | Create/update alert rules (HTTP only) |

Service & Traffic

| Tool | Description | |------|-------------| | get_service_summary | Service-level stats with external API call breakdown | | get_ip_summary | Request distribution by client IP | | get_user_agent_summary | Request distribution by browser/user-agent | | get_visitor_stats | Unique visitor counts (realtime, daily, hourly) | | get_interaction_counters | Service-to-service call relationships |

Infrastructure

| Tool | Description | |------|-------------| | get_thread_dump | Thread dump with stack traces | | get_host_info | Host-level top processes and disk usage | | get_agent_info | Agent runtime info (threads, env, sockets) | | get_server_info | Collector server metadata and counter model |

Distributed Tracing

| Tool | Description | |------|-------------| | get_distributed_trace | Trace a transaction across services via GXID | | get_realtime_xlogs | Real-time transaction stream | | get_raw_xlog | Raw XLog data (5 query modes) | | get_raw_profile | Raw profile steps with hash IDs |

Configuration & Management

| Tool | Description | |------|-------------| | get_configure | Read server/agent configuration | | set_configure | Modify configuration (HTTP only) | | control_thread | Suspend/resume/interrupt threads | | manage_kv_store | Global, namespaced, and private key-value store | | manage_shortener | URL shortener service | | remove_inactive_objects | Clean up dead agents (HTTP only) |

Architecture

┌─────────────────────────────┐
│  AI Agent (Claude, etc.)    │
│  "Why is the app slow?"     │
└──────────┬──────────────────┘
           │ MCP (stdio)
┌──────────▼──────────────────┐
│  Scouter MCP Server         │
│  ┌────────────────────────┐ │
│  │ Tool Hub (31 tools)    │ │
│  │ Hash Resolution Engine │ │
│  │ SQL Param Binding      │ │
│  └────────────────────────┘ │
└──────────┬──────────────────┘
           │ HTTP REST or TCP Binary
┌──────────▼──────────────────┐
│  Scouter Collector Server   │
│  + Webapp (REST API)        │
└──────────┬──────────────────┘
           │
    ┌──────▼──────┐
    │ Java Agents │
    │ Host Agents │
    └─────────────┘

Project Structure

scouter.mcp/
├── index.ts                 # Entry point — stdio transport + SIGINT handler
├── server/
│   └── index.ts             # createServer() factory → { server, cleanup }
├── tools/
│   ├── index.ts             # registerAllTools() hub — explicit imports of all tools
│   ├── shared-utils.ts      # Hash resolution, SQL param binding
│   └── ... (31 tool files)
├── client/
│   ├── index.ts             # Client facade — exports client, jsonStringify, catchWarn
│   ├── interface.ts         # ScouterClient interface + types
│   ├── http.ts              # HTTP/REST implementation
│   └── tcp.ts               # TCP binary protocol implementation
├── protocol/
│   ├── tcp-connection.ts    # TCP connection with handshake/auth
│   ├── packs.ts             # Scouter binary pack definitions
│   ├── values.ts            # Value type serialization
│   ├── data-input.ts        # Binary deserialization
│   ├── data-output.ts       # Binary serialization
│   └── constants.ts         # Protocol constants
├── time-utils.ts            # Time parsing utilities
├── __tests__/               # Vitest test suites
├── vitest.config.ts         # Test config (v8 coverage)
├── tsconfig.json            # NodeNext modules
└── package.json

Development

npm run dev          # Watch mode (tsc --watch)
npm test             # Run tests
npm run test:coverage  # Coverage report
npm run build        # Production build

Adding a New Tool

1. Create tools/my-tool.ts exporting register(server: McpServer) with server.registerTool()
2. Add import { register as registerMyTool } from "./my-tool.js" to tools/index.ts
3. Call registerMyTool(server) inside registerAllTools()
4. Use shared-utils.ts for hash resolution and SQL binding

Protocol Details

HTTP Mode

Connects to Scouter's webapp REST API (/scouter/v1/*). Supports all 32 tools including write operations (configuration, alert scripting, thread control).

Authentication: username/password login with bearer token auto-refresh on 401.

TCP Mode

Connects directly to the Scouter collector using the binary protocol (port 6100). Handshake uses NetCafe magic number (0xCAFE2001), login with SHA-256 hashed password.

Supports read-only tools. Write operations (config, alerts, KV store, URL shortener) throw UnsupportedOperationError.

Text hash resolution uses GET_TEXT_100 command with per-date caching.

Requirements

• Node.js >= 18
• Scouter Collector >= 2.x with webapp enabled (for HTTP mode)

License

Apache License 2.0 — same as the Scouter project.