Same hexagon, same tools, same k6 scenario, two runtimes. Both servers handled the agent burst with zero failures and stayed far below the SLO. Go answered with a ~5× lower p95 (2.6 ms vs 13.8 ms), and the most interesting finding was where Java spends its time: not in the tool.

⭐ Code: orders-mcp (Java) · orders-mcp-go (Go) · Part 6 of MCP in Production: Java & Go

🧪 1. The setup

⚠️ Read this as a laptop benchmark, not a lab result. One run per server, server and k6 on the same machine, Docker sharing the CPU. Good enough to see the shape of the difference, not to quote to the decimal.

⚡ 2. Latency

Both servers pass the thresholds with 10× headroom: the SLO is 150 ms and the worst p95 is 14 ms. For an agent waiting on an LLM that takes seconds per turn, either number is invisible.

Still, Go's p95 is ~5× lower and its worst request (118 ms) is less than half of Java's (288 ms). The JVM's max is very likely the first seconds of the run, while the JIT is still compiling the hot paths.

🔬 3. Where Java spends the time

This is the part I didn't expect. The mcp.tool.duration timer from part 4 measures only the tool: the use case and the JDBC query. Prometheus says its p95 was between 2 and 5.5 ms during the runs. k6, measuring the whole HTTP round trip, says 13.8 ms.

So most of Java's latency is outside the hexagon: the security filter chain, the MCP transport and serialization. The domain and the database are fast in both languages. That's a useful result in itself:

• if you want to optimize the Java server, profile the edge, not the domain;
• the hexagon did its job: the core is cheap, the adapters are where the framework cost lives;
• this is exactly why part 4 records a per-tool timer and why k6 measures end to end. With only one of them, you'd draw the wrong conclusion.

🧵 4. Concurrency: VUs as a symptom

ramping-arrival-rate sends requests at a fixed rate, so throughput is the same by design (~96 req/s for both). What changes is how many virtual users k6 needs to keep that rate:

Slower responses keep each VU busy longer, so k6 had to spin up 57 VUs for Java vs 20 for Go, and still dropped 9 iterations on Java while it scaled up. In production terms: the same agent traffic keeps ~3× more requests in flight against the Java server.

🧠 5. Startup and memory

The Java numbers come from Micrometer (jvm_memory_used_bytes), which counts heap and non-heap but not the full process footprint (RSS is higher). I didn't capture Go's startup and memory in this round; I'll add them in a follow-up, measured the same way for both, including RSS.

What I can say from the run: at ~100 req/s neither server was stressed. Java peaked at ~6% CPU with a ~70 MB heap on a 4 GB max. This scenario measures latency under a realistic agent burst, not the breaking point.

⚖️ 6. So, Java or Go for an MCP server?

My take after building both:

• Go wins on raw latency and efficiency, and it makes everything explicit. Great when the MCP server is a small, independently deployed edge service.
• Java costs ~11 ms more per call here, and in exchange you get Spring Security's OAuth 2.1 support (including RFC 9728 out of the box), @McpTool, Micrometer and the rest of the ecosystem your team already runs in production.
• The architecture mattered more than the language. Same ports, same contract tests, same metric names: that's what made this comparison possible at all.

💡 Lessons learned

1. Benchmark the load generator too. My first Go run had 0.84% failures, caused by k6 sharing one MCP session across VUs, not by the server.
2. Measure inside and outside. The per-tool timer and the k6 round trip told two different, both true, stories.
3. Arrival-rate tests hide throughput differences on purpose. Look at VUs, dropped iterations and latency instead, or run a stress test to find the ceiling.
4. Warm-up is real on the JVM. Report max latency with that in mind, or run a warm-up phase before measuring.
5. Below the SLO, the decision is about the team and the platform, not about milliseconds.

🚀 What's next

• A stress scenario that pushes both servers toward their limit (thousands of req/s) to find where each one breaks.
• Startup and RSS measured side by side, plus a Java run with GraalVM native image and virtual threads to see how much of the gap closes.

⭐ Code: orders-mcp · orders-mcp-go

👋 I'm Carmelo Buelvas, a Senior Backend Engineer writing about Java, Go and AI agents in production. Let's connect on LinkedIn.

Same server, same tools, same scopes, same metrics, different language. I rebuilt the hexagonal MCP server from parts 1–4 in Go, with the official MCP Go SDK, to see what changes and what doesn't when the architecture stays the same.

⭐ Code: github.com/cbuelvasc/orders-mcp-go · Java version: orders-mcp · Part 5 of MCP in Production: Java & Go

⬡ Same hexagon, different idioms

The core uses only the standard library. Not by discipline: a test fails if anyone imports something else.

🧱 1. The domain: values, not annotations

Value objects are structs with an unexported field and a constructor that validates, so an invalid OrderID simply cannot exist:

// OrderID is a value object: it can only hold a valid id like ORD-1042.
type OrderID struct{ value string }

// ParseOrderID normalizes and validates an order id.
func ParseOrderID(raw string) (OrderID, error) {
	v := strings.ToUpper(strings.TrimSpace(raw))
	if !orderIDFormat.MatchString(v) {
		return OrderID{}, fmt.Errorf("%w: invalid order id %q, expected format ORD-<digits>", ErrInvalidInput, v)
	}
	return OrderID{v}, nil
}

func (id OrderID) String() string { return id.value }

The business rule lives in the aggregate. Cancel returns a new Order (value receiver), the same immutability idea as the Java record:

// Cancel applies the business rule: only orders that have not shipped can be cancelled.
// It returns a new Order; the receiver is not modified.
func (o Order) Cancel(now time.Time) (Order, error) {
	if !o.Status.IsCancellable() {
		return Order{}, fmt.Errorf("%w: order %s cannot be cancelled because it is %s",
			ErrCannotBeCancelled, o.ID, o.Status)
	}
	o.Status = StatusCancelled
	o.UpdatedAt = now
	return o, nil
}

Ports are plain interfaces. In Go they usually sit next to the code that uses them, which here is the domain itself:

// --- Inbound ports (driving side): what the adapters can ask the core to do ---

