📦

Spring Ops MCP

MCP server for Spring Boot Actuator — let AI assistants monitor, debug, and interact with your running Spring Boot applications

0 installs

Trust: 34 — Low

Devtools

Ask AI about Spring Ops MCP

I know everything about Spring Ops MCP. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

Spring Ops MCP

Connect AI coding assistants to your Spring Boot applications.

Spring Ops MCP exposes Spring Boot Actuator endpoints as MCP (Model Context Protocol) tools, allowing Claude Code, Cursor, Windsurf, and other AI assistants to monitor, debug, and interact with your running applications through natural language.

"Check the health of my user-service"
"Why is my app slow? Check the metrics and thread dump"
"Enable debug logging for com.myapp.auth"
"What REST endpoints does order-service expose?"
"Compare memory usage across all my services"

Why Spring Ops MCP?

Because debugging Spring Boot apps shouldn't require 10 browser tabs and a PhD in Actuator endpoints.

Before: The Old Way 😩

1. Something's wrong → open browser → localhost:8081/actuator/health
2. Copy JSON, try to read it
3. Open /actuator/metrics → "what was that metric name again?"
4. Google the metric name
5. /actuator/metrics/http.server.requests?tag=uri:/api/users&tag=method:GET
6. Need debug logs → edit application.properties → restart app
7. Reproduce the issue → finally find the problem after 30 minutes

After: The Spring Ops MCP Way 🚀

You: "My /api/users endpoint is slow, investigate"

Claude: Found the issue:
        - Response time: 2.3s (should be <200ms)
        - Root cause: Connection pool exhausted (10/10 connections)
        - Fix: spring.datasource.hikari.maximum-pool-size=20

30 minutes → 30 seconds.

Real-World Impact

Task	Before	After
Morning health check across 5 services	10 min	10 sec
Debug production performance issue	30 min	2 min
Onboard new team member to codebase	2 days	30 min
Change log level for debugging	5 min + restart	5 sec, no restart
Find why auto-config isn't working	15 min	30 sec

📖 See all use cases with examples →

Features
Quick Start
- Option A: Embedded Mode
- Option B: Standalone Mode
Configuration
Available MCP Tools
Usage Examples
Target App Requirements
Building from Source
Architecture
Roadmap
Contributing
License

Features

Category	Capabilities
🏥 Health & Status	Application health with all indicators (database, redis, disk, custom), build info, git commit
📊 Metrics	JVM memory, CPU, HTTP request stats, connection pools, Micrometer metrics with tag filtering
⚙️ Configuration	Environment properties, active profiles, Spring beans, REST endpoint mappings
📝 Logging	View log levels, change log levels at runtime (no restart needed!)
🔍 Diagnostics	Thread dumps, auto-configuration report, scheduled tasks, HTTP exchange traces
🗄️ Caches	List caches, clear specific or all caches

Quick Start

Option A: Embedded Mode (Recommended)

Add the MCP server directly to your Spring Boot application. The MCP endpoint runs alongside your app.

1. Add the dependency

Maven:

<dependency>
    <groupId>io.github.sigachev</groupId>
    <artifactId>spring-ops-mcp-starter</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle:

implementation 'io.github.sigachev:spring-ops-mcp-starter:0.1.0'

2. Configure your application

Add to application.properties:

# Your app's port
server.port=8081

# Expose Actuator endpoints
management.endpoints.web.exposure.include=health,info,metrics,env,loggers,beans,mappings,threaddump,scheduledtasks,conditions,caches
management.endpoint.health.show-details=always

# MCP server configuration
spring.ai.mcp.server.name=my-app
spring.ai.mcp.server.transport=sse
spring.ai.mcp.server.sse-path=/mcp/sse

# Auto-register this app for self-monitoring
spring.ops.mcp.register-self=true
spring.ops.mcp.self-name=my-app
spring.ops.mcp.self-port=${server.port}

Or application.yml:

server:
  port: 8081

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env,loggers,beans,mappings,threaddump,scheduledtasks,conditions,caches
  endpoint:
    health:
      show-details: always

spring:
  ai:
    mcp:
      server:
        name: my-app
        transport: sse
        sse-path: /mcp/sse
  ops:
    mcp:
      register-self: true
      self-name: my-app
      self-port: 8081

3. Start your application

./mvnw spring-boot:run

Your app now has an MCP endpoint at http://localhost:8081/mcp/sse

4. Connect Claude Code

claude mcp add my-app --transport http http://localhost:8081/mcp/sse

5. Start chatting!

