A Spring Boot application that integrates OpenAI's GPT models with the Model Context Protocol (MCP) to provide AI-powered chat functionality with tool calling capabilities.

• OpenAI Integration: Leverages GPT-4.1-nano for intelligent chat responses
• MCP Client Support: Connects to MCP servers to extend AI capabilities with custom tools
• Tool Callbacks: Automatic tool discovery and execution via MCP protocol
• RESTful API: Simple HTTP endpoints for stateless chat interactions
• Observability: Built-in logging for prompts, completions, and errors
• Modern Stack: Spring Boot 3.5.10, Spring AI 1.1.2, Java 21

• Java 21 or higher
• Maven 3.9+
• OpenAI API key
• MCP server running on http://localhost:8081/ (or configure your own)

1. Clone the repository

   git clone <repository-url>
   cd mcp-client

2. Set up environment variables

   export OPENAI_API_KEY=your_openai_api_key_here

3. Build the project

   ./mvnw clean install

The application is configured via src/main/resources/application.yaml:

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4.1-nano
          temperature: 0.7
    mcp:
      client:
        streamable-http:
          connections:
            server1:
              url: http://localhost:8081/

• OpenAI Model: Default is gpt-4.1-nano, can be changed to other GPT models
• Temperature: Set to 0.7 for balanced creativity/determinism
• MCP Server URL: Configure the endpoint where your MCP server is running

Important: Ensure your MCP server is running on http://localhost:8081/ before starting this application.

If you encounter the error:

Factory method 'mcpSyncClients' threw exception with message: 
Client failed to initialize by explicit API call

This means the MCP server is not reachable. Verify:

1. The MCP server is running
2. The URL in application.yaml is correct
3. There are no network/firewall issues

./mvnw spring-boot:run

The application will start on http://localhost:8080

Endpoint: POST /v1/chat/stateless

Request:

curl -X POST http://localhost:8080/v1/chat/stateless \
  -H "Content-Type: text/plain" \
  -d "What is the weather like today?"

Response:

{
  "conversationId": null,
  "response": "The current weather is...",
  "timeTaken": 1250
}

Fields:

• response: The AI-generated response
• timeTaken: Time taken to process the request in milliseconds
• conversationId: Currently unused (reserved for future stateful conversations)

mcp-client/
├── src/
│   ├── main/
│   │   ├── java/com/navneet/mcp_client/
│   │   │   ├── McpClientApplication.java       # Main Spring Boot application
│   │   │   ├── constants/
│   │   │   │   └── AgentConstants.java         # System prompts and constants
│   │   │   ├── controller/
│   │   │   │   └── ChatController.java         # REST API endpoints
│   │   │   ├── models/
│   │   │   │   ├── ChatRequest.java            # Request DTOs
│   │   │   │   └── ChatResponse.java           # Response DTOs
│   │   │   └── service/
│   │   │       ├── ChatService.java            # Service interface
│   │   │       └── impl/
│   │   │           └── ChatServiceImpl.java    # Chat service implementation
│   │   └── resources/
│   │       └── application.yaml                # Application configuration
│   └── test/
│       └── java/com/navneet/mcp_client/
│           └── McpClientApplicationTests.java  # Integration tests
├── pom.xml                                      # Maven dependencies
└── README.md                                    # This file

• Spring Boot 3.5.10: Core framework
• Spring AI 1.1.2: AI integration layer
  • spring-ai-starter-mcp-client: MCP protocol support
  • spring-ai-starter-model-openai: OpenAI integration
  • @Tool annotation support: Enables automatic tool discovery and invocation by AI models
• Lombok: Reduces boilerplate code
• Spring Web: RESTful API support

Handles AI-powered chat interactions with MCP tool callbacks support.

Provides time and date utility functions exposed as tools to the AI model:

• Get current time/date in various formats
• Convert between different time representations (milliseconds, seconds, formatted strings)
• All methods are annotated with @Tool for automatic Spring AI discovery

Error: Factory method 'mcpSyncClients' threw exception

Solutions:

1. Ensure MCP server is running and accessible
2. Check the URL in application.yaml
3. Verify network connectivity to the MCP server
4. Review MCP server logs for errors

Error: Authentication or rate limit issues

Solutions:

1. Verify OPENAI_API_KEY environment variable is set correctly
2. Check your OpenAI account for API quota/credits
3. Ensure the model name is correct and accessible with your API key

Solutions:

1. Check MCP server is exposing tools correctly
2. Review application logs for tool discovery messages
3. Ensure toolcallback.enabled is set to true in configuration

./mvnw test

./mvnw clean package
java -jar target/mcp-client-0.0.1-SNAPSHOT.jar

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

This project is licensed under the terms specified in the LICENSE file.

• Spring AI Documentation
• Model Context Protocol (MCP)
• OpenAI API Documentation
• Spring Boot Documentation

navneet.prabhakar

Built with ❤️ using Spring AI and MCP