// FindOrder returns one order or ErrOrderNotFound.
type FindOrder interface {
	FindByID(ctx context.Context, id OrderID) (Order, error)
}

// ListRecentOrders returns the newest orders of a customer. The limit is clamped by the core.
type ListRecentOrders interface {
	ListRecent(ctx context.Context, customer CustomerID, limit int) ([]Order, error)
}

// CancelOrder cancels an order that has not shipped yet.
type CancelOrder interface {
	Cancel(ctx context.Context, id OrderID) (Order, error)
}

// --- Outbound port (driven side): what the core needs from the outside world ---

// OrderRepository is implemented by PostgreSQL in production and by an in-memory fake in tests.
type OrderRepository interface {
	FindByID(ctx context.Context, id OrderID) (Order, bool, error)
	FindRecentByCustomer(ctx context.Context, customer CustomerID, limit int) ([]Order, error)
	Save(ctx context.Context, order Order) error
}

Errors are values. The adapters translate them with errors.Is: ErrOrderNotFound becomes a 404 in REST and a readable tool error in MCP.

🤖 2. The MCP adapter, split in two

This is the design choice I like most in the Go version:

tools.go is plain Go: inputs, outputs, scope checks, validation and metrics. The JSON schema the model sees is generated from struct tags:

type FindOrderInput struct {
	OrderID string `json:"orderId" jsonschema:"Order id, format ORD-<digits>, e.g. ORD-1042"`
}

func (t *Tools) CancelOrder(ctx context.Context, scopes []string, in CancelOrderInput) (OrderView, error) {
	return observe(t.metrics, "cancelOrder", func() (OrderView, error) {
		if err := require(scopes, ScopeWrite); err != nil {
			return OrderView{}, err
		}
		id, err := domain.ParseOrderID(in.OrderID)
		if err != nil {
			return OrderView{}, err
		}
		o, err := t.cancel.Cancel(ctx, id)
		if err != nil {
			return OrderView{}, err
		}
		return toView(o), nil
	})
}

server.go is the only file that knows the SDK. Each tool is one mcp.AddTool call:

	mcp.AddTool(server, &mcp.Tool{
		Name: "findOrder",
		Description: "Returns status, total amount and last update of ONE order. " +
			"Use it when the user mentions a specific order id like ORD-1042.",
	}, func(ctx context.Context, req *mcp.CallToolRequest, in FindOrderInput) (*mcp.CallToolResult, OrderView, error) {
		out, err := t.FindOrder(ctx, scopes(req), in)
		return nil, out, err
	})

// scopes reads the scopes that auth.RequireBearerToken attached to the request.
func scopes(req *mcp.CallToolRequest) []string {
	if req == nil || req.Extra == nil || req.Extra.TokenInfo == nil {
		return nil
	}
	return req.Extra.TokenInfo.Scopes
}

In Java, @PreAuthorize made the scope check invisible and declarative. In Go it is one explicit line. Less magic, and it is unit-tested without starting a server.

🔐 3. Security: the SDK does the plumbing, we verify the token

The SDK's auth.RequireBearerToken handles the HTTP side, including the 401 with resource_metadata. We plug in a verifier:

	requireToken := sdkauth.RequireBearerToken(
		func(ctx context.Context, token string, _ *http.Request) (*sdkauth.TokenInfo, error) {
			claims, err := verifier.Verify(ctx, token)
			if err != nil {
				return nil, sdkauth.ErrInvalidToken
			}
			return &sdkauth.TokenInfo{Scopes: claims.Scopes, Expiration: claims.ExpiresAt}, nil
		},
		&sdkauth.RequireBearerTokenOptions{ResourceMetadataURL: metadataURL},
	)

The verifier itself (internal/platform/auth) uses only the standard library, so every check is visible:

💡 For production you can swap it for a vetted JOSE library behind the same Verify function. Writing it once is the best way to know what those libraries check for you.

🧪 4. The same contract, in Go

The contract test is just a function that receives a factory. The in-memory fake and PostgreSQL (Testcontainers, behind a build tag) both run it:

func RunOrderRepositoryContract(t *testing.T, newRepo func(t *testing.T) domain.OrderRepository)

make test          # unit + in-memory contract + architecture (no Docker)
make integration   # same contract against real PostgreSQL

🛡️ 5. Architecture rules without a framework

No ArchUnit in Go, and you don't need it: go/parser can read the imports of every file.

func TestDomainIsPureGo(t *testing.T) {
	check(t, "domain must only use the standard library", under("internal/domain"),
		func(imp string) bool { return !isStdlib(imp) })
}

func TestApplicationOnlyKnowsTheDomain(t *testing.T) {
	check(t, "app may only import the domain", under("internal/app"),
		func(imp string) bool { return !isStdlib(imp) && imp != module+"/internal/domain" })
}

func TestOnlyTheMcpAdapterAndMainKnowTheSDK(t *testing.T) {
	check(t, "MCP SDK outside its adapter",
		func(pkg string) bool { return pkg != "internal/adapter/in/mcp" && pkg != "cmd/server" },
		func(imp string) bool { return strings.HasPrefix(imp, "github.com/modelcontextprotocol/go-sdk") })
}

📊 6. Built to be compared

The Go server exposes mcp_tool_duration_seconds, mcp_tool_errors_total and http_server_requests_seconds, the same names Micrometer produces in Java. The Grafana dashboard from part 4 works unchanged (only the JVM panels became heap and goroutines), and the k6 scenario is the same: same arrival rate, same thresholds, one agent (token + session) per virtual user. The only extra knob is MCP_HOST: the Go SDK's Streamable HTTP handler protects against DNS rebinding and only accepts localhost in the Host header, so if k6 runs in a container (host.docker.internal) you override the header.

💡 Lessons learned

1. The architecture translated 1:1. The idioms didn't. Ports, adapters and contract tests mean the same thing; annotations became explicit code.
2. Explicit wiring is a feature. main.go shows the whole hexagon in one screen. In Spring that picture is spread across @Configuration classes.
3. Keep the SDK at the edge. Splitting tools.go from server.go made the tool logic testable with zero dependencies.
4. Errors as values map cleanly to protocols. One errors.Is switch per adapter: HTTP status codes for REST, readable messages for the model.
5. Same metric names make comparisons honest. Decide them once, in the first language.

