Java MCP Expert Agent

Builds production-ready Model Context Protocol servers in Java using the official SDK with reactive programming and Spring Boot integration.

When to Use This Agent

Choose this agent when you need to:

• Implement MCP servers with tool definitions, resource handlers, and prompt templates using the Java SDK
• Configure reactive pipelines with Project Reactor for async tool execution and streaming
• Integrate MCP capabilities into Spring Boot apps using starter dependencies

Consider alternatives when:

• You need an MCP server in TypeScript or Python rather than Java
• You require only an MCP client without server-side tool hosting

Quick Start

Configuration

Copy
name: java-mcp-expert-agent
type: agent
category: web-tools

Example Invocation

Copy
claude agent:invoke java-mcp-expert-agent "Create an MCP server with a database query tool and file resource handler"

Example Output

Created: src/main/java/com/example/mcp/McpServerConfig.java
  - McpServer builder with tools + resources capabilities
  - StdioServerTransport configuration
Created: src/main/java/com/example/mcp/tools/DatabaseQueryTool.java
  - JSON Schema: query (string, required), limit (integer)
  - Reactive handler on Schedulers.boundedElastic
  - Timeout: 30s with error mapping
Created: src/main/java/com/example/mcp/resources/FileResourceHandler.java
  - URI pattern: file:///{path}
  - Subscription tracking with ConcurrentHashMap

Core Concepts

MCP Server Capabilities

Aspect	Details
Tools	Named operations with JSON Schema inputs, reactive Mono<ToolResponse> handlers
Resources	URI-addressable data sources with read handlers and change notifications
Prompts	Template-based conversation starters with typed arguments
Transports	Stdio for CLI, HTTP via JDK HttpClient, Servlet, WebFlux for reactive
Reactive Model	Project Reactor Mono (single) and Flux (stream) with backpressure

MCP Server Architecture

+-------------------+     +-------------------+     +------------------+
|  MCP Client       |<--->|  Transport Layer  |<--->|  MCP Server      |
|  (Claude, IDE)    |     |  (Stdio / HTTP)   |     |  (Java SDK)      |
+-------------------+     +-------------------+     +------------------+
                                                          |
              +-------------------+     +-----------------+
              |  Resource         |     |  Tool           |
              |  Handlers         |     |  Handlers       |
              +-------------------+     +-----------------+

Configuration

Parameter	Type	Default	Description
java_version	string	"17"	Minimum Java: "17" (LTS) or "21" (virtual threads)
transport_type	string	"stdio"	Transport: "stdio", "http", "servlet", or "webflux"
spring_boot	boolean	false	Enable Spring Boot starter auto-configuration
reactor_scheduler	string	"boundedElastic"	Scheduler for blocking: "boundedElastic" or "parallel"
json_library	string	"jackson"	JSON backend via mcp-jackson2 module

Best Practices

1. Offload Blocking to boundedElastic - JDBC, file I/O, and external API calls block threads. Always wrap with Mono.fromCallable(...).subscribeOn(Schedulers.boundedElastic()) to prevent stalling the event loop.

2. Define Precise JSON Schemas - Use the fluent JsonSchema.object() builder with required properties and type constraints. Vague schemas cause runtime ClassCastExceptions when clients send unexpected types.

3. Map Errors Gracefully - Use .onErrorResume(SpecificException.class, e -> Mono.just(ToolResponse.error()...)) for known exceptions. Unhandled exceptions become opaque transport failures.

4. Track Subscriptions with Concurrent Collections - Maintain ConcurrentHashMap.newKeySet() of active resource subscription URIs for targeted change notifications instead of noisy broadcasts.

5. Use Sync Facade for Simple Tools - For quick operations without I/O, use server.toSyncServer() with plain return values. This reduces reactive boilerplate without sacrificing performance.

Common Issues

1. Thread Starvation Without subscribeOn - Calling blocking JDBC inside a Mono without specifying a scheduler executes on the event loop thread, blocking all concurrent tool invocations under load.

2. Mono.empty Causes Client Hang - A handler returning Mono.empty() on certain paths causes the MCP client to wait indefinitely. Always return a ToolResponse from every execution path.

3. Jackson Deserialization Failures - Missing optional properties cause exceptions if POJOs expect non-null fields. Configure FAIL_ON_UNKNOWN_PROPERTIES to false and use Optional<T> for optional parameters.