https://github.com/generalsparsh/mcp-spring-boot-client_v2
Spring Boot MCP client with REST endpoints to connect servers, list tools, and call JSON‑RPC methods. Java MCP client: discover tools, read resources, and invoke tools over HTTP with a clean REST API. Production‑ready MCP client in Spring Boot (HTTP + JSON‑RPC) with tool discovery and invocation.
https://github.com/generalsparsh/mcp-spring-boot-client_v2
java maven mcp model-context-protocol rest-api spring-boot testing webflux
Last synced: 2 months ago
JSON representation
Spring Boot MCP client with REST endpoints to connect servers, list tools, and call JSON‑RPC methods. Java MCP client: discover tools, read resources, and invoke tools over HTTP with a clean REST API. Production‑ready MCP client in Spring Boot (HTTP + JSON‑RPC) with tool discovery and invocation.
- Host: GitHub
- URL: https://github.com/generalsparsh/mcp-spring-boot-client_v2
- Owner: GeneralSparsh
- License: other
- Created: 2025-09-20T19:27:12.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2025-09-20T19:37:25.000Z (10 months ago)
- Last Synced: 2025-09-20T21:22:40.741Z (10 months ago)
- Topics: java, maven, mcp, model-context-protocol, rest-api, spring-boot, testing, webflux
- Language: Java
- Homepage:
- Size: 25.5 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Notice: NOTICE
Awesome Lists containing this project
README
# MCP Spring Boot Client
A comprehensive Model Context Protocol (MCP) client implementation using Spring Boot and Maven.
## Overview
This project demonstrates the ability to ingest MCP server URLs and call any API exposed by those servers using the Model Context Protocol. The implementation is designed to be generic and work with any MCP-compliant server.
## Features
- **Dynamic MCP Server Connection**: Connect to any MCP server by providing its URL
- **Generic API Calling**: Call any tool or API exposed by connected MCP servers
- **Multiple Transport Support**: HTTP and STDIO transport mechanisms
- **RESTful API**: Complete REST API for external integration
- **Comprehensive Testing**: Unit tests covering all major functionality
- **Asynchronous Operations**: Non-blocking operations for better performance
- **Configuration Management**: Flexible configuration for multiple servers
- **Error Handling**: Robust error handling and logging
## Architecture
The project follows a layered architecture:
```
├── Controller Layer (REST API)
├── Service Layer (Business Logic)
├── Model Layer (Data Transfer Objects)
├── Configuration Layer (Application Settings)
└── Transport Layer (MCP Communication)
```
## Project Structure
```
mcp-spring-boot-client/
├── src/
│ ├── main/
│ │ ├── java/com/interview/mcp/
│ │ │ ├── config/
│ │ │ │ └── McpServerProperties.java
│ │ │ ├── controller/
│ │ │ │ └── McpClientController.java
| | | ├──schema/
│ │ │ │ ├── McpSchema.java
│ │ │ ├── model/
│ │ │ │ ├── McpApiCallResult.java
│ │ │ │ ├── McpConnectionResult.java
│ │ │ │ ├── McpServerInfo.java
│ │ │ │ └── McpToolInfo.java
│ │ │ ├── service/
│ │ │ │ ├── HttpMcpServerConnection.java
│ │ │ │ ├── McpClientService.java
│ │ │ │ └── McpServerConnection.java
│ │ │ └── McpClientApplication.java
│ │ └── resources/
│ │ └── application.yml
│ └── test/
│ └── java/com/interview/mcp/
│ ├── McpClientControllerTest.java
│ └── McpClientServiceTest.java
├── pom.xml
└── README.md
```
## Key Components
### 1. McpClientService
The core service that manages MCP server connections and operations:
- Connects to MCP servers using HTTP or STDIO transport
- Discovers available tools and resources
- Executes tool calls and API requests
- Manages multiple server connections concurrently
### 2. McpClientController
REST API controller providing endpoints for:
- `/api/mcp/connect` - Connect to new MCP servers
- `/api/mcp/servers` - List connected servers
- `/api/mcp/tools` - List available tools
- `/api/mcp/tools/call` - Call specific tools
- `/api/mcp/call` - Make generic API calls
### 3. HttpMcpServerConnection
HTTP transport implementation following MCP specification:
- JSON-RPC 2.0 message format
- Tool discovery and execution
- Resource management
- Error handling and logging
## Getting Started
### Prerequisites
- Java 17 or higher
- Maven 3.8+
- An MCP-compliant server to connect to
### Build and Run
1. **Clone and build the project:**
```bash
mvn clean package
```
2. **Run the application:**
```bash
java -jar target/mcp-spring-boot-client-1.0.0.jar
```
3. **Access the application:**
- Base URL: http://localhost:8080
- Health check: http://localhost:8080/api/mcp/health
### Configuration
Configure MCP servers in `application.yml`:
```yaml
mcp:
servers:
- name: "example-server"
url: "http://localhost:3000"
transport: HTTP
```
## API Usage Examples
### 1. Connect to MCP Server
```bash
curl -X POST http://localhost:8080/api/mcp/connect \
-H "Content-Type: application/json" \
-d '{
"serverUrl": "http://localhost:3000",
"serverName": "my-server"
}'
```
### 2. List Available Tools
```bash
curl http://localhost:8080/api/mcp/tools
```
### 3. Call a Tool
```bash
curl -X POST http://localhost:8080/api/mcp/tools/call \
-H "Content-Type: application/json" \
-d '{
"serverName": "my-server",
"toolName": "calculator",
"parameters": {
"operation": "add",
"a": 5,
"b": 3
}
}'
```
### 4. Make Generic API Call
```bash
curl -X POST http://localhost:8080/api/mcp/call \
-H "Content-Type: application/json" \
-d '{
"serverUrl": "http://localhost:3000",
"method": "GET",
"endpoint": "/api/data"
}'
```
## Testing
Run unit tests:
```bash
mvn test
```
The test suite includes:
- Service layer tests for MCP operations
- Controller tests for REST API endpoints
- Integration tests for end-to-end scenarios
## Model Context Protocol Compliance
This implementation follows the MCP specification:
- JSON-RPC 2.0 message format
- Standard MCP methods (initialize, tools/list, tools/call, etc.)
- Proper error handling and status codes
- Support for both HTTP and STDIO transports
## Design Principles
- **Generic Implementation**: Works with any MCP-compliant server
- **Scalable Architecture**: Supports multiple concurrent server connections
- **Extensible Design**: Easy to add new transport mechanisms
- **Production Ready**: Comprehensive error handling and logging
- **Testable Code**: High test coverage with unit and integration tests
## Future Enhancements
- WebSocket transport support
- Server-sent events for real-time updates
- Connection pooling and load balancing
- Advanced authentication mechanisms
- Monitoring and metrics integration
## Author
Sparsh Sahu
## License
MIT License