🚀 Next in the series

Part 6: Java vs Go, measured: the same k6 run against both servers, with p95/p99 latency per tool, throughput, memory and startup time.

⭐ Code: github.com/cbuelvasc/orders-mcp-go

👋 I'm Carmelo Buelvas, a Senior Backend Engineer writing about Java, Go and AI agents in production. Let's connect on LinkedIn.

Agents don't behave like humans: they call tools in bursts, in loops and in chains. If you can't see latency, errors and auth failures per tool, you can't run an MCP server in production.

⭐ Code: github.com/cbuelvasc/orders-mcp · Part 4 of the series MCP in Production: Java & Go

🔭 The pipeline

📐 1. Designing the metrics

Two meters, both tagged by tool:

They are recorded in the MCP adapter, the only place that knows what a "tool" is:

/** Timer + error counter per tool -> Prometheus -> Grafana. */
private <T> T observe(String tool, Supplier<T> call) {
    try {
        return meterRegistry.timer("mcp.tool.duration", "tool", tool).record(call);
    } catch (RuntimeException e) {
        meterRegistry.counter("mcp.tool.errors", "tool", tool,
                "exception", e.getClass().getSimpleName()).increment();
        throw e;
    }
}

Percentiles need histogram buckets, and SLOs need buckets at the thresholds you care about:

management:
  metrics:
    distribution:
      percentiles-histogram:
        mcp.tool.duration: true
      slo:
        mcp.tool.duration: 50ms, 100ms, 250ms

📊 2. The dashboard, as code

Grafana is provisioned from the repo (docker/grafana), so the dashboard is versioned with the service.

The PromQL behind the key panels:

💡 The 401/403 panel is the one people forget. A spike there usually means an agent with an expired token or a client asking for the wrong scope, and it looks like an outage from the agent's side.

⚡ 3. Load testing like an agent

The k6 script does what an autonomous agent does: gets a token with client_credentials, opens an MCP session, and calls tools in a burst. Each virtual user is one agent, with its own token and its own session:

// Per-VU state: every virtual user is one agent with its own token and MCP session.
let agent = null;
let nextId = 1;

function connect() {
  // OAuth 2.1 client_credentials: what an autonomous agent would do
  const tokenRes = http.post(TOKEN_URL, {
    grant_type: 'client_credentials',
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    scope: 'orders:read',
  }, { tags: { tool: 'token' } });
  if (!check(tokenRes, { 'got token': (r) => r.status === 200 })) return null;
  const token = tokenRes.json('access_token');
  // ... initialize the MCP session, keep Mcp-Session-Id
  return { token, session };
}

export default function () {
  if (!agent) agent = connect();          // once per VU, on its first iteration
  if (!agent) { sleep(1); return; }
  // ... tools/call with nextId++ so every request has its own JSON-RPC id
}

⚠️ Lesson from a real run: my first version opened one session in setup() and shared it across all VUs, with fixed JSON-RPC ids. Under the burst, about 0.8% of calls failed with duplicate in-flight request ID: the server (correctly) refuses two concurrent requests with the same id in the same session. One session per VU plus incrementing ids took failures to 0. A bonus: the token no longer travels through setup(), so it doesn't end up in the --summary-export file.

export const options = {
  scenarios: {
    agents: {
      executor: 'ramping-arrival-rate',
      startRate: 10, timeUnit: '1s',
      preAllocatedVUs: 50, maxVUs: 200,
      stages: [
        { duration: '30s', target: 50 },
        { duration: '1m', target: 200 },   // burst: agents chaining calls
        { duration: '30s', target: 0 },
      ],
    },
  },
  thresholds: {
    http_req_failed: ['rate<0.01'],
    'http_req_duration{tool:findOrder}': ['p(95)<150'],
    'http_req_duration{tool:listRecentOrders}': ['p(95)<200'],
  },
};

Why ramping-arrival-rate? Agents don't wait for the previous response before deciding to call again across conversations: load arrives at a rate, not per user. An arrival-rate executor models that and exposes queueing that a fixed number of virtual users hides.

Why thresholds per tool? Because a slow listRecentOrders and a fast findOrder average out to "fine" while one tool is actually breaking its SLO.

▶️ 4. Run it yourself

./gradlew bootRun            # app + Postgres + Keycloak + Prometheus + Grafana
k6 run k6/mcp-load-test.js   # in another terminal
open http://localhost:3000   # Dashboards › MCP › Orders MCP · Tools

I'll share my own numbers in the Java vs Go comparison (part 6). Run it on your machine and tell me what you get.

💡 Lessons learned

1. The tool is your unit of observability, the same way the endpoint is for REST.
2. Averages lie. Enable histograms and look at p95/p99 per tool.
3. Put SLO buckets where your promise is (100 ms here), so "are we OK?" is one number.
4. Auth failures are part of reliability for agent traffic.
5. Dashboards belong in the repo, provisioned, reviewed and versioned like code.

🚀 Next in the series

Part 5: the same hexagonal MCP server in Go, with the official MCP Go SDK. Same tools, same scopes, same metrics, so part 6 can compare them fairly.

⭐ Code: github.com/cbuelvasc/orders-mcp

👋 I'm Carmelo Buelvas, a Senior Backend Engineer writing about Java, Go and AI agents in production. Let's connect on LinkedIn.

Hexagonal architecture is a promise: you can replace an adapter without touching the core. In this part I keep that promise by swapping the in-memory repository for PostgreSQL, and I prove it with a contract test that both adapters must pass.

⭐ Code: github.com/cbuelvasc/orders-mcp · Part 3 of the series MCP in Production: Java & Go

🔁 The swap

What changed per layer for the persistence swap:

The only port change was a new save method, and that came from the cancelOrder feature in part 2, not from the database.

🧾 1. The port is the contract

/** Outbound port: implemented by driven adapters (PostgreSQL in production, in-memory in tests). */
public interface OrderRepositoryPort {

