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:

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

SQL & Database

Error & Alert Analysis

Service & Traffic

Infrastructure

Distributed Tracing

Configuration & Management

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.