NCAR/sage-mcp-server-example

sage-mcp-server-example

A very simple exampel of a mcp server built in spring boot.

Inspired by this example:

Connect Your AI to Everything: Spring AI's MCP Boot Starters

Model Context Protocol

Lifecycle, official documentation.

Tools, official documentation.

Spring

Streamable-HTTP MCP Servers, Spring AI documentation.

Docker Image

$ docker build -t sage-mcp-server-example:latest --build-arg APP_JAR=target/sage-mcp-server-example-1.0-SNAPSHOT.jar .

Curl Requests

MCP Initalize

Needed to establish a mcp-session-id http header attribute.

curl -v -X POST http://localhost:8080/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {
        "tools": {},
        "resources": {},
        "prompts": {}
      },
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

Output:

Note: Unnecessary use of -X or --request, POST is already inferred.
*   Trying 127.0.0.1:8080...
* Connected to localhost (127.0.0.1) port 8080 (#0)
> POST /mcp HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/8.1.2
> Accept: application/json, text/event-stream
> Content-Type: application/json
> Content-Length: 318
>
< HTTP/1.1 200
< Mcp-Session-Id: 97e6ab94-1d1d-4676-83e0-795084695d5c
< Content-Type: application/json
< Transfer-Encoding: chunked
< Date: Thu, 04 Dec 2025 19:41:28 GMT
<
* Connection #0 to host localhost left intact
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","capabilities":{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"subscribe":false,"listChanged":true},"tools":{"listChanged":true}},"serverInfo":{"name":"sage-mcp-server","version":"1.0.0"}}}

We then need to take the returned Mcp-Session-Id and use it for the next few requests.

List MCP Tools

curl -X POST http://localhost:8080/mcp \
  -H "Mcp-Session-Id: <id_from_initialize>" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {
      },
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

Example output:

{
  "jsonrpc":"2.0",
  "id":1,
  "result":{
    "tools":[
      {
        "name":"getCurrentTime",
        "title":"getCurrentTime",
        "description":"Get the time from the server.",
        "inputSchema":{
          "type":"object",
          "properties":{
            
          },
          "required":[
            
          ]
        },
        "annotations":{
          "title":"",
          "readOnlyHint":false,
          "destructiveHint":true,
          "idempotentHint":false,
          "openWorldHint":true
        }
      },
      {
        "name":"getTemperature",
        "title":"getTemperature",
        "description":"Get the temperature (in celsius) for a specific location",
        "inputSchema":{
          "type":"object",
          "properties":{
            "latitude":{
              "type":"number",
              "format":"double",
              "description":"The location latitude"
            },
            "longitude":{
              "type":"number",
              "format":"double",
              "description":"The location longitude"
            }
          },
          "required":[
            "latitude",
            "longitude"
          ]
        },
        "annotations":{
          "title":"",
          "readOnlyHint":false,
          "destructiveHint":true,
          "idempotentHint":false,
          "openWorldHint":true
        }
      }
    ]
  }
}

Call Temperature MCP Tool

curl -X POST http://localhost:8080/mcp \
  -H "Mcp-Session-Id: e4e5f549-97f7-4792-88f9-3dfa7d246257" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "getTemperature",
        "arguments": {
          "latitude": 39.9783,
          "longitude": 105.2750
        }
      },
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

Example output:

{
  "jsonrpc":"2.0",
  "id":1,
  "result":{
    "content":[
      {
        "type":"text",
        "text":"{\"current\":{\"time\":\"2025-12-04T19:45:00\",\"interval\":900,\"temperature_2m\":-4.6},\"current_units\":{\"time\":\"iso8601\",\"interval\":\"seconds\",\"temperature_2m\":\"°C\"}}"
      }
    ],
    "isError":false
  }
}

Call Current Time MCP Tool

curl -X POST http://localhost:8080/mcp \
  -H "Mcp-Session-Id: e4e5f549-97f7-4792-88f9-3dfa7d246257" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "getCurrentTime",
        "arguments": {
        }
      },
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

Example output:

{
  "jsonrpc":"2.0",
  "id":1,
  "result":{
    "content":[
      {
        "type":"text",
        "text":"\"2025-12-04T12:57:16.190039\""
      }
    ],
    "isError":false
  }
}