    Optional<Order> findById(OrderId id);

    List<Order> findRecentByCustomer(CustomerId customerId, int limit);

    Order save(Order order);
}

🧪 2. A contract test every adapter must pass

This is the key idea of the post. Instead of testing each adapter in its own way, I write the expectations once, as an abstract test against the port:

/**
 * Contract for the outbound port. EVERY adapter (in-memory, PostgreSQL, ...) must pass it.
 * This is what makes swapping adapters safe.
 */
public abstract class OrderRepositoryContract {

    protected abstract OrderRepositoryPort repository();

    private static final Instant NOW = Instant.parse("2026-11-13T12:00:00Z");

    @Test
    void savesAndFindsAnOrder() {
        var order = order("ORD-9001", "CUS-99", OrderStatus.PAID, NOW);

        repository().save(order);

        assertThat(repository().findById(order.id())).contains(order);
    }

    @Test
    void returnsEmptyForUnknownOrders() {
        assertThat(repository().findById(OrderId.of("ORD-9999999"))).isEmpty();
    }

    @Test
    void listsTheMostRecentOrdersOfOneCustomerNewestFirst() {
        repository().save(order("ORD-9101", "CUS-98", OrderStatus.PAID, NOW.minus(3, ChronoUnit.HOURS)));
        repository().save(order("ORD-9102", "CUS-98", OrderStatus.PAID, NOW.minus(1, ChronoUnit.HOURS)));
        repository().save(order("ORD-9103", "CUS-98", OrderStatus.PAID, NOW.minus(2, ChronoUnit.HOURS)));
        repository().save(order("ORD-9104", "CUS-97", OrderStatus.PAID, NOW));

        var recent = repository().findRecentByCustomer(CustomerId.of("CUS-98"), 2);

        assertThat(recent).extracting(o -> o.id().value()).containsExactly("ORD-9102", "ORD-9103");
    }

    // ...more scenarios in the repo
}

The in-memory version moved to src/test: it is now a test double that is guaranteed to behave like production, because it passes the same contract.

🐘 3. The PostgreSQL adapter

Plain SQL with JdbcClient. The mapping between rows and the Order aggregate lives here and only here. No JPA entities leaking into the domain.

/**
 * Driven adapter for PostgreSQL. Plain SQL with JdbcClient: no ORM entities leaking into the domain.
 * The mapping between rows and the Order aggregate lives here and only here.
 */
@Repository
public class JdbcOrderRepository implements OrderRepositoryPort {

    private static final String COLUMNS = "id, customer_id, status, total, currency, updated_at";

    private final JdbcClient jdbc;

    public JdbcOrderRepository(JdbcClient jdbc) {
        this.jdbc = jdbc;
    }

    @Override
    public Optional<Order> findById(OrderId id) {
        return jdbc.sql("SELECT " + COLUMNS + " FROM orders WHERE id = :id")
                .param("id", id.value())
                .query(JdbcOrderRepository::toOrder)
                .optional();
    }

    @Override
    public List<Order> findRecentByCustomer(CustomerId customerId, int limit) {
        return jdbc.sql("""
                        SELECT %s FROM orders
                        WHERE customer_id = :customerId
                        ORDER BY updated_at DESC
                        LIMIT :limit
                        """.formatted(COLUMNS))
                .param("customerId", customerId.value())
                .param("limit", limit)
                .query(JdbcOrderRepository::toOrder)
                .list();
    }

    @Override
    public Order save(Order order) {
        jdbc.sql("""
                        INSERT INTO orders (id, customer_id, status, total, currency, updated_at)
                        VALUES (:id, :customerId, :status, :total, :currency, :updatedAt)
                        ON CONFLICT (id) DO UPDATE
                        SET status = EXCLUDED.status, total = EXCLUDED.total, updated_at = EXCLUDED.updated_at
                        """)
                .param("id", order.id().value())
                .param("customerId", order.customerId().value())
                .param("status", order.status().name())
                .param("total", order.total())
                .param("currency", order.currency())
                .param("updatedAt", Timestamp.from(order.updatedAt()))
                .update();
        return order;
    }

    private static Order toOrder(ResultSet rs, int rowNum) throws SQLException {
        return new Order(
                OrderId.of(rs.getString("id")),
                CustomerId.of(rs.getString("customer_id")),
                OrderStatus.valueOf(rs.getString("status")),
                rs.getBigDecimal("total"),
                rs.getString("currency"),
                rs.getTimestamp("updated_at").toInstant());
    }
}

The ON CONFLICT ... DO UPDATE upsert makes save work for both new and existing orders.

📜 4. Flyway migrations

-- V1__create_orders.sql
CREATE TABLE orders
(
    id          VARCHAR(20)    PRIMARY KEY,
    customer_id VARCHAR(20)    NOT NULL,
    status      VARCHAR(20)    NOT NULL CHECK (status IN ('CREATED', 'PAID', 'SHIPPED', 'DELIVERED', 'CANCELLED')),
    total       NUMERIC(12, 2) NOT NULL CHECK (total >= 0),
    currency    CHAR(3)        NOT NULL,
    updated_at  TIMESTAMPTZ    NOT NULL
);

-- Supports listRecentOrders: WHERE customer_id = ? ORDER BY updated_at DESC LIMIT ?
CREATE INDEX idx_orders_customer_recent ON orders (customer_id, updated_at DESC);

-- V2__seed_demo_orders.sql
-- Demo data: ORD-1000 .. ORD-1059 for customers CUS-1 .. CUS-6
INSERT INTO orders (id, customer_id, status, total, currency, updated_at)
SELECT 'ORD-' || n,
       'CUS-' || (n % 6 + 1),
       (ARRAY ['CREATED', 'PAID', 'SHIPPED', 'DELIVERED', 'CANCELLED'])[n % 5 + 1],
       15 + (n % 17) * 7.5,
       'USD',
       now() - ((1060 - n) || ' hours')::interval
FROM generate_series(1000, 1059) AS n;

The index matches the query of listRecentOrders exactly: filter by customer, order by date, take N.

