MCP Server Template — Spring Boot + Spring AI

Minimal template để tạo MCP (Model Context Protocol) server trên Spring Boot ecosystem, sẵn sàng deploy trên Kubernetes.

Naming Convention

mcp-{resource}-server

Ví dụ: mcp-account-server, mcp-payment-server, mcp-card-server.

Template mặc định dùng mcp-sample-server — thay sample bằng domain resource thực tế.

Tech Stack

Component	Version	Ghi chú
Java	21	ZGC Generational, Virtual Threads ready
Spring Boot	3.4.4	Stable GA
Spring AI	1.1.4	MCP Server Boot Starter (Streamable HTTP)
Container	Jib 3.4	Không cần Docker daemon
K8s	Kustomize	Base + overlays (dev/staging/prod)

Quick Start

./mvnw spring-boot:run

Endpoint	URL	Ghi chú
MCP Streamable HTTP	POST http://localhost:8080/mcp	Default endpoint
Health	GET http://localhost:8080/actuator/health	Actuator

Sample Tools

Template đăng ký sẵn 2 tools mẫu trong SampleTool.java:

Tool	Method	Mô tả
lookupEntity	lookupEntity(entityId)	Tra cứu entity theo ID
createEntity	createEntity(name, tags)	Tạo entity mới (name + optional tags)

Cả hai trả về SampleResponse(id, name, status, tags) — dummy data, thay bằng logic thực tế khi dùng.

Gọi thử MCP endpoint

MCP dùng JSON-RPC over HTTP. List tools:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Gọi tool lookupEntity:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{"name":"lookupEntity","arguments":{"entityId":"abc-123"}}
  }'

Project Structure

src/main/java/com/sample/mcp/server/
├── McpServerApplication.java          # Entry point
├── tool/
│   └── SampleTool.java                # @Tool annotated tools
├── service/
│   └── SampleService.java             # Business logic
├── model/                             # DTOs, domain models
└── exception/
    └── GlobalExceptionHandler.java    # ProblemDetail error responses

Tạo MCP Server mới từ template

Package convention

{group}.mcp.{resource}.server

• {group} — reverse domain của tổ chức (ví dụ: io.acme, vn.mycompany, com.example)
• {resource} — domain resource của server (ví dụ: account, transaction, payment)

Ví dụ	Package
Acme Corp — account server	io.acme.mcp.account.server
Acme Corp — order server	io.acme.mcp.order.server
Example Inc — payment server	com.example.mcp.payment.server

Các bước

# 1. Copy template
cp -r mcp-sample-server mcp-account-server
cd mcp-account-server

# 2. Rename (sed hoặc IDE refactor)
#    - pom.xml: groupId → {group}, artifactId → mcp-{resource}-server
#    - Package: com.sample.mcp.server → {group}.mcp.{resource}.server
#    - application.yml: spring.application.name → mcp-{resource}-server
#    - K8s manifests: mcp-sample-server → mcp-{resource}-server

# 3. Thay SampleTool bằng domain tool

Tạo MCP Tool mới

@Service
public class AccountTool {

    @Tool(description = "Get account balance by account number")
    public AccountBalance getBalance(
            @ToolParam(description = "Account number (10 digits)", required = true)
            String accountNumber
    ) {
        // gọi downstream API / DB
    }
}

Mỗi method @Tool tự động:

• Đăng ký thành 1 tool trong MCP server
• Generate JSON schema cho input parameters
• Serialize return type thành structured conten

... View full README on GitHub