You: Check the health of my-app
Claude: ✓ my-app is UP
        Components:
        - db: UP (PostgreSQL 15.3)
        - redis: UP
        - diskSpace: UP (128 GB free)

Option B: Standalone Mode

Run Spring Ops MCP as a separate service that connects to multiple Spring Boot applications.

1. Run the standalone server

Docker (recommended):

docker run -p 8090:8090 sigachev/spring-ops-mcp

Or download and run the JAR:

curl -LO https://github.com/sigachev/spring-ops-mcp/releases/latest/download/spring-ops-mcp-server.jar
java -jar spring-ops-mcp-server.jar

Or build from source:

git clone https://github.com/sigachev/spring-ops-mcp.git
cd spring-ops-mcp
./mvnw clean package -pl spring-ops-mcp-server -am -DskipTests
java -jar spring-ops-mcp-server/target/spring-ops-mcp-server-0.1.0-SNAPSHOT.jar

2. Connect Claude Code

claude mcp add spring-ops --transport http http://localhost:8090/mcp/sse

3. Register your applications

You: Register user-service at http://localhost:8081
Claude: ✓ Registered 'user-service' - connection verified!

You: Register order-service at http://localhost:8082
Claude: ✓ Registered 'order-service' - connection verified!

You: List my apps
Claude: Registered applications:
        1. user-service  → http://localhost:8081/actuator
        2. order-service → http://localhost:8082/actuator

4. Pre-configure apps (optional)

Instead of registering apps via chat, configure them in application.yml:

spring:
  ops:
    mcp:
      apps:
        user-service:
          url: http://localhost:8081
        order-service:
          url: http://localhost:8082
        payment-service:
          url: http://localhost:8083
          actuator-path: /management  # custom actuator path

Configuration

Configuration Properties

Property	Default	Description
`spring.ops.mcp.enabled`	`true`	Enable/disable Spring Ops MCP
`spring.ops.mcp.register-self`	`true`	Auto-register this app for self-monitoring
`spring.ops.mcp.self-name`	`self`	Name for self-registration
`spring.ops.mcp.self-port`	`8080`	Port for self-registration
`spring.ops.mcp.apps.<name>.url`	-	Base URL of target application
`spring.ops.mcp.apps.<name>.actuator-path`	`/actuator`	Actuator base path

Full Configuration Example

server:
  port: 8090

spring:
  application:
    name: spring-ops-mcp-server

  ai:
    mcp:
      server:
        name: spring-ops-mcp
        version: 0.1.0
        transport: sse
        sse-path: /mcp/sse

  ops:
    mcp:
      enabled: true
      register-self: false  # Standalone mode
      apps:
        # Development services
        user-service:
          url: http://localhost:8081
        order-service:
          url: http://localhost:8082
        payment-service:
          url: http://localhost:8083
        
        # Production services (with auth - coming soon)
        # prod-api:
        #   url: https://api.mycompany.com
        #   actuator-path: /management
        #   auth-type: basic
        #   username: actuator
        #   password: ${ACTUATOR_PASSWORD}

logging:
  level:
    io.github.sigachev.springopsmcp: DEBUG

Available MCP Tools

App Management

Tool	Description
`listApps`	List all registered Spring Boot applications
`registerApp(name, url, actuatorPath?)`	Register a new application for monitoring
`removeApp(name)`	Remove an application from monitoring

Health & Status

Tool	Description
`getHealth(appName)`	Get health status with all indicators (db, redis, disk, custom)
`getInfo(appName)`	Get build info, git commit, and custom info

Metrics

Tool	Description
`listMetrics(appName)`	List all available metric names
`getMetric(appName, metricName, tags?)`	Get specific metric with optional tag filtering

Common metrics:

jvm.memory.used, jvm.memory.max — JVM heap
jvm.gc.pause — Garbage collection
http.server.requests — HTTP request stats (filter by uri, method, status)
hikaricp.connections.active — Database connection pool
system.cpu.usage, process.cpu.usage — CPU
tomcat.threads.current, tomcat.threads.busy — Thread pool

Configuration

Tool	Description
`getEnv(appName, pattern?)`	Get environment properties (optionally filtered)
`getBeans(appName)`	List all Spring beans
`getMappings(appName)`	Get all REST endpoint mappings

Logging

Tool	Description
`getLoggers(appName, loggerName?)`	Get log levels for all or specific logger
`setLogLevel(appName, loggerName, level)`	Change log level at runtime

Valid log levels: TRACE, DEBUG, INFO, WARN, ERROR, OFF

Diagnostics