🐳 5. Testcontainers: the real thing in tests

/** A real PostgreSQL in Docker for integration tests. Spring Boot wires the DataSource automatically. */
@TestConfiguration(proxyBeanMethods = false)
public class PostgresTestcontainersConfig {

    @Bean
    @ServiceConnection
    PostgreSQLContainer postgres() {
        return new PostgreSQLContainer("postgres:17-alpine");
    }
}

/** Same contract as the in-memory fake, now against real PostgreSQL + Flyway migrations. */
@SpringBootTest
@Import(PostgresTestcontainersConfig.class)
class JdbcOrderRepositoryIT extends OrderRepositoryContract {

    @Autowired
    JdbcOrderRepository repository;

    @Override
    protected OrderRepositoryPort repository() {
        return repository;
    }

    @Test
    void flywaySeedsTheDemoData() {
        assertThat(repository.findById(OrderId.of("ORD-1042"))).isPresent();
    }
}

@ServiceConnection wires the DataSource to the container automatically. Flyway runs the same migrations as production, so the test also checks the schema.

🚀 6. Local dev with one command

spring-boot-docker-compose (a developmentOnly dependency) reads compose.yaml, starts the containers and creates the connection details for PostgreSQL. No URLs or passwords in application.yml.

🛡️ 7. Guarding the new boundary

One more ArchUnit rule: SQL is only allowed in the JDBC adapter.

@ArchTest
static final ArchRule onlyTheJdbcAdapterKnowsSql = noClasses()
        .that().resideOutsideOfPackage("..adapter.out.jdbc..")
        .should().dependOnClassesThat().resideInAnyPackage("org.springframework.jdbc..", "java.sql..");

💡 Lessons learned

1. A port without a contract test is only a hope. The contract is what makes the swap safe.
2. Keep fakes honest. If the fake passes the same contract, unit tests stay fast and trustworthy.
3. Plain SQL is fine. For a read-heavy MCP server, JdbcClient keeps the adapter small and the queries obvious.
4. Model the index after the tool. The tool's query defines the access pattern.

🚀 Next in the series

Part 4: observing AI agents in production: Grafana dashboards, SLOs and k6 load tests with real OAuth tokens.

⭐ Code: github.com/cbuelvasc/orders-mcp

👋 I'm Carmelo Buelvas, a Senior Backend Engineer writing about Java, Go and AI agents in production. Let's connect on LinkedIn.

An AI agent calling your tools is a client like any other, and it needs a token. With Spring Security 7 your MCP server becomes an OAuth 2.1 Resource Server, and each tool declares the scope it needs.

⭐ Code: github.com/cbuelvasc/orders-mcp · Part 2 of the series MCP in Production: Java & Go

🧨 Why this matters

In part 1 every agent could call every tool. That was fine for reading orders. It is not fine the moment a tool changes data: an agent that only needs to answer "where is my order?" must never be able to cancel one.

So this part adds two things:

1. Authentication: no token, no tools.
2. Least privilege per tool: read tools need orders:read, write tools need orders:write.

🔄 How an MCP client gets in

The MCP authorization spec builds on standard OAuth. The interesting part is discovery: the client doesn't need to be configured with the authorization server; the MCP server tells it.

⬡ Where security lives in the hexagon

Security is an infrastructure concern. The domain still doesn't know that tokens exist.

🛠️ 1. Dependencies

Spring Boot 4 has a dedicated starter for the resource server:

# gradle/libs.versions.toml
spring-boot-starter-oauth2-resource-server = { module = "org.springframework.boot:spring-boot-starter-security-oauth2-resource-server" }

# application.yml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: ${ISSUER_URI:http://localhost:8180/realms/orders}

