MCP Demo Server

A Model Context Protocol (MCP) demo server built with Spring Boot 4 and Spring AI.
It exposes calculator and date/time tools over the MCP SSE (Server-Sent Events) transport so any MCP-compatible client — including GitHub Copilot in IntelliJ IDEA — can connect to it over HTTP.

---

Table of Contents

1. Features
2. Prerequisites
3. Building the project
4. Running the server
5. Adding to GitHub Copilot in IntelliJ IDEA
6. Actuator endpoints
7. Available tools
8. Project structure
9. Extending the server
10. Troubleshooting

---

Features

Tool group	Tools
Calculator	add, subtract, multiply, divide, power, sqrt
Date & Time	getCurrentDateTime, getCurrentDate, formatDateTime, listTimezones

• Spring Boot 4.0.3 with Spring AI 1.0.0-M6
• MCP SSE transport — runs as an HTTP server (default port 8080)
• Spring Boot Actuator — health, info, and mappings endpoints to verify SSE endpoint availability
• Logs written to stdout and to mcp-server.log in the system temp directory (override with LOG_PATH)

---

Prerequisites

Requirement	Version
Java	17 or later
Maven	3.6+

Verify with:

java -version
mvn -version

---

Building the project

# Clone (if you haven't already)
git clone https://github.com/TinusJ/MCP_SERVER.git
cd MCP_SERVER

# Package into a fat JAR
mvn package -DskipTests

# Run the tests (optional)
mvn test

The fat JAR is created at:

target/mcp-server-demo-0.0.1-SNAPSHOT.jar

---

Running the server

The server starts an HTTP server on port 8080 with SSE transport:

java -jar target/mcp-server-demo-0.0.1-SNAPSHOT.jar

Once running, the following MCP endpoints are available:

Endpoint	Method	Description
/sse	GET	SSE stream — clients connect here to receive events
/mcp/message	POST	Message endpoint — clients send JSON-RPC requests here

Smoke-test

# Check the server is running
curl http://localhost:8080/actuator/health

# Connect to the SSE endpoint (Ctrl+C to stop)
curl http://localhost:8080/sse

---

Adding to GitHub Copilot in IntelliJ IDEA

Step 1 — Build and start the server

mvn package -DskipTests
java -jar target/mcp-server-demo-0.0.1-SNAPSHOT.jar

The server must be running before IntelliJ can connect.

Step 2 — Open the MCP configuration in IntelliJ

1. Open IntelliJ IDEA (2024.3 or later with the GitHub Copilot plugin installed and signed in).

2. Go to Settings → Tools → GitHub Copilot → MCP Servers
   (or search "MCP" in the Settings search bar).

3. Click + to add a new server.

4. Fill in the form:

   Field	Value
   Name	demo-mcp-server
   Transport	SSE
   URL	http://localhost:8080/sse

5. Click OK and restart the Copilot chat session.

Step 3 — Use the tools in Copilot Chat

Open Copilot Chat (Alt+Shift+C / ⌥⇧C) and try:

What is 1234 divided by 56? Use the MCP calculator.

What is today's date in the America/Chicago timezone?

Copilot will call the server tools automatically and include the results in its reply.

---

Alternative: project-level .mcp.json

The repository includes a .mcp.json at the project root.
Some MCP clients pick this up automatically:

// .mcp.json
{
  "servers": {
    "demo-mcp-server": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Note: The server must be running before the client can connect.

---

Actuator endpoints

Spring Boot Actuator is included to provide health checks and endpoint visibility.
The following actuator endpoints are exposed:

Endpoint	Description
/actuator/health	Server health status (disk space, liveness, readiness)
/actuator/info	Application info
/actuator/mappings	All registered HTTP endpoints — use this to verify /sse and /mcp/message are mapped

Verifying SSE endpoints via Actuator

# Check health
curl http://localhost:8080/actuator/health

# List all mapped endpoints (look for /sse and /mcp/message)
curl http://localhost:8080/actuator/mappings | python3 -m json.tool

---

Available tools

Calculator tools

Tool	Description	Parameters
add	Add two numbers	a, b (double)
subtract	Subtract b from a	a, b (double)
multiply	Multiply two numbers	a, b (double)
divide	Divide a by b	a, b (double, b ≠ 0)
power	Raise base to exponent	base, exponent (double)
sqrt	Square root of a number	number (double, ≥ 0)

Date & time tools

Tool	Description	Parameters
getCurrentDateTime	Current date-time (ISO-8601)	timezone (string, e.g. UTC)
getCurrentDate	Current date only	timezone (string)
formatDateTime	Reformat a date-time string	dateTimeString, inputPattern, outputPattern
listTimezones	List all valid timezone IDs	(none)

---

Project structure

src/
├── main/
│   ├── java/com/example/mcpserver/
│   │   ├── McpServerApplication.java       # Spring Boot entry point + tool registration
│   │   ├── config/
│   │   │   └── McpServerConfig.java        # ObjectMapper bean for SSE transport
│   │   └── tools/
│   │       ├── CalculatorTools.java        # @Tool-annotated calculator methods
│   │       └── DateTimeTools.java          # @Tool-annotated date/time methods
│   └── resources/
│       ├── application.properties          # SSE transport, actuator config
│       └── logback-spring.xml             # Console + file logging
└── test/
    └── java/com/example/mcpserver/
        ├── McpServerApplicationTests.java  # Unit tests for all tools
        ├── actuator/
        │   └── ActuatorEndpointTests.java  # Actuator + SSE endpoint tests
        └── config/
            └── McpServerConfigTests.java   # Configuration tests

---

Extending the server

1. Create a new @Service class in the tools package with methods annotated with @Tool.
2. Register it in McpServerApplication by adding a @Bean that returns a ToolCallbackProvider:

@Bean
public ToolCallbackProvider myToolCallbackProvider(MyTools myTools) {
    return MethodToolCallbackProvider.builder().toolObjects(myTools).build();
}

3. Rebuild (mvn package) and restart the server — the new tools appear automatically in the MCP tools/list.

---

Troubleshooting

Server fails to start

1. Check the port is available — The server runs on port 8080 by default. If the port is in use, change it in application.properties:

   server.port=9090

2. Check the log file — Logs are written to mcp-server.log in the system temp directory (e.g. /tmp on Linux/macOS, %TEMP% on Windows). Override with the LOG_PATH environment variable.

3. Verify Java is available — Run java -version in a terminal.

"Failed to connect to MCP server" in IntelliJ

1. Make sure the server is running — Unlike STDIO transport, the SSE server must be started before the client connects:

   java -jar target/mcp-server-demo-0.0.1-SNAPSHOT.jar

2. Verify the server is healthy:

   curl http://localhost:8080/actuator/health

3. Check the SSE endpoint is mapped — Use the actuator mappings endpoint to confirm /sse is registered:

   curl http://localhost:8080/actuator/mappings

4. Check the URL in IntelliJ — Make sure the URL is http://localhost:8080/sse (or the custom port if changed).

---

References

• Spring AI MCP Server documentation
• Model Context Protocol specification
• GitHub Copilot MCP support