{"id":28911427,"url":"https://github.com/duongminhhieu/springboot-ai-mcp-example","last_synced_at":"2026-05-05T06:38:47.874Z","repository":{"id":300378631,"uuid":"1005988872","full_name":"duongminhhieu/springboot-ai-mcp-example","owner":"duongminhhieu","description":"Example Spring AI Model Context Protocol (MCP)","archived":false,"fork":false,"pushed_at":"2025-06-21T11:19:13.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-21T11:25:35.404Z","etag":null,"topics":["mcp","mcp-client","mcp-server","mongodb","openai-api","postgresql","spring-ai","webmvc"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/duongminhhieu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-21T08:33:49.000Z","updated_at":"2025-06-21T11:23:48.000Z","dependencies_parsed_at":"2025-06-21T11:25:47.979Z","dependency_job_id":"a4b4d165-51ab-42ee-aedf-9aeb67b6dd34","html_url":"https://github.com/duongminhhieu/springboot-ai-mcp-example","commit_stats":null,"previous_names":["duongminhhieu/springboot-ai-mcp-example"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/duongminhhieu/springboot-ai-mcp-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duongminhhieu%2Fspringboot-ai-mcp-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duongminhhieu%2Fspringboot-ai-mcp-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duongminhhieu%2Fspringboot-ai-mcp-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duongminhhieu%2Fspringboot-ai-mcp-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/duongminhhieu","download_url":"https://codeload.github.com/duongminhhieu/springboot-ai-mcp-example/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duongminhhieu%2Fspringboot-ai-mcp-example/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261179044,"owners_count":23120846,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-client","mcp-server","mongodb","openai-api","postgresql","spring-ai","webmvc"],"created_at":"2025-06-21T19:08:18.464Z","updated_at":"2026-05-05T06:38:42.834Z","avatar_url":"https://github.com/duongminhhieu.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spring AI MCP Examples\nThis project demonstrates how to build and integrate a **Model-Controller-Prompt (MCP)** architecture using **Spring Boot** and **Spring AI**. It includes both an **MCP Client** and an **MCP Server**, showcasing how AI models can dynamically interact with external tools and data sources (**MongoDB**, **PostgreSQL**) to fulfill user requests in real time.\n* **Full blog:** https://blog.nashtechglobal.com/building-an-mcp-server-and-client-using-java-spring-boot-ai/\n\n## Features\n* **Data Source Integration**: Connects to a local MongoDB, PostgreSQL to perform various operations.\n* **Callable Tools with ```@Tool``` Annotation**:\nTool methods are declared using the ```@Tool``` annotation, making them discoverable and callable by the AI model at runtime.\n\n* **Tool Registration with** ```ToolCallbackProvider```: Used to expose and register tools dynamically during initialization, enabling seamless integration with Spring AI.\n\n![image](https://github.com/user-attachments/assets/17e00ada-3ad5-442e-aadf-083c4497e359)\n\n\n## How It Works \nThe MCP workflow in these examples follows these steps:\n\n![MCP Sequence Diagram](./the-whole-flow.svg)\n\n### Initial Setup and Discovery\n\n1. **Connection Initialization**\n* When the host application starts, its Chat Client sends an initialization request to the MCP Client.\n* The MCP Client establishes a connection to the configured MCP Server.\n\n2. **Capability Discovery**\n* The MCP Client asks the MCP Server: “What capabilities (tools) do you offer?”\n* The MCP Server responds with metadata describing all available tools, such as names, parameters, and descriptions.\n\n4. **Registration**\n* The MCP Client forwards this tool list to the Chat Client.\n* The Chat Client registers these tools with the AI model (LLM) so it knows what tools are available at runtime.\n* The AI model confirms: “These tools are now available for me to use.”\n\n### Processing a User Request\nLet’s say a user asks: _\"Get all products\"_\n\n1. **Need Recognition**\n* The Chat Client receives the user’s message and forwards it to the AI model.\n* The AI model analyzes the prompt and determines it requires external data (e.g., a product list from a database).\n\n2. **Tool Selection**\n* The AI model selects a registered tool that can handle the request, e.g., getProductsTool.\n\n3. **Tool Invocation**\n* The Chat Client requests the MCP Client to execute the selected tool.\n* The MCP Client sends a standardized request to the MCP Server.\n* The MCP Server executes the corresponding tool logic.\n\n4. **Data Retrieval**\n* The tool queries the necessary data source (e.g., MongoDB or PostgreSQL).\n* The database responds with the requested product data.\n* The tool sends the data back up to the MCP Server, which relays it to the MCP Client.\n\n5. **Response Generation**\n* The MCP Client returns the external data to the AI model.\n* The AI model generates a final natural language response that incorporates the data.\n\n6. **Result Delivery**\n* The Chat Client sends the completed response back to the user interface.\n* The user sees the answer: e.g., “Here are 10 products currently available.”\n\n\n## Running the Examples\n\n### Prerequisites\n\n* Java 21\n* SpringBoot 3.5.3\n* Spring AI 1.0.0\n* MongoDB\n* Postgresql\n* Docker\n* OpenAI API key\n\n### Step 1: Run Docker Compose to set up MongoDB and PostgreSQL with init data\n\n```sh\ndocker compose up -d\n```\n### Step 2: Update application.yaml with OpenAI API Key:\n* [**Open API Key**](https://github.com/duongminhhieu/springboot-ai-mcp-example/blob/master/mcp-client/src/main/resources/application.yml#L9)\n* Get OpenAI API key [here] (https://platform.openai.com/api-keys)\n\n### Step 3: Run MCP Server\n```bash\ncd mcp-server\n./mvnw spring-boot:run\n```\n### Step 4: Run MCP Client\n```bash\ncd mcp-client\n./mvnw spring-boot:run\n```\n### Step 5: Test in Postman \n\n* Test with **PostgreSQL**\n```curl\ncurl --location 'localhost:8081/chat/ask' \\\n--header 'Content-Type: text/plain' \\\n--data 'Requirement: [Postgres] In the table orders, retrieve all orders that have status COMPLETED\n\nRules:\n1. Respond strictly in JSON format, conforming to RFC 8259.\n2. The JSON structure must align with the java.util.HashMap format.\n3. Do not include explanations, comments, or any labels like ```json```.'\n```\n\n* Test with **MongoDB**\n```curl\ncurl --location 'localhost:8081/chat/ask' \\\n--header 'Content-Type: text/plain' \\\n--data 'Requirement: Retrieve all documents from the product-service collection, products table, where the price \u003e 100\n\nRules:\n1. Respond strictly in JSON format, conforming to RFC 8259.\n2. The JSON structure must align with the java.util.HashMap format.\n3. Do not include explanations, comments, or any labels like ```json```.'\n```\n| PostgreSQL | MongoDB |\n|--------------|--------------|\n| ![Screenshot 1](https://github.com/user-attachments/assets/35a3b64f-0a48-4db1-aee9-47af39c78cdc) | ![Screenshot 2](https://github.com/user-attachments/assets/99ac9786-760f-4998-bf81-4a59ae62ca60) |\n\n\n## References\n* https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html\n* Supported by ChatGPT\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduongminhhieu%2Fspringboot-ai-mcp-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fduongminhhieu%2Fspringboot-ai-mcp-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduongminhhieu%2Fspringboot-ai-mcp-example/lists"}