orders:
  mcp:
    security:
      resource: ${MCP_RESOURCE_URL:http://localhost:8080/mcp}
      authorization-servers:
        - ${ISSUER_URI:http://localhost:8180/realms/orders}
      scopes: [orders:read, orders:write]

🛡️ 2. The filter chain

/**
 * The MCP server is an OAuth 2.1 Resource Server:
 * - every request to /mcp and /api needs a valid Bearer token (JWT)
 * - each tool checks its own scope with @PreAuthorize (method security)
 * - Spring Security 7 serves the Protected Resource Metadata (RFC 9728) natively;
 *   we only customize it and point 401 responses to it
 */
@Configuration(proxyBeanMethods = false)
@EnableMethodSecurity
@EnableConfigurationProperties(McpSecurityProperties.class)
class SecurityConfig {

    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http, McpSecurityProperties props) throws Exception {
        var entryPoint = new ResourceMetadataEntryPoint(props.resourceMetadataUrl());
        return http
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/.well-known/oauth-protected-resource/**").permitAll()
                        .requestMatchers("/actuator/health/**", "/actuator/prometheus").permitAll()
                        .anyRequest().authenticated())
                .oauth2ResourceServer(oauth -> oauth
                        .jwt(jwt -> { })
                        .authenticationEntryPoint(entryPoint)
                        .protectedResourceMetadata(metadata -> metadata
                                .protectedResourceMetadataCustomizer(builder -> {
                                    builder.resource(props.resource())
                                            .bearerMethod("header")
                                            .tlsClientCertificateBoundAccessTokens(false);
                                    props.authorizationServers().forEach(builder::authorizationServer);
                                    props.scopes().forEach(builder::scope);
                                })))
                .exceptionHandling(ex -> ex.authenticationEntryPoint(entryPoint))
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .csrf(csrf -> csrf.disable()) // no browser sessions, bearer tokens only
                .build();
    }
}

Three decisions worth calling out:

• Stateless + no CSRF: MCP clients send bearer tokens, not cookies.
• Metadata is public: the client must be able to read it before it has a token.
• @EnableMethodSecurity: authorization happens per tool, not per URL. Every tool lives behind the same /mcp endpoint, so URL rules can't tell tools apart.

🧭 3. Discovery: RFC 9728 metadata

/**
 * 401 + WWW-Authenticate with resource_metadata, as required by the MCP authorization spec.
 * That header is how an MCP client discovers where to get a token.
 */
class ResourceMetadataEntryPoint implements AuthenticationEntryPoint {

    private final String resourceMetadataUrl;

    ResourceMetadataEntryPoint(String resourceMetadataUrl) {
        this.resourceMetadataUrl = resourceMetadataUrl;
    }

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response,
                         AuthenticationException authException) {
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
        response.setHeader(HttpHeaders.WWW_AUTHENTICATE,
                "Bearer resource_metadata=\"%s\"".formatted(resourceMetadataUrl));
    }
}

The metadata document itself needs no controller: Spring Security 7 ships an OAuth2ProtectedResourceMetadataFilter that answers /.well-known/oauth-protected-resource. The protectedResourceMetadata(...) customizer above adds the authorization server and the scopes, and turns off tls_client_certificate_bound_access_tokens, which the filter advertises as true by default.

⚠️ Lesson learned the hard way: my first version had its own @RestController for this endpoint. The tests failed because the built-in filter answered first, without authorization_servers. When the framework already implements a spec, configure it instead of competing with it.

What the client sees:

curl -i -X POST http://localhost:8080/mcp
# HTTP/1.1 401
# WWW-Authenticate: Bearer resource_metadata="http://localhost:8080/.well-known/oauth-protected-resource/mcp"

curl http://localhost:8080/.well-known/oauth-protected-resource/mcp
# {"resource":"http://localhost:8080/mcp",
#  "authorization_servers":["http://localhost:8180/realms/orders"],
#  "scopes_supported":["orders:read","orders:write"],
#  "bearer_methods_supported":["header"]}

💡 The Spring AI community project mcp-security packages these ideas too. With Spring Security 7, the building blocks are already in the framework.

🔐 4. Scopes per tool

Read tools:

    @PreAuthorize(READ)
    @McpTool(name = "findOrder", description = """
            Returns status, total amount and last update of ONE order.
            Use it when the user mentions a specific order id like ORD-1042.
            """)
    public OrderView findOrder(
            @McpToolParam(description = "Order id, format ORD-<digits>, e.g. ORD-1042", required = true)
            String orderId) {
        return observe("findOrder", () -> OrderView.from(findOrder.findById(OrderId.of(orderId))));
    }

And the new write tool. Note the description: it tells the model to ask the user for confirmation first.

    @PreAuthorize(WRITE)
    @McpTool(name = "cancelOrder", description = """
            Cancels ONE order that has not shipped yet. This action cannot be undone.
            Only call it after the user explicitly confirmed the order id to cancel.
            """)
    public OrderView cancelOrder(
            @McpToolParam(description = "Order id to cancel, format ORD-<digits>", required = true)
            String orderId) {
        return observe("cancelOrder", () -> OrderView.from(cancelOrder.cancel(OrderId.of(orderId))));
    }

The business rule ("you can't cancel an order that already shipped") lives in the aggregate, not in the adapter:

    /** Business rule: only orders that have not left the warehouse can be cancelled. */
    public Order cancel(Instant now) {
        if (!status.isCancellable()) {
            throw new OrderCannotBeCancelledException(id, status);
        }
        return new Order(id, customerId, OrderStatus.CANCELLED, total, currency, now);
    }

🔑 5. A demo authorization server

The repo ships a Keycloak realm with two clients, which makes the difference between scopes very visible:

./gradlew bootRun   # starts Postgres, Keycloak, Prometheus and Grafana from compose.yaml
TOKEN=$(./scripts/get-token.sh orders-readonly orders:read)
curl http://localhost:8080/api/orders/ORD-1042 -H "Authorization: Bearer $TOKEN"

🧪 6. Testing the rules

No real tokens needed: @WithMockUser sets the authorities, and a real HTTP call checks the 401.

@Test
@WithMockUser(authorities = "SCOPE_orders:read")
void aReaderCannotCancelOrders() {
    assertThatThrownBy(() -> tools.cancelOrder("ORD-1040"))
            .isInstanceOf(AuthorizationDeniedException.class);
}

@Test
void mcpEndpointRejectsAnonymousCallsAndPointsToTheMetadata() throws Exception {
    var response = http(HttpRequest.newBuilder(uri("/mcp"))
            .POST(HttpRequest.BodyPublishers.ofString("{}"))
            .header("Content-Type", "application/json"));

    assertThat(response.statusCode()).isEqualTo(401);
    assertThat(response.headers().firstValue("WWW-Authenticate"))
            .hasValueSatisfying(h -> assertThat(h).startsWith("Bearer resource_metadata="));
}

💡 Lessons learned

1. URL rules are not enough for MCP. All tools share /mcp, so authorization must be per method.
2. Discovery is part of the contract. The 401 header and the metadata let any compliant client find its way.
3. Separate read and write scopes from day one. It is the cheapest protection against an over-eager agent.
4. Tool descriptions are also a safety control. "Only call it after the user confirmed" is guidance the model actually reads.

🚀 Next in the series

Part 3: replacing the in-memory repository with PostgreSQL (JdbcClient + Flyway + Testcontainers) without touching the core.

⭐ Code: github.com/cbuelvasc/orders-mcp

👋 I'm Carmelo Buelvas, a Senior Backend Engineer writing about Java, Go and AI agents in production. Let's connect on LinkedIn.

An MCP server is just another driving adapter. If your service follows hexagonal architecture, exposing it to AI agents is a new entry door, not a rewrite.

⭐ Full code: github.com/cbuelvasc/orders-mcp

🧩 The big picture

The Model Context Protocol (MCP) is an open standard that lets an AI client (Claude, Copilot, Cursor or your own agent) discover and call tools exposed by a server. It does for agents what REST did for services.

The question I wanted to answer: where does MCP fit in a well-designed backend?

The MCP adapter and the REST adapter sit side by side. Both call the same inbound ports. The domain doesn't know AI exists.

🔄 What happens during a tool call

📁 Project structure

src/main/java/dev/cbuelvasc/orders/
├── domain/                     ← pure Java, no frameworks
│   ├── model/                  Order, OrderId, CustomerId, OrderStatus
│   ├── exception/              OrderNotFoundException
│   └── port/
│       ├── in/                 FindOrderUseCase, ListRecentOrdersUseCase
│       └── out/                OrderRepositoryPort
├── application/                OrderQueryService (no Spring annotations)
└── infrastructure/
    ├── adapter/
    │   ├── in/mcp/             OrderMcpTools, OrderView   ← AI entry door
    │   ├── in/rest/            OrderController            ← human entry door
    │   └── out/memory/         InMemoryOrderRepository
    └── config/                 UseCaseConfig

🛠️ 1. Gradle: Kotlin DSL + version catalog

All versions live in one place:

# gradle/libs.versions.toml
[versions]
java = "25"
spring-boot = "4.1.2"
spring-ai = "2.0.2"
archunit = "1.5.0"

[libraries]
spring-ai-bom = { module = "org.springframework.ai:spring-ai-bom", version.ref = "spring-ai" }
spring-ai-mcp-server-webmvc = { module = "org.springframework.ai:spring-ai-starter-mcp-server-webmvc" }
spring-boot-starter-webmvc = { module = "org.springframework.boot:spring-boot-starter-webmvc" }
spring-boot-starter-actuator = { module = "org.springframework.boot:spring-boot-starter-actuator" }
spring-boot-starter-test = { module = "org.springframework.boot:spring-boot-starter-test" }
micrometer-prometheus = { module = "io.micrometer:micrometer-registry-prometheus" }
junit-platform-launcher = { module = "org.junit.platform:junit-platform-launcher" }
archunit-junit5 = { module = "com.tngtech.archunit:archunit-junit5", version.ref = "archunit" }

[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }

// build.gradle.kts
import org.springframework.boot.gradle.plugin.SpringBootPlugin

plugins {
    java
    alias(libs.plugins.spring.boot)
}

group = "dev.cbuelvasc"
version = "0.1.0"

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(libs.versions.java.get())
    }
}

