spring-monitoring-mcp-server

heyEdem/spring-monitoring-mcp-server

3.2

If you are the rightful owner of spring-monitoring-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Spring Boot MCP Server is an AI-Agent Monitoring Tool that leverages the Model Context Protocol (MCP) to enable AI agents to monitor Spring Boot services.

Tools
2
Resources
0
Prompts
0

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

cd /Users/Edem/Documents/IdeaProjects/spring-monitoring-mcp-server
./run-mcp-server.sh

Then type:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}

Press Enter. You should see a JSON response.

Enable debug logging

Modify the startup script to add logging flags:

exec java -Djava.util.logging.config.file=logging.properties -cp ...

Common Issues

Issue: Server not showing up in Claude Code

  • ✓ Check that the path in settings.json is absolute
  • ✓ Ensure run-mcp-server.sh is executable (chmod +x)
  • ✓ Build the project first (./mvnw clean compile)

Issue: Connection timeout when checking services

  • ✓ Verify the target service is running
  • ✓ Check the URL format (must include http:// or https://)
  • ✓ Ensure the service has Spring Boot Actuator enabled

Issue: Permission denied

  • ✓ Make sure Java 21+ is installed (java --version)
  • ✓ Check that Maven can run (./mvnw --version)

Development

Project Structure

spring-monitoring-mcp-server/
├── src/main/java/com/example/mcp/
│   ├── McpServer.java          # Main MCP server (stdio)
│   ├── Tool.java               # Tool interface
│   ├── HealthTool.java         # Health check tool
│   ├── MetricsTool.java        # Metrics tool
│   ├── controller/
│   │   └── McpController.java  # HTTP endpoints (optional)
│   ├── service/
│   │   └── MonitoringService.java
│   └── dto/
│       ├── HealthResponse.java
│       ├── MetricsResponse.java
│       └── ServiceRequest.java
├── src/main/resources/
│   ├── mcp.json                # Tool definitions
│   └── application.yaml        # Spring Boot config
├── run-mcp-server.sh           # Startup script
├── mcp-config-example.json     # Example MCP config
├── pom.xml                     # Maven dependencies
└── readME.md                   # This file

Adding New Tools

  1. Create a new class implementing the Tool interface:
public class MyNewTool implements Tool {
    @Override
    public JsonObject run(JsonObject args) {
        // Your implementation
        JsonObject result = new JsonObject();
        result.addProperty("message", "Hello from MyNewTool");
        return result;
    }
}
  1. Register it in McpServer.java:
tools.put("myNewTool", new MyNewTool());
  1. Add the tool definition in the handleListTools method with proper schema.

Running Tests

./mvnw test

Building a JAR

./mvnw clean package
java -jar target/spring-monitoring-mcp-server-0.0.1-SNAPSHOT.jar

Alternative: HTTP-based MCP (Optional)

This project also includes an HTTP-based MCP implementation running on port 8082. To use it:

./mvnw spring-boot:run

Then access:

  • GET http://localhost:8082/mcp/mcp.json - Tool manifest
  • POST http://localhost:8082/mcp/check_service_health - Health check
  • POST http://localhost:8082/mcp/get_service_metrics - Metrics

Note: Claude Code primarily uses stdio transport, so the HTTP endpoints are mainly for testing or integration with other systems.

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

License

[Add your license here]

Resources

Support

For issues or questions:

  • Open an issue on GitHub
  • Check the Claude Code documentation
  • Review the troubleshooting section above