Build the Kotlin MCP operations server: tools as a secured boundary

Checkpoint tag: chapter-07-mcp-server — an MCP client can list and call get_service_status, list_recent_incidents, and get_incident; the server has no write capability yet.

What will be built

mcp-operations-server goes from empty shell to a real MCP server: Kotlin, Spring AI’s spring-ai-starter-mcp-server-webmvc with protocol=STREAMABLE, three read-only tools backed by a typed RestClient into operations-simulator, structured error results for every downstream failure mode, and a Contract-test suite that pins the simulator’s wire format.

Why it matters

An MCP server is not “tools with extra steps” — it is a capability boundary in its own process. Local @Tool methods execute inside the agent’s JVM with the agent’s privileges; a remote tool executes behind a separate security context, its own rate limits, its own audit sink, and its own deploy lifecycle. That separation is what lets Chapter 9 put ops:incident:write on a service boundary rather than on a prompt. When you hear “just give the model a function to call,” this chapter is the argument for why the function lives across a network hop.

Concepts explained

MCP primitives. Tools are model-invocable functions (what we build). Resources are addressable read-only data (ops://services/catalog) — context the client pulls. Prompts are reusable prompt templates the server can vend. Misusing them — a tool that returns documents, a prompt that mutates — confuses clients; each primitive has a semantic job.

Transports. stdio is for same-machine subprocesses (no network auth story). The old HTTP+SSE transport is deprecated in MCP SDK 2.0. Streamable HTTP is a single endpoint handling POST (requests) and GET (server->client stream). STATELESS is a Spring AI protocol variant that drops session tracking entirely — appropriate here since our tools carry all context per-call. We use STREAMABLE with deliberately stateless tool semantics; switching to protocol=STATELESS later is a config change, not a redesign.

Annotation scanning. With the starter on the classpath, @McpTool methods are discovered automatically (spring.ai.mcp.server.annotation-scanner.enabled=true by default), JSON schemas are generated from parameter types, and @McpToolParam(required=…) marks optionality. Generated schema is a description for the model — validation still happens in the method body.

Security warning (upstream docs state this plainly): the HTTP MCP endpoint is unauthenticated JSON-RPC out of the box. We run it on localhost/internal networking now and add the OAuth boundary in Chapter 9 — exposed before that chapter, this service would let anyone list and call every tool. Do not deploy intermediate checkpoints outside a private network.

Files added or changed

1
mcp-operations-server/src/main/resources/application.yml
2
mcp-operations-server/src/main/kotlin/in/o612/eng/opsagent/mcp/
3
    config/HttpClientConfig.kt
4
    simulator/SimulatorClient.kt
5
    tools/OperationsTools.kt
6
    errors/ToolError.kt
7
mcp-operations-server/src/test/kotlin/...

Complete code

1
server:
2
  port: 8081
3

4
spring:
5
  application:
6
    name: mcp-operations-server
7
  main:
8
    web-application-type: servlet
9
  ai:
10
    mcp:
11
      server:
12
        name: ops-operations-server
13
        version: "1.0.0"
14
        protocol: STREAMABLE        # STATELESS is the alternative; SSE is deprecated in MCP SDK 2.0
15
        instructions: "Read-only operational status and incident tools. Writes require approval upstream."
16
        request-timeout: 15s
17

18
simulator:
19
  base-url: ${SIMULATOR_URL:http://localhost:8082}
20
  connect-timeout: 2s
21
  read-timeout: 10s

Kotlin first: every file opens with the escaped package — `in` is a keyword.

1
package `in`.o612.eng.opsagent.mcp.config
2

3
import org.springframework.beans.factory.annotation.Value
4
import org.springframework.context.annotation.Bean
5
import org.springframework.context.annotation.Configuration
6
import org.springframework.http.client.SimpleClientHttpRequestFactory
7
import org.springframework.web.client.RestClient
8
import java.time.Duration
9

10
@Configuration
11
class HttpClientConfig {
12

13
    @Bean
14
    fun simulatorRestClient(
15
        @Value("\${simulator.base-url}") baseUrl: String,
16
        @Value("\${simulator.connect-timeout}") connectTimeout: Duration,
17
        @Value("\${simulator.read-timeout}") readTimeout: Duration,
18
    ): RestClient {
19
        val factory = SimpleClientHttpRequestFactory().apply {
20
            setConnectTimeout(connectTimeout)
21
            setReadTimeout(readTimeout)
22
        }
23
        return RestClient.builder()
24
            .baseUrl(baseUrl)
25
            .requestFactory(factory)
26
            .build()
27
    }
28
}

SimulatorClient — typed calls over the contract types from Chapter 2; the tenant travels as the simulator’s X-Tenant-Id contract header:

1
package `in`.o612.eng.opsagent.mcp.simulator
2

3
import `in`.o612.eng.opsagent.contracts.incident.IncidentDetail
4
import `in`.o612.eng.opsagent.contracts.incident.IncidentSummary
5
import org.springframework.core.ParameterizedTypeReference
6
import org.springframework.stereotype.Component
7
import org.springframework.web.client.RestClient
8

9
@Component
10
class SimulatorClient(private val http: RestClient) {
11

12
    fun serviceStatus(tenant: String, serviceId: String): ServiceStatusPayload =
13
        http.get()
14
            .uri("/sim/v1/services/{id}/health", serviceId)
15
            .header("X-Tenant-Id", tenant)
16
            .retrieve()
17
            .body(ServiceStatusPayload::class.java)
18
            ?: throw SimulatorException("empty body for service $serviceId")
19

20
    fun listIncidents(tenant: String, serviceId: String?, severity: String?, limit: Int): List<IncidentSummary> =
21
        http.get()
22
            .uri { u ->
23
                val b = u.path("/sim/v1/incidents").queryParam("limit", limit)
24
                // Kotlin can't pass String? into queryParam's vararg — set conditionally
25
                if (serviceId != null) b.queryParam("serviceId", serviceId)
26
                if (severity != null) b.queryParam("severity", severity)
27
                b.build()
28
            }
29
            .header("X-Tenant-Id", tenant)
30
            .retrieve()
31
            .body(object : ParameterizedTypeReference<List<IncidentSummary>>() {})
32
            ?: emptyList()
33

34
    fun incident(tenant: String, incidentId: String): IncidentDetail =
35
        http.get()
36
            .uri("/sim/v1/incidents/{id}", incidentId)
37
            .header("X-Tenant-Id", tenant)
38
            .retrieve()
39
            .body(IncidentDetail::class.java)
40
            ?: throw SimulatorException("incident $incidentId not found")
41

42
    class SimulatorException(message: String, cause: Throwable? = null) : RuntimeException(message, cause)
43
    data class ServiceStatusPayload(
44
        val serviceId: String, val health: String,
45
        val lastDeployment: String?, val checkedAt: String,
46
    )
47
}

The tools class. Each method validates its arguments again — schema generation describes intent to the model; it is not a validator:

1
package `in`.o612.eng.opsagent.mcp.tools
2

3
import `in`.o612.eng.opsagent.mcp.errors.ToolError
4
import `in`.o612.eng.opsagent.mcp.simulator.SimulatorClient
5
import org.springframework.ai.mcp.annotation.McpTool
6
import org.springframework.ai.mcp.annotation.McpToolParam
7
import org.springframework.stereotype.Component
8

9
@Component
10
class OperationsTools(private val simulator: SimulatorClient) {
11

12
    @McpTool(
13
        name = "get_service_status",
14
        description = "Get the current health of a service and its most recent deployment",
15
        generateOutputSchema = true,
16
    )
17
    fun getServiceStatus(
18
        @McpToolParam(description = "Service identifier, e.g. payment-gateway", required = true)
19
        serviceId: String,
20
        @McpToolParam(description = "Tenant that owns the service", required = true)
21
        tenant: String,
22
    ): Any = guard {
23
        require(serviceId.matches(Regex("[a-z0-9][a-z0-9-]{1,63}"))) { "invalid serviceId" }
24
        simulator.serviceStatus(tenant, serviceId)
25
    }
26

27
    @McpTool(
28
        name = "list_recent_incidents",
29
        description = "List recent incidents, optionally filtered by service and severity",
30
        generateOutputSchema = true,
31
    )
32
    fun listRecentIncidents(
33
        @McpToolParam(description = "Tenant scope", required = true) tenant: String,
34
        @McpToolParam(description = "Optional service filter") serviceId: String? = null,
35
        @McpToolParam(description = "SEV1..SEV4") severity: String? = null,
36
        @McpToolParam(description = "Max results, 1..100") limit: Int = 20,
37
    ): Any = guard {
38
        require(limit in 1..100) { "limit out of range" }
39
        require(severity == null || severity in setOf("SEV1", "SEV2", "SEV3", "SEV4")) {
40
            "invalid severity"
41
        }
42
        simulator.listIncidents(tenant, serviceId, severity, limit)
43
    }
44

45
    @McpTool(
46
        name = "get_incident",
47
        description = "Fetch one incident with its notes",
48
        generateOutputSchema = true,
49
    )
50
    fun getIncident(
51
        @McpToolParam(description = "Tenant scope", required = true) tenant: String,
52
        @McpToolParam(description = "Incident identifier", required = true) incidentId: String,
53
    ): Any = guard {
54
        require(incidentId.matches(Regex("inc-[0-9a-f]+"))) { "invalid incidentId" }
55
        simulator.incident(tenant, incidentId)
56
    }
57

58
    private fun guard(block: () -> Any): Any = try {
59
        block()
60
    } catch (e: IllegalArgumentException) {
61
        ToolError.of("INVALID_ARGUMENT", e.message ?: "bad arguments")
62
    } catch (e: SimulatorClient.SimulatorException) {
63
        ToolError.of("UPSTREAM_ERROR", "downstream simulator call failed")
64
    } catch (e: org.springframework.web.client.RestClientException) {
65
        ToolError.of("UPSTREAM_UNAVAILABLE", "operations backend unreachable")
66
    }
67
}

1
package `in`.o612.eng.opsagent.mcp.errors
2

3
data class ToolError(val code: String, val message: String) {
4
    companion object {
5
        fun of(code: String, message: String) = mapOf(
6
            "error" to code,
7
            "message" to message,
8
        )
9
    }
10
}

Two deliberate choices worth reading twice: errors return as structured {"error": …} payloads rather than thrown exceptions — a thrown exception surfaces to the model as an opaque protocol error; a structured result is information the agent can reason about (“upstream unavailable” → say so, don’t retry blindly). And the tool methods return Any because success returns domain types while failure returns the error map — Chapter 10’s write tools keep the same convention. Stack traces, SQL, and header values never cross into ToolError.

Commands to build and run

1
docker compose -f infra/compose/docker-compose.yml up -d postgres
2
./gradlew :operations-simulator:bootRun &
3
./gradlew :mcp-operations-server:bootRun &

Point any MCP client at http://localhost:8081/mcp — tools/list should report the three tools with generated input schemas; tools/call get_service_status {"serviceId":"payment-gateway","tenant":"acme"} returns the seeded health payload.

Automated tests

• OperationsToolsTest (unit): MockRestServiceServer behind the RestClient — happy path maps payloads; 404 → UPSTREAM_ERROR; malformed body → UPSTREAM_ERROR, not a Jackson leak; bad args → INVALID_ARGUMENT without any HTTP call.
• WireContractTest: the same fixture JSON serves both the simulator-side serialization test and the client-side parse test — the contract is pinned from both directions.
• FaultContractIT (simulator + Postgres containers): malformed fault → structured UPSTREAM_ERROR; outage → UPSTREAM_UNAVAILABLE. The fault modes from Chapter 2 pay rent starting now.
• ArchUnit addition: mcp tools package must not reference ..persistence.. (it has none — tools only reach SimulatorClient).

Failure-injection lab

Drive the three “ugly” fault modes through the real HTTP path and watch the tool results:

The point: the model sees clean structured failures. Retry policy belongs to the caller (Chapter 8’s tool policy), not to the tool that already knows the downstream is sick.

Security considerations

Tool inputs are model-originated text: serviceId/incidentId regex checks, limit bounds, and severity allowlisting run after schema generation, in code. tenant is a required argument now and becomes a JWT-derived claim in Chapter 9 — the signature already exists so that change is mechanical. The server binds to the Compose network, not the host’s public interface.

Observability checks

mcp.tool.calls + mcp.tool.errors counters labeled tool + outcome; simulator.request.duration timer; every ToolError logs a WARN with code but never arguments (arguments may contain tenant data — logs get the code, audits get the detail in Chapter 12).

Troubleshooting

• tools/list is empty: annotation scanning off or wrong package — check spring.ai.mcp.server.annotation-scanner and component scan roots.
• 404 on /mcp: the endpoint exists only under protocol=STREAMABLE with the webmvc starter; SSE puts it at /sse+/mcp/message instead.
• Kotlin package errors: in must be backticked — `in`.o612.eng.opsagent.mcp — everywhere including imports.

Checkpoint verification checklist

• tools/list shows exactly three tools with generated schemas.
• Every fault mode maps to a structured error result — zero stack traces over the wire.
• Argument validation rejects bad input before any downstream call.
• Contract tests pin both sides of the simulator wire format.

Commit message and Git tag

1
feat(mcp-server): streamable-http MCP server with read-only ops tools

git tag chapter-07-mcp-server

What comes next

Chapter 8 gives the agent the keys: the MCP client config, the tool policy registry, and the bounded loop that decides what the model may actually invoke.

Project State Ledger — chapter-07-mcp-server

• MCP server: spring-ai-starter-mcp-server-webmvc, protocol=STREAMABLE, name ops-operations-server, endpoint http://localhost:8081/mcp, request-timeout 15s
• Tools live: get_service_status, list_recent_incidents, get_incident — read-only; error convention = {"error": code, "message": safe}
• Client: SimulatorClient over RestClient (connect 2s / read 10s), X-Tenant-Id propagation
• Kotlin packages: `in`.o612.eng.opsagent.mcp.{config,simulator,tools,errors}
• Security gap (intentional, documented): no auth yet — Chapter 9; never deploy outside private networking
• Next: chapter-08-mcp-client