Spring Boot MCP Server – AI-Agent Monitoring Tool

Let AI agents monitor your Spring Boot services using the Model Context Protocol (MCP).

This is a production-ready MCP server that allows AI agents (Claude Code, etc.) to:

• ✅ Check if a service is UP/DOWN
• ⏱️ Measure response time
• 📊 Fetch Spring Boot Actuator metrics

Features

• Spring Boot Integration - Leverages Actuator endpoints
• MCP Protocol Compliant - Full JSON-RPC 2.0 implementation
• Stdio Transport - Works seamlessly with Claude Code
• Zero-config health & metrics checks
• Fast - Uses Java HttpClient with configurable timeouts
• Comprehensive Error Handling - Proper error codes and messages
• Logging - Built-in Java logging for debugging

Quick Start with Claude Code

1. Prerequisites

• Java 21 or higher
• Maven (or use the included mvnw wrapper)
• Claude Code CLI

2. Build the Project

cd /absolute/path/to/spring-monitoring-mcp-server
./mvnw clean compile

3. Configure Claude Code

Add this MCP server to your Claude Code settings file (~/.claude/settings.json):

{
  "mcpServers": {
    "spring-monitoring": {
      "command": "/absolute/path/to/spring-monitoring-mcp-server/run-mcp-server.sh"
    }
  }
}

Or create a local .mcp.json file in your project:

{
  "mcpServers": {
    "spring-monitoring": {
      "command": "/absolute/path/to/spring-monitoring-mcp-server/run-mcp-server.sh"
    }
  }
}

4. Test It!

1. Using the actuator endpoints to make http calls

 http://localhost:3450/tools/checkServiceHealth

{
  "serviceUrl": "http://localhost:{your-running-application-port}"
}

or test the metrics endpoint:

 http://localhost:3450/tools/getServiceMetrics

{
  "serviceUrl": "http://localhost:{your-running-application-port}"
}

2 - Using Claude Code

Start Claude Code and ask:

Check the health of my service at http://localhost:{your-running-application-port}

or

Get metrics from http://localhost:{your-running-application-port}

Available Tools

1. checkServiceHealth

Check if a Spring Boot service is up and measure its response time.

Input:

{
  "serviceUrl": "http://localhost:{your-running-application-port}"
}

Output:

{
  "serviceUrl": "http://localhost:{your-running-application-port}",
  "status": "UP",
  "statusCode": 200,
  "responseTimeMs": 45,
  "body": {
    "status": "UP",
    "components": {...}
  }
}

2. getServiceMetrics

Fetch Spring Boot Actuator metrics from a service.

Input:

{
  "serviceUrl": "http://localhost:{your-running-application-port}"
}

Output:

{
  "serviceUrl": "http://localhost:{your-running-application-port}",
  "status": "UP",
  "statusCode": 200,
  "responseTimeMs": 32,
  "metrics": {
    "names": ["jvm.memory.used", "http.server.requests", ...]
  }
}

Architecture

This MCP server uses a stdio transport model:

Claude Code <--JSON-RPC 2.0--> MCP Server <--HTTP--> Your Spring Boot Services
              (stdio)                         (REST)

Components

1. McpServer.java - Main stdio MCP server implementing JSON-RPC 2.0 protocol
2. HealthTool.java - Tool for checking service health via /actuator/health
3. MetricsTool.java - Tool for fetching metrics via /actuator/metrics
4. run-mcp-server.sh - Startup script that builds and launches the server

Protocol Flow

1. Claude Code launches the MCP server via the startup script
2. Server reads JSON-RPC requests from stdin
3. Server processes requests (initialize, tools/list, tools/call)
4. Server makes HTTP calls to target Spring Boot services
5. Server writes JSON-RPC responses to stdout

Troubleshooting

Check if the server is configured

claude mcp list

You should see spring-monitoring in the list.

Test the startup script manually

... [View full README on GitHub](https://github.com/heyEdem/spring-monitoring-mcp-server#readme)