Tool	Description
`getThreadDump(appName)`	Get thread dump for deadlock analysis
`getScheduledTasks(appName)`	List @Scheduled tasks
`getConditions(appName)`	Get auto-configuration conditions report
`getHttpExchanges(appName)`	Get recent HTTP request traces

Caches

Tool	Description
`getCaches(appName)`	List all caches
`clearCache(appName, cacheName)`	Clear specific cache (or `"all"` for all caches)

Usage Examples

🌅 Morning Health Check

You: Good morning! How are my services doing?

Claude: Good morning! All 3 services are healthy:

┌─────────────────┬────────┬─────────────────────────┐
│ Service         │ Status │ Memory                  │
├─────────────────┼────────┼─────────────────────────┤
│ user-service    │ ✓ UP   │ 245 MB / 512 MB (48%)   │
│ order-service   │ ✓ UP   │ 312 MB / 512 MB (61%)   │
│ payment-service │ ✓ UP   │ 198 MB / 512 MB (39%)   │
└─────────────────┴────────┴─────────────────────────┘

No issues detected. All database and Redis connections healthy.

🐌 Performance Investigation

You: The checkout endpoint is slow, investigate

Claude: I'll analyze the checkout endpoint performance.

[Calling getMetric("order-service", "http.server.requests", "uri:/api/checkout")]
[Calling getMetric("order-service", "hikaricp.connections.active")]
[Calling getThreadDump("order-service")]

Found the issue:

📊 /api/checkout performance:
   - Average response time: 4.2s (should be <500ms)
   - 95th percentile: 6.8s
   - Requests/min: 847

🔍 Root cause: Database connection pool exhausted
   - HikariCP: 10/10 connections active (100% utilized)
   - 6 threads blocked waiting for connections
   - Slow query in OrderRepository.findByUserIdWithItems()

💡 Recommendations:
1. Increase pool size:
   spring.datasource.hikari.maximum-pool-size=20

2. Add database index:
   CREATE INDEX idx_orders_user_id ON orders(user_id);

3. Optimize the query — consider pagination or lazy loading for order items

🔍 Runtime Debugging

You: Enable debug logging for the auth package, I need to trace a login issue

Claude: Done! Set com.myapp.auth to DEBUG in user-service.

You: [reproduce the issue]

You: What do the logs show?

Claude: Based on the debug output, the issue is in TokenValidator:
        - JWT signature validation is passing
        - But the token's "aud" claim doesn't match your configured audience
        - Expected: "https://api.myapp.com"
        - Actual: "https://api.myapp.com/" (trailing slash)

You: OK, I see the issue. Set logging back to INFO.

Claude: Done! Set com.myapp.auth back to INFO.

🗺️ API Discovery

You: I'm new to the team. What endpoints does order-service have?

Claude: order-service exposes 12 REST endpoints:

📦 Orders
   POST   /api/orders              Create new order
   GET    /api/orders              List orders (paginated)
   GET    /api/orders/{id}         Get order by ID
   PUT    /api/orders/{id}         Update order
   DELETE /api/orders/{id}         Cancel order

💳 Payments
   POST   /api/orders/{id}/pay     Process payment
   GET    /api/orders/{id}/payment Payment status

👤 User Orders
   GET    /api/users/{userId}/orders    User's order history

📊 Analytics
   GET    /api/orders/stats        Order statistics
   GET    /api/orders/export       Export orders (CSV)

🔧 Internal
   POST   /internal/orders/sync    Sync with warehouse
   GET    /internal/health         Deep health check

⚖️ Environment Comparison

You: Compare the config between local and staging for user-service

Claude: Configuration differences between local and staging:

| Property                        | Local           | Staging              |
|---------------------------------|-----------------|----------------------|
| spring.datasource.url           | localhost:5432  | staging-db.aws:5432  |
| spring.redis.host               | localhost       | staging-redis.aws    |
| spring.kafka.bootstrap-servers  | localhost:9092  | staging-kafka.aws    |
| logging.level.root              | DEBUG           | INFO                 |
| server.tomcat.max-threads       | 200             | 400                  |
| app.feature.new-checkout        | true            | false                |

⚠️ Note: The new-checkout feature flag is enabled locally but disabled in staging.

🧹 Cache Management

You: The product catalog seems stale, clear the product caches

Claude: Found 3 product-related caches in catalog-service:
        - products (1,247 entries)
        - product-categories (89 entries)  
        - product-prices (1,247 entries)

Cleared all 3 caches. The next requests will fetch fresh data from the database.

Target App Requirements

Your monitored Spring Boot applications need:

1. Actuator Dependency

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

2. Exposed Endpoints

