Integrate Baidu Map MCP with Spring AI in Spring Boot 3 – Step‑by‑Step Guide

1. Introduction

The Spring Boot 3 practical case collection has been updated to 125 examples, available as a PDF ebook.

2. What is MCP?

Refer to the article "王炸！Spring AI+MCP 三步实现智能体开发" for an overview of MCP.

3. Spring AI MCP Client Starter Features

Manage multiple client instances

Auto‑initialize clients when enabled

Support multiple named transport methods

Integrate with Spring AI tool execution framework

Automatic resource cleanup on application context shutdown

Customizable client creation via customizers

The starter enables easy integration of third‑party MCP servers, including custom ones.

4. Communication Modes

STDIO (Standard Input/Output) : In‑process communication using stdin/stdout, suitable for local development, unit testing, or single‑node services.

SSE (Server‑Sent Events) : HTTP‑based one‑way push from server to client, ideal for real‑time data, monitoring, log streams, or notifications.

5. Add Dependencies

<code>&lt;!-- Spring AI MCP client starter (latest 1.0.0‑M7) --&gt;</code>
<code>&lt;dependency&gt;</code>
<code>  &lt;groupId&gt;org.springframework.ai&lt;/groupId&gt;</code>
<code>  &lt;artifactId&gt;spring-ai-starter-mcp-client&lt;/artifactId&gt;</code>
<code>&lt;/dependency&gt;</code>
<code>&lt;dependency&gt;</code>
<code>  &lt;groupId&gt;org.springframework.ai&lt;/groupId&gt;</code>
<code>  &lt;artifactId&gt;spring-ai-starter-mcp-client-webflux&lt;/artifactId&gt;</code>
<code>&lt;/dependency&gt;</code>
<code>&lt;dependency&gt;</code>
<code>  &lt;groupId&gt;com.alibaba.cloud.ai&lt;/groupId&gt;</code>
<code>  &lt;artifactId&gt;spring-ai-alibaba-starter&lt;/artifactId&gt;</code>
<code>  &lt;version&gt;1.0.0-M6.1&lt;/version&gt;</code>
<code>&lt;/dependency&gt;</code>

6. Configuration File (application.yml)

<code>spring:</code>
<code>  ai:</code>
<code>    dashscope:</code>
<code>      api-key: sk-xxxooo</code>
<code>      base-url: https://dashscope.aliyuncs.com/compatible-mode/v1</code>
<code>      chat:</code>
<code>        options:</code>
<code>          model: qwen-turbo</code>

This uses Alibaba's Qwen‑Turbo model.

7. MCP Server Communication Options

STDIO runs the MCP server in the same process; SSE uses HTTP push.

8. Configure Baidu Map MCP Server

https://mcp.so/zh/server/baidu-map?tab=tools

Obtain a Baidu Map API key from:

https://lbsyun.baidu.com/apiconsole/center

9. YAML Configuration for Baidu Map

<code>spring:</code>
<code>  ai:</code>
<code>    mcp:</code>
<code>      client:</code>
<code>        enabled: true</code>
<code>        type: async</code>
<code>        root-change-notification: true</code>
<code>        toolcallback:</code>
<code>          enabled: true</code>
<code>        stdio:</code>
<code>          connections:</code>
<code>            amap-maps:</code>
<code>              command: npx.cmd</code>
<code>              args:</code>
<code>                - -y</code>
<code>                - "@amap/amap-maps-mcp-server"</code>
<code>              env:</code>
<code>                AMAP_MAPS_API_KEY: xxxooo</code>

Ensure Node.js (v20) is installed; set toolcallback.enabled to true, use async client type, and configure stdio.connections for each MCP server.

10. Using the ChatClient

<code>private final ChatClient chatClient;</code>
<code>public ToolController(ChatClient.Builder aiClientBuilder, ToolCallbackProvider mcpTools) {</code>
<code>  this.chatClient = aiClientBuilder.defaultTools(mcpTools).build();</code>
<code>}</code>
<code>@GetMapping("")</code>
<code>public ResponseEntity<String> amap(String prompt) {</code>
<code>  String response = this.chatClient.prompt(prompt).call().content();</code>
<code>  return ResponseEntity.ok(response);</code>
<code>}</code>

After starting the service, the console lists the available tools provided by the connected MCP server.

11. External JSON Configuration for MCP Servers

Create mcp-servers.json in the classpath, e.g.:

<code>{</code>
<code>  "mcpServers": {</code>
<code>    "baidu-map": {</code>
<code>      "command": "npx.cmd",</code>
<code>      "args": ["-y", "@baidumap/mcp-server-baidu-map"],</code>
<code>      "env": {"BAIDU_MAP_API_KEY": "your_key_here"}</code>
<code>    }</code>
<code>  }</code>
<code>}</code>

Reference it in application.yml :

<code>spring:</code>
<code>  ai:</code>
<code>    mcp:</code>
<code>      client:</code>
<code>        enabled: true</code>
<code>        type: async</code>
<code>        root-change-notification: true</code>
<code>        toolcallback:</code>
<code>          enabled: true</code>
<code>        stdio:</code>
<code>          servers-configuration: classpath:mcp-servers.json</code>

12. Custom MCP Server Example

Define a custom server in mcp-servers.json :

<code>{</code>
<code>  "custom": {</code>
<code>    "command": "java",
<code>    "args": [</code>
<code>      "-Dspring.ai.mcp.server.stdio=true",
<code>      "-Dspring.main.web-application-type=none",
<code>      "-Dlogging.pattern.console=",
<code>      "-Dspring.main.banner-mode=off",
<code>      "-jar",
<code>      "D:\\apps\\ai_mcp_server-1.0.0.jar"
<code>    ]</code>
<code>  }</code>
<code>}</code>

Four system properties (-D…) are required for the service to start correctly.

After configuring, the custom MCP server starts via stdio, registers its tools, and can be used through the ChatClient.