repositories {
    mavenCentral()
}

dependencies {
    // BOMs as Gradle platforms (no dependency-management plugin needed)
    implementation(platform(SpringBootPlugin.BOM_COORDINATES))
    implementation(platform(libs.spring.ai.bom))

    // Driving adapters
    implementation(libs.spring.ai.mcp.server.webmvc)   // MCP (AI agents)
    implementation(libs.spring.boot.starter.webmvc)    // REST (humans)

    // Observability
    implementation(libs.spring.boot.starter.actuator)
    implementation(libs.micrometer.prometheus)

    testImplementation(platform(SpringBootPlugin.BOM_COORDINATES))
    testImplementation(libs.spring.boot.starter.test)
    testImplementation(libs.archunit.junit5)
    testRuntimeOnly(libs.junit.platform.launcher)
}

tasks.withType<JavaCompile>().configureEach {
    options.compilerArgs.add("-parameters")
}

tasks.test {
    useJUnitPlatform()
}

No io.spring.dependency-management plugin: the Spring Boot and Spring AI BOMs are imported as native Gradle platforms.

# application.yml
spring:
  application:
    name: orders-mcp
  ai:
    mcp:
      server:
        name: orders-mcp-server
        version: 0.1.0
        type: SYNC
        protocol: STREAMABLE   # SSE | STREAMABLE | STATELESS -> endpoint: /mcp
  threads:
    virtual:
      enabled: true

management:
  endpoints:
    web:
      exposure:
        include: health, info, metrics, prometheus
  metrics:
    tags:
      application: ${spring.application.name}

⬡ 2. The core: domain and ports

Pure Java. No Spring, no MCP, no JPA. Value objects validate themselves, so a malformed id never reaches the repository:

/** Value object: an order id always has the format ORD-<digits>. */
public record OrderId(String value) {

    private static final Pattern FORMAT = Pattern.compile("ORD-\\d{1,10}");

    public OrderId {
        Objects.requireNonNull(value, "order id is required");
        value = value.strip().toUpperCase();
        if (!FORMAT.matcher(value).matches()) {
            throw new IllegalArgumentException("Invalid order id '%s'. Expected format ORD-<digits>".formatted(value));
        }
    }

    public static OrderId of(String value) {
        return new OrderId(value);
    }
}

// domain/port/in
/** Inbound port: driving adapters (MCP, REST) depend on this, never on the implementation. */
public interface FindOrderUseCase {

    /** @throws dev.cbuelvasc.orders.domain.exception.OrderNotFoundException if it does not exist */
    Order findById(OrderId id);
}

public interface ListRecentOrdersUseCase {

    int MAX_LIMIT = 20;

    /** Newest first. The limit is clamped to [1, MAX_LIMIT] by the core. */
    List<Order> listRecent(CustomerId customerId, int limit);
}

// domain/port/out
/** Outbound port: implemented by driven adapters (in-memory today, JPA tomorrow). */
public interface OrderRepositoryPort {

    Optional<Order> findById(OrderId id);

    List<Order> findRecentByCustomer(CustomerId customerId, int limit);
}

// application
/**
 * Application service. No Spring annotations: it is wired in infrastructure/config,
 * so the core stays framework-agnostic (verified by HexagonalArchitectureTest).
 */
public class OrderQueryService implements FindOrderUseCase, ListRecentOrdersUseCase {

    private final OrderRepositoryPort repository;

    public OrderQueryService(OrderRepositoryPort repository) {
        this.repository = Objects.requireNonNull(repository);
    }

    @Override
    public Order findById(OrderId id) {
        return repository.findById(id).orElseThrow(() -> new OrderNotFoundException(id));
    }

    @Override
    public List<Order> listRecent(CustomerId customerId, int limit) {
        // Business rule lives in the core, so it protects EVERY adapter (REST, MCP, ...)
        int safeLimit = Math.clamp(limit, 1, MAX_LIMIT);
        return repository.findRecentByCustomer(customerId, safeLimit);
    }
}

🤖 3. The MCP adapter with @McpTool

Spring AI 2.0 brings annotation-based MCP. This is the only class that knows about MCP, and it depends on ports, not on the service:

