{"slug": "building-an-ai-chat-agent-with-mcp-spring-ai", "title": "Building an AI Chat Agent with MCP, Spring AI", "summary": "A developer built an AI chat agent using Model Context Protocol (MCP), Spring AI, and Google Gemini to answer weather questions with real tool integration. The system includes a Spring Boot MCP server exposing weather and geocoding tools, and an AI agent that uses Gemini to decide when to call these tools, preventing hallucination. The project demonstrates a scalable architecture for production AI assistants.", "body_md": "Model Context Protocol (MCP) is an open standard for connecting AI apps to tools and data sources. A useful way to think about it is as a USB-C port for AI: one standard interface that lets different models plug into different capabilities without custom glue code for every integration.\n\nIn this project, we combine MCP, Spring AI, and Google Gemini to build a chat app that can answer weather questions using real tools instead of hallucinating. The system has three parts:\n\nThe result is a small but realistic architecture you can extend into a production assistant.\n\n```\nUser (Browser:3000)\n    | POST /api/chat\n    v\nAI Agent (Spring:7171) -- MCP / Streamable HTTP --> MCP Server (Spring:7170)\n    |                                               |\n    | Google Gemini                                 | Bright Sky API (weather)\n    |                                               | OpenStreetMap Nominatim (geocoding)\n    v                                               v\nChat response                                    Tool execution\n```\n\nThe full source code is available on [GitHub](https://github.com/ykpraveen/mcp-spring-sample).\n\nThe tool server is a Spring Boot application that exposes MCP tools through Spring AI's annotation scanner. It runs on port `7170`\n\nand uses Streamable HTTP for transport.\n\n```\n<dependency>\n    <groupId>org.springframework.ai</groupId>\n    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>\n</dependency>\n<dependency>\n    <groupId>org.springframework.boot</groupId>\n    <artifactId>spring-boot-starter-web</artifactId>\n</dependency>\n```\n\nWith Spring AI, a tool is just a Spring bean method annotated with `@McpTool`\n\n:\n\n```\n@Component\npublic class WeatherTool {\n\n    private final WeatherToolService weatherToolService;\n\n    public WeatherTool(WeatherToolService weatherToolService) {\n        this.weatherToolService = weatherToolService;\n    }\n\n    @McpTool(name = \"get_current_weather\",\n             description = \"Get current weather by dwd_station_id or by lat/lon\")\n    public Map<String, Object> getCurrentWeather(\n            @McpToolParam(description = \"DWD station ID\", required = false)\n            String dwd_station_id,\n            @McpToolParam(description = \"Latitude\", required = false) Double lat,\n            @McpToolParam(description = \"Longitude\", required = false) Double lon\n    ) {\n        return weatherToolService.getWeather(dwd_station_id, lat, lon);\n    }\n}\n```\n\nSpring turns that method into an MCP tool definition and publishes the parameter metadata as part of the schema. That means the model can discover the tool, understand its inputs, and decide when to call it.\n\nThe project also includes a geocoding tool that resolves city names to coordinates:\n\n```\n@McpTool(name = \"geocode_city\",\n         description = \"Convert a city name to latitude and longitude using OpenStreetMap Nominatim\")\npublic Map<String, Object> geocodeCity(\n        @McpToolParam(description = \"City name (e.g., 'Berlin', 'New York')\", required = true)\n        String cityName\n) { ... }\n```\n\nThe tools delegate the real work to services that handle validation, caching, and external API calls:\n\n```\n@Service\npublic class WeatherToolService {\n\n    public Map<String, Object> getWeather(String dwdStationId, Double lat, Double lon) {\n        // Validate the request\n        // Check the cache\n        // Call Bright Sky if needed\n        // Return a structured response\n    }\n}\n```\n\nThe key design choices are straightforward:\n\n`success`\n\n, `error_code`\n\n, and `error_message`\n\n```\nserver:\n  port: 7170\n\nspring:\n  ai:\n    mcp:\n      server:\n        name: spring-sample-mcp-server\n        version: 1.0.0\n        protocol: STREAMABLE\n        type: SYNC\n        annotation-scanner:\n          enabled: true\n\nmcp:\n  security:\n    api-key: ${MCP_API_KEY:}\n```\n\nThe `STREAMABLE`\n\nprotocol gives the agent a lightweight MCP transport, and the shared API key keeps the demo simple without adding full auth infrastructure.\n\nThe MCP server and agent share an `MCP_API_KEY`\n\n. The agent adds it automatically as an `X-API-Key`\n\nheader, and the server validates it on inbound MCP requests.\n\nThat is enough for local development and a sample project. For anything public-facing, move to Spring Security, OAuth2 or JWT, rate limiting, and a gateway in front of the MCP endpoint.\n\nThe agent is responsible for deciding when to use tools, calling Gemini, and keeping the conversation stateful.\n\n```\n<dependency>\n    <groupId>org.springframework.ai</groupId>\n    <artifactId>spring-ai-starter-model-google-genai</artifactId>\n</dependency>\n<dependency>\n    <groupId>org.springframework.ai</groupId>\n    <artifactId>spring-ai-starter-mcp-client</artifactId>\n</dependency>\n<dependency>\n    <groupId>org.springframework.boot</groupId>\n    <artifactId>spring-boot-starter-web</artifactId>\n</dependency>\n```\n\nThe agent injects the shared API key through a custom HTTP request customizer:\n\n```\n@Configuration\npublic class AgentConfiguration {\n\n    @Bean\n    McpClientCustomizer<HttpClientStreamableHttpTransport.Builder>\n    streamableHttpTransportCustomizer(AgentProperties properties) {\n        McpSyncHttpClientRequestCustomizer requestCustomizer =\n                (builder, method, uri, body, context) -> {\n                    if (StringUtils.hasText(properties.getMcpApiKey())) {\n                        builder.header(\"X-API-Key\", properties.getMcpApiKey());\n                    }\n                };\n        return (name, builder) -> builder.httpRequestCustomizer(requestCustomizer);\n    }\n}\n```\n\nThe agent keeps a small in-memory conversation history, checks whether the user message looks like a tool request, and then routes the prompt through either a plain Gemini client or a tool-enabled client.\n\n```\npublic String reply(String sessionId, String userMessage) {\n    List<ConversationTurn> history = memoryStore.history(sessionId);\n    String prompt = buildPrompt(history, userMessage);\n    boolean toolRequest = shouldUseTools(userMessage);\n    ChatClient client = toolRequest ? toolEnabledClient() : plainChatClient;\n    String answer = invokeModel(client, prompt);\n    memoryStore.appendTurn(sessionId, userMessage, answer);\n    return answer;\n}\n```\n\nThe lazy initialization is deliberate: the agent can start even if the MCP server is down, and it only initializes MCP clients when a tool request actually arrives.\n\nThe tool trigger is intentionally simple:\n\n```\nprivate static boolean shouldUseTools(String userMessage) {\n    String normalized = userMessage.toLowerCase(Locale.ROOT);\n    for (String keyword : TOOL_KEYWORDS) {\n        if (normalized.contains(keyword)) {\n            return true;\n        }\n    }\n    return false;\n}\n```\n\nThat heuristic is enough for a demo and easy to explain. In a larger system, you could replace it with a router model or intent classifier.\n\nThe model call runs on a virtual thread with a configurable timeout so the request does not hang forever if Gemini is slow or unreachable:\n\n``` js\nprivate String invokeModel(ChatClient client, String prompt) {\n    var executor = Executors.newVirtualThreadPerTaskExecutor();\n    try {\n        var future = executor.submit(() ->\n                client.prompt().user(prompt).call().content());\n        return future.get(timeoutSeconds, TimeUnit.SECONDS);\n    } catch (TimeoutException ex) {\n        throw new ResponseStatusException(HttpStatus.GATEWAY_TIMEOUT, ...);\n    } finally {\n        executor.shutdownNow();\n    }\n}\n```\n\nConversation history lives in an in-memory LRU store with a small per-session turn window. That keeps follow-up questions like \"What about tomorrow?\" grounded in the earlier exchange without introducing a database too early.\n\nThe agent configuration sets the model to `gemini-3.5-flash`\n\n, the memory limit to 20 turns per session, and the session cap to 500.\n\nThe frontend is a Vite app with a simple chat window, minimal state, and no component library.\n\n```\nconst [messages, setMessages] = useState([]);\nconst [loading, setLoading] = useState(false);\n\nconst sendMessage = async (text) => {\n    setMessages(prev => [...prev, { role: 'user', content: text }]);\n    setLoading(true);\n    const response = await fetch('/api/chat', {\n        method: 'POST',\n        headers: { 'Content-Type': 'application/json' },\n        body: JSON.stringify({ sessionId, message: text })\n    });\n    const data = await response.json();\n    setMessages(prev => [...prev, {\n        role: 'assistant',\n        content: data.reply || 'No response'\n    }]);\n    setLoading(false);\n};\n```\n\nThe Vite dev server proxies `/api/*`\n\nto the agent:\n\n```\nproxy: {\n  '/api': {\n    target: 'http://localhost:7171',\n    changeOrigin: true,\n    rewrite: (path) => path.replace(/^\\/api/, '')\n  }\n}\n```\n\nThe UI is intentionally plain: a purple gradient, responsive layout, and a smooth message list are enough to make the app feel complete without distracting from the architecture.\n\n```\nexport GEMINI_API_KEY=your_gemini_api_key\nexport MCP_API_KEY=a_shared_secret\ncd mcp-server-spring\nmvn spring-boot:run\ncd mcp-spring-agent\nmvn spring-boot:run\ncd mcp-ui\nnpm install\nnpm run dev\n```\n\nIf the user asks, \"What's the weather in Berlin?\" the flow looks like this:\n\n`geocode_city(\"Berlin\")`\n\nto get coordinates`get_current_weather(lat=52.52, lon=13.41)`\n\n**MCP separates the model from the tools.** The agent knows what tools exist and how to call them, but not how those tools are implemented. That makes the system easier to evolve.\n\n**The same server can serve different models.** Gemini is just the model in this demo. The MCP server itself can work with any compatible client.\n\n**Lazy initialization keeps the app resilient.** The agent can boot even if the MCP server is temporarily unavailable, and tool support only activates when it is actually needed.\n\nThis sample is a solid starting point. Natural next steps include:\n\n*Have you built anything with MCP and Spring AI? I'd love to hear how you approached it.*", "url": "https://wpnews.pro/news/building-an-ai-chat-agent-with-mcp-spring-ai", "canonical_source": "https://dev.to/ykpraveen/building-an-ai-chat-agent-with-mcp-spring-ai-f0n", "published_at": "2026-06-24 09:41:20+00:00", "updated_at": "2026-06-24 09:43:32.962486+00:00", "lang": "en", "topics": ["artificial-intelligence", "large-language-models", "ai-agents", "developer-tools", "ai-infrastructure"], "entities": ["Spring AI", "Google Gemini", "Model Context Protocol", "Bright Sky API", "OpenStreetMap Nominatim", "Spring Boot", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/building-an-ai-chat-agent-with-mcp-spring-ai", "markdown": "https://wpnews.pro/news/building-an-ai-chat-agent-with-mcp-spring-ai.md", "text": "https://wpnews.pro/news/building-an-ai-chat-agent-with-mcp-spring-ai.txt", "jsonld": "https://wpnews.pro/news/building-an-ai-chat-agent-with-mcp-spring-ai.jsonld"}}