# Minimum for basic monitoring
management.endpoints.web.exposure.include=health,info,metrics

# Full feature set
management.endpoints.web.exposure.include=health,info,metrics,env,loggers,beans,mappings,threaddump,scheduledtasks,conditions,httpexchanges,caches

# Show health details
management.endpoint.health.show-details=always

3. (Optional) HTTP Exchanges

To enable getHttpExchanges, add:

@Bean
public HttpExchangeRepository httpExchangeRepository() {
    return new InMemoryHttpExchangeRepository();
}

Building from Source

# Clone
git clone https://github.com/sigachev/spring-ops-mcp.git
cd spring-ops-mcp

# Build all modules
./mvnw clean install

# Build server JAR only
./mvnw clean package -pl spring-ops-mcp-server -am -DskipTests

# Run standalone server
java -jar spring-ops-mcp-server/target/spring-ops-mcp-server-0.1.0-SNAPSHOT.jar

# Docker build
docker build -t spring-ops-mcp .

Architecture

spring-ops-mcp/
├── spring-ops-mcp-core/          # Core MCP tools & Actuator client
│   ├── ActuatorMcpTools.java     # 18 @Tool-annotated methods
│   ├── ActuatorClient.java       # HTTP client for Actuator endpoints
│   ├── AppRegistry.java          # Registered apps storage
│   └── RegisteredApp.java        # App model
│
├── spring-ops-mcp-starter/       # Spring Boot Starter (embedded mode)
│   ├── SpringOpsMcpAutoConfiguration.java
│   └── SpringOpsMcpProperties.java
│
└── spring-ops-mcp-server/        # Standalone server application
    └── SpringOpsMcpServerApplication.java

How It Works

┌─────────────────────────────────────────────────────────────────────┐
│                        Developer Machine                            │
│                                                                     │
│  ┌─────────────┐         ┌──────────────────────┐                  │
│  │ Claude Code │◄───────►│   spring-ops-mcp     │                  │
│  │   Cursor    │   MCP   │   (Embedded or       │                  │
│  │  Windsurf   │ Protocol│    Standalone)       │                  │
│  └─────────────┘         └──────────┬───────────┘                  │
│                                     │                               │
│                          HTTP calls to /actuator/*                  │
│                                     │                               │
│         ┌───────────────────────────┼───────────────────────┐      │
│         ▼                           ▼                       ▼      │
│  ┌─────────────┐           ┌─────────────┐          ┌─────────────┐│
│  │user-service │           │order-service│          │payment-svc  ││
│  │    :8081    │           │    :8082    │          │    :8083    ││
│  │ /actuator/* │           │ /actuator/* │          │ /actuator/* ││
│  └─────────────┘           └─────────────┘          └─────────────┘│
└─────────────────────────────────────────────────────────────────────┘

Roadmap

Authentication support — Basic auth, Bearer token, mTLS for secured Actuator endpoints
Prometheus metrics — Query Prometheus for historical data
Log streaming — Stream application logs via MCP
Kubernetes integration — Pod discovery, kubectl operations
Flyway/Liquibase — Migration status and management
Spring Cloud Config — Configuration management across environments

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

Related Projects

Spring AI — AI integration for Spring
MCP Java SDK — Official MCP SDK for Java
Model Context Protocol — The MCP specification
Spring Boot Actuator — Production-ready features

Support

Author

Mikhail Sigachev

GitHub: @sigachev
Project: spring-ops-mcp

Built with ❤️ for the Spring Boot community.

Spring Ops MCP

Reviews

Documentation

Spring Ops MCP

Why Spring Ops MCP?

Before: The Old Way 😩

After: The Spring Ops MCP Way 🚀

Real-World Impact

Table of Contents

Features

Quick Start

Option A: Embedded Mode (Recommended)

1. Add the dependency

2. Configure your application

3. Start your application

4. Connect Claude Code

5. Start chatting!

Option B: Standalone Mode

1. Run the standalone server

2. Connect Claude Code

3. Register your applications

4. Pre-configure apps (optional)

Configuration

Configuration Properties

Full Configuration Example

Available MCP Tools

App Management

Health & Status

Metrics

Configuration

Logging

Diagnostics

Caches

Usage Examples

🌅 Morning Health Check

🐌 Performance Investigation

🔍 Runtime Debugging

🗺️ API Discovery

⚖️ Environment Comparison

🧹 Cache Management

Target App Requirements

1. Actuator Dependency

2. Exposed Endpoints

3. (Optional) HTTP Exchanges

Building from Source

Architecture

How It Works

Roadmap

Contributing

License

Related Projects

Support

Author