Content
# Spring AI MCP Host (Java) — DSM-flavored Demo
A faithful Java/Spring Boot implementation of the MCP architecture from your diagram:
**one host application** (Spring Boot + Anthropic Claude) maintains **three MCP clients**, each
connected 1:1 to a separate **MCP server** that wraps an external system.
## Architecture
```
┌────────────────────────────────────┐
│ MCP HOST (port 8080) │
│ Spring Boot + ChatClient + Claude │
│ │
│ ┌──────────┐ ┌──────────┐ ┌─────┐ │
│ │ Client A │ │ Client B │ │ C │ │
│ └────┬─────┘ └────┬─────┘ └──┬──┘ │
└───────┼────────────┼──────────┼────┘
│ MCP/HTTP │ MCP/HTTP │ MCP/HTTP
┌─────────▼──┐ ┌──────▼──────┐ ┌─▼─────────┐
│ db-server │ │ fs-server │ │ web-server│
│ port 8090 │ │ port 8091 │ │ port 8092 │
│ │ │ │ │ │
│ Tools: │ │ Tools: │ │ Tools: │
│ - distrib │ │ - listFiles │ │ - fetchUrl│
│ - volume │ │ - readFile │ │ │
│ - top-merch│ │ - writeFile │ │ │
│ - failed │ │ │ │ │
└─────┬──────┘ └──────┬──────┘ └─────┬─────┘
│ │ │
┌─────▼──────┐ ┌──────▼──────┐ ┌─────▼─────┐
│ H2/PG │ │ ./sandbox │ │ httpbin, │
│ (txns DB) │ │ (filesys) │ │ wikipedia │
└────────────┘ └─────────────┘ └───────────┘
```
Mapping to the diagram you shared:
- The diagram's **MCP Host** = the `host/` module
- Each **MCP Client** = auto-created by Spring AI's MCP client starter, one per `streamable-http.connections.*` entry in `application.yml`
- Each **MCP Server** = one of `db-server/`, `fs-server/`, `web-server/`
- The transport between client and server = **Streamable HTTP** (the modern MCP transport, replaces SSE)
## Project layout
```
mcp-host/
├── pom.xml # Parent POM (BOM imports)
├── host/ # The MCP HOST application
│ └── src/main/...
├── db-server/ # MCP Server: transaction database
│ └── src/main/...
├── fs-server/ # MCP Server: sandboxed filesystem
│ └── src/main/...
├── web-server/ # MCP Server: web fetch (allowlisted)
│ └── src/main/...
└── scripts/
├── start-all.sh
└── stop-all.sh
```
## Prerequisites
- Java 21
- Maven 3.9+
- An Anthropic API key (or swap the LLM — see "Switching LLM providers" below)
## Quickstart
```bash
# 1. Set your API key
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxx
# 2. Build everything
mvn -DskipTests clean package
# 3. Start all four services
./scripts/start-all.sh
# 4. Ask a question that requires the database
curl 'http://localhost:8080/chat?q=How+many+CHECKING+transactions+failed+enrichment%3F'
# 5. Ask one that requires the filesystem
curl 'http://localhost:8080/chat?q=What+does+the+vendor-notes.txt+file+say+about+performance+targets%3F'
# 6. Ask one that combines sources
curl 'http://localhost:8080/chat?q=Compare+the+actual+vendor+primacy+rate+for+CHECKING+with+the+target+in+vendor-notes.txt'
# 7. Stop everything
./scripts/stop-all.sh
```
## How the wiring works (the part most tutorials gloss over)
Look at `host/src/main/resources/application.yml`:
```yaml
spring:
ai:
mcp:
client:
streamable-http:
connections:
transaction-server: { url: http://localhost:8090 }
filesystem-server: { url: http://localhost:8091 }
web-server: { url: http://localhost:8092 }
toolcallback:
enabled: true
```
That's it. The `spring-ai-starter-mcp-client` dependency reads those three connections,
creates one MCP client per entry, calls each server's `tools/list` endpoint at startup,
and aggregates every discovered tool into a single `ToolCallbackProvider` bean. The
host's `ChatClient` gets all of them attached, so the LLM sees a unified tool palette.
When you ask "how many CHECKING transactions failed enrichment?", Claude:
1. Looks at all available tools and their descriptions
2. Picks `getFailedEnrichmentCounts` from the transaction-server
3. Spring AI's MCP client runtime invokes it over HTTP
4. The result flows back into the LLM, which writes a natural-language answer
## Things to try (and why each one matters)
| Question | What it teaches |
|----------|----------------|
| "How many CHECKING transactions did we have in the last 7 days?" | Tool selection by description matching |
| "What's the total volume across all account types in the last 30 days?" | LLM calls the same tool multiple times with different args |
| "Read vendor-notes.txt and summarize the latency targets" | Cross-server: filesystem tool used standalone |
| "Compare our actual Spade success rate to the target in vendor-notes.txt" | Cross-server reasoning: DB tool + FS tool combined |
| "Fetch https://httpbin.org/json and tell me what's there" | Web tool with allowlist |
| "Fetch https://evil.com/x" | Allowlist rejection — see the guardrail in action |
## Switching LLM providers
The MCP architecture is LLM-agnostic. To swap Anthropic for OpenAI:
```xml
<!-- in host/pom.xml, replace the anthropic dep with: -->
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
```
```yaml
# in host/application.yml, replace anthropic config with:
spring.ai.openai.api-key: ${OPENAI_API_KEY}
spring.ai.openai.chat.options.model: gpt-4o
```
Or use Ollama for fully local inference — same pattern. **You change one dependency
and a few config lines. The MCP servers don't change at all.** That's the whole
point of MCP.
## Production hardening checklist
This is a learning project. Before anything resembling production:
1. **Auth on every server.** Put OAuth2 / mTLS / API keys in front of each MCP
server. Spring AI 1.1+ has MCP Security support built in.
2. **Tool input validation.** The LLM controls tool arguments. Validate them on
the server side as if they were user input — because effectively they are.
3. **Audit logging.** Log every tool invocation with caller identity, args, and
result size. This is non-negotiable in a regulated environment.
4. **Rate limits per tool.** A confused LLM can call a tool in a loop. Cap it.
5. **PII masking on tool outputs.** Reuse your existing `@MaskPii` AOP — apply
it to the methods on `TransactionTools`.
6. **Don't expose write tools without explicit user confirmation flow.** The
`writeFile` tool should require a separate approval step in production.
7. **Network egress controls.** The web server's allowlist is a starting point,
not a real control. Force outbound through your bank's egress proxy.
## How this maps to your DSM 2.0 work
The `db-server` is intentionally modeled on DSM 2.0:
- The schema mirrors your enrichment output (account_type, vendor, status)
- The tools mirror queries you already run on Datadog dashboards (vendor primacy
distribution, failed enrichment counts)
- The vendor-notes file mirrors the kind of operational context that lives in
Confluence today
A natural next step would be to point the `db-server` at the actual Postgres
schema you use for enrichment routing rules. The MCP server pattern means an
LLM-powered Slack bot could answer engineering questions like "what's our Spade
success rate by account type today?" without anyone hand-writing SQL.