/**
 * Driving adapter for AI agents. This is the ONLY class that knows about MCP.
 * It depends on inbound ports, never on the application service or the repository.
 */
@Component
public class OrderMcpTools {

    private final FindOrderUseCase findOrder;
    private final ListRecentOrdersUseCase listRecentOrders;
    private final MeterRegistry meterRegistry;

    public OrderMcpTools(FindOrderUseCase findOrder,
                         ListRecentOrdersUseCase listRecentOrders,
                         MeterRegistry meterRegistry) {
        this.findOrder = findOrder;
        this.listRecentOrders = listRecentOrders;
        this.meterRegistry = meterRegistry;
    }

    @McpTool(name = "findOrder", description = """
            Returns status, total amount and last update of ONE order.
            Use it when the user mentions a specific order id like ORD-1042.
            """)
    public OrderView findOrder(
            @McpToolParam(description = "Order id, format ORD-<digits>, e.g. ORD-1042", required = true)
            String orderId) {
        return observe("findOrder", () -> OrderView.from(findOrder.findById(OrderId.of(orderId))));
    }

    @McpTool(name = "listRecentOrders", description = """
            Lists the most recent orders of ONE customer, newest first.
            Use it when the user asks about the latest orders of a customer.
            """)
    public List<OrderView> listRecentOrders(
            @McpToolParam(description = "Customer id, format CUS-<digits>, e.g. CUS-7", required = true)
            String customerId,
            @McpToolParam(description = "How many orders to return, from 1 to 20", required = false)
            Integer limit) {
        int requested = limit == null ? 5 : limit;
        return observe("listRecentOrders", () -> listRecentOrders
                .listRecent(CustomerId.of(customerId), requested)
                .stream()
                .map(OrderView::from)
                .toList());
    }

    /** Timer + error counter per tool -> Prometheus -> Grafana. */
    private <T> T observe(String tool, Supplier<T> call) {
        try {
            return meterRegistry.timer("mcp.tool.duration", "tool", tool).record(call);
        } catch (RuntimeException e) {
            meterRegistry.counter("mcp.tool.errors", "tool", tool,
                    "exception", e.getClass().getSimpleName()).increment();
            throw e; // Spring AI turns it into an MCP error result the model can read
        }
    }
}

/**
 * What the model sees. The adapter translates the domain into a small,
 * model-friendly shape: only the fields it needs, nothing sensitive.
 */
public record OrderView(String orderId,
                        String status,
                        boolean isFinal,
                        BigDecimal total,
                        String currency,
                        Instant updatedAt) {

    static OrderView from(Order order) {
        return new OrderView(
                order.id().value(),
                order.status().name(),
                order.status().isFinal(),
                order.total(),
                order.currency(),
                order.updatedAt());
    }
}

The adapter translates the domain into a small, model-friendly shape. No ToolCallbackProvider boilerplate: the @McpTool methods are discovered automatically. The core is wired in one place:

/** Wires the framework-agnostic core into Spring. */
@Configuration(proxyBeanMethods = false)
class UseCaseConfig {

    @Bean
    OrderQueryService orderQueryService(OrderRepositoryPort orderRepository) {
        return new OrderQueryService(orderRepository);
    }
}

🧪 4. Guarding the hexagon with ArchUnit

Hexagonal only works if the rules hold. Let the build enforce them:

/** The hexagon is only real if a test enforces it. */
@AnalyzeClasses(packages = "dev.cbuelvasc.orders", importOptions = ImportOption.DoNotIncludeTests.class)
class HexagonalArchitectureTest {

    @ArchTest
    static final ArchRule domainIsPureJava = noClasses()
            .that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAnyPackage(
                    "org.springframework..", "jakarta..", "io.micrometer..", "io.modelcontextprotocol..");

    @ArchTest
    static final ArchRule applicationDoesNotDependOnFrameworks = noClasses()
            .that().resideInAPackage("..application..")
            .should().dependOnClassesThat().resideInAnyPackage("org.springframework..", "jakarta..");

    @ArchTest
    static final ArchRule coreDoesNotKnowInfrastructure = noClasses()
            .that().resideInAnyPackage("..domain..", "..application..")
            .should().dependOnClassesThat().resideInAPackage("..infrastructure..");

    @ArchTest
    static final ArchRule onlyTheMcpAdapterKnowsMcp = noClasses()
            .that().resideOutsideOfPackage("..adapter.in.mcp..")
            .should().dependOnClassesThat().resideInAnyPackage(
                    "org.springframework.ai..", "io.modelcontextprotocol..");

    @ArchTest
    static final ArchRule adaptersTalkToPortsNotToTheService = noClasses()
            .that().resideInAPackage("..adapter.in..")
            .should().dependOnClassesThat().resideInAPackage("..application..");
}

🔐 5. Production-ready: defense in depth

Key ideas:

• 🔑 OAuth 2.1 is what the MCP spec recommends for HTTP transports (next step in the repo roadmap).
• 🧨 Treat every tool argument as untrusted. Prompt injection is real. Value objects like OrderId give you validation for free.
• ✋ Write tools (refunds, cancellations) need dedicated scopes and human confirmation in the client.

📊 6. Observability and load testing

Every tool call records mcp.tool.duration and mcp.tool.errors, tagged by tool, exposed on /actuator/prometheus. The repo includes a k6 script that ramps to 200 tool calls per second:

k6 run k6/mcp-load-test.js

💡 Lessons learned

1. Descriptions are the API. Vague descriptions lead to wrong tool calls.
2. findOrder beats queryDatabase. Small, focused tools are safer and easier for the model.
3. Readable errors like Order not found: ORD-1042 let the agent recover.
4. Hexagonal pays off. Adding MCP meant one new adapter. The domain didn't change at all.

🚀 What's next

Next post: the same hexagonal MCP server in Go with the official MCP Go SDK, with a side-by-side comparison of developer experience, memory footprint and latency under k6.

⭐ Code: github.com/cbuelvasc/orders-mcp

👋 I'm Carmelo Buelvas, a Senior Backend Engineer writing about Java, Go and AI agents in production. Let's connect on LinkedIn.