Define tools, prompts, and resources as annotated Spring beans. Pull in optional modules for OAuth2, per-handler authorization, Jakarta Bean Validation, structured audit logs, Micrometer observations, MDC correlation, an /actuator/mcp inventory endpoint, and GraalVM native-image support — all wired through one customizer SPI.
An enterprise-grade Spring Boot framework for stateless Model Context Protocol (MCP) servers in Java (MCP 2026-07-28). OAuth2 resource server, per-handler authorization, OpenTelemetry, Jakarta Validation, audit logging, GraalVM native-image — all opt-in via a one-dependency feature-module pattern.
Status: stable. 1.0.0 implements MCP 2026-07-28 exclusively and follows semantic versioning — breaking changes only in a new major. Features deliberately not implemented are enumerated, with rationale, in ADR-0022. We'd love feedback and real-world usage reports.
What's in the box
Building an MCP server from scratch means solving the same problems every team solves: JSON-RPC dispatch, the _meta envelope and routing-header validation, SSE response streaming, multi-round-trip elicitation, schema generation, OAuth2, tracing, metrics, audit. Mocapi ships those pieces as Spring Boot autoconfiguration you wire by adding a transport starter, and extend through a single customizer SPI.
MCP 2026-07-28 surface. Tools, prompts, resources, resource templates, completions, server/discover, multi-round-trip (MRTR) elicitation, progress notifications, cacheable results, and the OAuth2 authorization flow — fully stateless, as the revision requires. Exercised by the official conformance suite. Deliberate omissions (deprecated Roots/Sampling/Logging, subscriptions/listen) are recorded with rationale in ADR-0022.
Transport-agnostic handler code. Write a @McpTool once; run it over Streamable HTTP (for web clients) or stdio (for Claude Desktop / Cursor / IDE integrations) with no code change.
Observability modules. Metrics and tracing via Micrometer Observation, SLF4J MDC correlation, structured audit logs — each activates by dropping in a module.
Authorization. OAuth2 resource server (MCP 2026-07-28 spec), per-handler Guard SPI, and @RequiresScope / @RequiresRole annotations backed by Spring Security. New to securing an MCP server? Start with the security guide — the endpoint is unauthenticated until you add mocapi-oauth2.
Stateless by design. No sessions, no sticky routing, no shared store: any node serves any request, and elicitation round trips travel as self-contained AES-GCM-encrypted requestState tokens. Scale-to-zero and serverless deployments are the natural shape.
Typed extension SPI. One customizer interface per handler kind. Attach interceptors, guards, or parameter resolvers with full access to the handler's descriptor, method, and bean — no blind bean-list autowiring.
Virtual-thread-friendly. Context propagates across the per-call virtual-thread spawn so tracing spans parent correctly and SecurityContextHolder works on the handler thread. A standing soak test sustained ~565 req/s with full observability on a laptop (see Performance Benchmarking).
MCP Apps (the server half). Serve interactive ui:// HTML resources and link them to tools — declare them with @McpAppResource, or serve a bundle straight from the classpath with @McpUi(resource=…); mocapi emits the io.modelcontextprotocol/ui capability, _meta.ui (CSP/sandbox), and fails fast on dangling links. Add mocapi-apps. See MCP Apps.
MCP Tasks. Add @McpTask to any tool and it transparently runs as a polled background task (io.modelcontextprotocol/tasks) for clients that declare the extension — same tool code serves everyone else synchronously. Progress emits become the task's statusMessage, mid-task elicitation flows through tasks/get/tasks/update, and state lives behind a pluggable TaskStore (in-memory default; contract TCK for custom stores). For durable, multi-node task state add mocapi-tasks-substrate — a Substrate-backed store that works across any of its nine backends (Redis, PostgreSQL, MongoDB, …) and survives application restarts. Add mocapi-tasks. See MCP Tasks.
Then declare individual mocapi artifacts without a <version> — the BOM pins them.
Define a tool:
import com.callibrity.mocapi.api.tools.McpTool;
import org.springframework.stereotype.Component;
@Component
public class GreetingTool {
@McpTool(name = "greet", description = "Returns a greeting message")
public GreetingResponse greet(String name) {
return new GreetingResponse("Hello, " + name + "!");
}
public record GreetingResponse(String message) {}
}
Define a prompt:
import com.callibrity.mocapi.api.prompts.McpPrompt;
import com.callibrity.mocapi.model.GetPromptResult;
import com.callibrity.mocapi.model.PromptMessage;
import com.callibrity.mocapi.model.Role;
import com.callibrity.mocapi.model.TextContent;
import org.springframework.stereotype.Component;
import java.util.List;
@Component
public class SummarizationPrompts {
@McpPrompt(name = "summarize", description = "Summarize the provided text")
public GetPromptResult summarize(String text) {
return new GetPromptResult(
"Summarization prompt",
List.of(new PromptMessage(
Role.USER,
new TextContent("Summarize the following:\n\n" + text, null))));
}
}
Define a resource (fixed URI) and a resource template (pattern-matched URI):
import com.callibrity.mocapi.api.resources.McpResource;
import com.callibrity.mocapi.api.resources.McpResourceTemplate;
import com.callibrity.mocapi.model.ReadResourceResult;
import com.callibrity.mocapi.model.TextResourceContents;
import org.springframework.stereotype.Component;
import java.util.List;
@Component
public class DocResources {
@McpResource(uri = "docs://readme", mimeType = "text/markdown")
public ReadResourceResult readme() {
return new ReadResourceResult(
List.of(new TextResourceContents("docs://readme", "text/markdown", "# Hello")));
}
@McpResourceTemplate(uriTemplate = "docs://pages/{slug}", mimeType = "text/markdown")
public ReadResourceResult page(String slug) {
return new ReadResourceResult(
List.of(new TextResourceContents(
"docs://pages/" + slug, "text/markdown", "Content for " + slug)));
}
}
Run your Spring Boot application. With mocapi-streamable-http-spring-boot-starter, Mocapi exposes a Streamable HTTP endpoint at /mcp. For clients that launch the server as a subprocess (Claude Desktop, Cursor, and other IDE integrations), depend on mocapi-stdio-spring-boot-starter instead and set mocapi.stdio.enabled=true — same tools, same code, different pipe.
OpenTelemetry -- drop-in OTel tracing via mocapi-otel: bundles mocapi-o11y + Spring Boot 4's OTel SDK + tracing bridge; emits a two-layer jsonrpc.server / mcp.handler.execution trace with OTel MCP / JSON-RPC / GenAI semconv attrs
Logging -- MDC correlation keys via mocapi-logging
Audit -- structured audit logging via mocapi-audit for compliance queries and SIEM ingestion
Actuator Endpoint -- /actuator/mcp handler-inventory endpoint shape and operational checks
Extending mocapi -- the seam taxonomy (*Contributor/*Customizer/*Interceptor/*Store-*Source-*Strategy/*Sink), one worked example per seam, the dispatch-interceptor contract, and API-vs-SPI classification
Customizers -- the *HandlerCustomizer SPI for extending mocapi: attach interceptors, guards, and parameter resolvers per handler
mocapi-stdio-transport — newline-delimited JSON-RPC on stdin/stdout, for subprocess-launched MCP clients
Spring Boot starters — pick your transport
Only two starters. Every mocapi application adds exactly one.
mocapi-streamable-http-spring-boot-starter — bundles mocapi-server + streamable-HTTP transport + spring-boot-starter-web. Expose an /mcp endpoint accessible over the network.
mocapi-stdio-spring-boot-starter — bundles mocapi-server + stdio transport. For subprocess-launched MCP clients (Claude Desktop, Cursor, IDE integrations); no web stack.
Feature modules — drop in to activate
Each module is plain Java + an optional Spring Boot autoconfig (hosted in mocapi-autoconfigure). Add the module to your pom; the corresponding feature activates automatically.
mocapi-oauth2 — OAuth2 resource-server protection on the MCP endpoint (MCP 2026-07-28 authorization); wraps Spring Boot's OAuth2 resource-server starter and adds the RFC 9728 protected-resource metadata document. Ships two SecurityFilterChain beans (public metadata + authenticated MCP) each with its own customizer SPI (McpMetadataFilterChainCustomizer, McpFilterChainCustomizer), a swappable McpTokenStrategy for JWT vs. opaque tokens, and a facet-based McpMetadataCustomizer SPI for shaping the metadata document. See Authorization.
mocapi-spring-security-guards — annotation-driven Guard implementations backed by Spring Security. Reads @RequiresScope / @RequiresRole off user handler methods at startup and attaches matching guards via the customizer SPI; denied handlers disappear from tools/list etc. and call-time returns JSON-RPC -32010 Forbidden. See Guards.
mocapi-jakarta-validation — Jakarta Bean Validation on user @McpTool / @McpPrompt / @McpResourceTemplate parameters. Annotations like @NotBlank/@Size/@Pattern surface as CallToolResult.isError=true for tools (MCP-spec-idiomatic for LLM self-correction) and JSON-RPC -32602 Invalid params with per-violation detail for prompts and resources. See Validation.
mocapi-logging — SLF4J MDC correlation for MCP handler invocations. Stamps mcp.protocol.version, mcp.client.name, mcp.handler.kind, mcp.handler.name, and mcp.request.id onto the MDC for the duration of every handler call so every log line from user code carries correlation context automatically. See Logging.
mocapi-o11y — metrics + distributed tracing via Micrometer's Observation API. Two layers: a filter enriches ripcurl-o11y's outer jsonrpc.server observation with mcp.method.name / mcp.protocol.version tags (joining inbound W3C trace context from the _meta envelope); a per-handler interceptor emits an inner mcp.handler.execution observation carrying GenAI / MCP-resource attrs (gen_ai.tool.name, gen_ai.prompt.name, mcp.resource.uri). Self-sufficient — transitively pulls spring-boot-micrometer-observation so an ObservationRegistry is always present. See Observability.
mocapi-otel — drop-in OpenTelemetry tracing. Source-less dependency bundle that pulls mocapi-o11y plus spring-boot-starter-opentelemetry (OTel SDK + Micrometer Observation → OTel tracing bridge + autoconfig). Add this module plus the exporter for your backend — OTLP for Jaeger/Tempo, Azure Monitor starter for App Insights, Datadog, etc. — and jsonrpc.server / mcp.handler.execution spans flow end-to-end. See OTel guide.
mocapi-audit — structured audit logging for every MCP handler invocation. Emits one INFO event on the mocapi.audit SLF4J logger per call with caller identity, protocol version, client name, handler kind/name, outcome (success/forbidden/invalid_params/error), duration, and (opt-in) a SHA-256 hash of the arguments — everything compliance / SIEM queries need, nothing PII-shaped. See Audit.
mocapi-actuator — Spring Boot Actuator endpoint (/actuator/mcp) exposing a read-only inventory of the tools, prompts, resources, and resource templates registered on this node. Publishes handler names + schema digests. See Actuator Endpoint.
mocapi-apps — the MCP Apps server surface (io.modelcontextprotocol/ui). Declare ui:// HTML resources with @McpAppResource (or serve a classpath bundle via @McpUi(resource=…)) and link them to tools with @McpUi; contributes the ui capability plus _meta.ui (CSP/sandbox) on descriptors, and fails startup fast on a @McpUi pointing at an undeclared resource. mocapi is the server half only — the in-iframe JS is the host's and the official ext-apps SDK's. See MCP Apps.
mocapi-tasks — the MCP Tasks extension (io.modelcontextprotocol/tasks). Add @McpTask to a tool and task-capable clients get a polled background task (tasks/get / tasks/update / tasks/cancel) while everyone else runs it synchronously — the tool body never changes. Progress emitters feed the task's statusMessage; mid-task elicitation replays through a pluggable TaskStore (in-memory default with a multi-node warning; ship your own store bean for clusters and prove it with the bundled contract TCK). See MCP Tasks.
mocapi-autoconfigure — one module hosting every mocapi autoconfig (pulled in by either transport starter; you normally don't depend on it directly).
Prompt templating (optional)
mocapi-prompts-spring — PromptTemplateFactory using Spring's ${name} placeholder syntax; no extra dependencies
mocapi-prompts-mustache — PromptTemplateFactory backed by JMustache for richer {{name}} templates with sections
Bill of Materials (optional)
mocapi-bom — imports into your <dependencyManagement> to align versions across multiple mocapi artifacts without hard-coding each one
The tasks example on a durable Redis TaskStore (mocapi-tasks-substrate): Spring Boot's Docker Compose support starts Redis, and task state survives application restarts — kill the app at input_required, restart, answer, and MRTR replay completes the task
Mocapi targets the MCP 2026-07-28 specification and is validated against the official conformance suite: core 79 checks pass / 13 baselined; tasks extension 33 pass / 2 baselined — every baselined failure is a deliberate omission (see ADR-0022) or a documented suite defect, not a protocol-correctness gap. Mocapi passes every check that tests actual protocol behavior. The expected-failures baseline records each exception with its reason; see mocapi-conformance/README.md to reproduce:
# Start the conformance server
cd mocapi-conformance
mvn spring-boot:run
# In another terminal
npx @modelcontextprotocol/conformance server --url http://localhost:8081/mcp
Building from Source
mvn clean install
Requires Java 25+ and Maven 3.9+.
Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Mocapi is a made-up word that includes the letters MCP (Model Context Protocol). It's pronounced moh-cap-ee (/ˈmoʊˌkæpi/), like a friendly little robot who speaks protocol.
M
Mocapi
callibrity·2 顆星·
An enterprise-grade Spring Boot framework for stateless Model Context Protocol (MCP) servers in Java (MCP 2026-07-28). OAuth2 resource server, per-handler authorization, OpenTelemetry, Jakarta Validat
An enterprise-grade Spring Boot framework for stateless Model Context Protocol (MCP) servers in Java (MCP 2026-07-28). OAuth2 resource server, per-handler authorization, OpenTelemetry, Jakarta Validation, audit logging, GraalVM native-image — all opt-in via a one-dependency feature-module pattern.
上次檢查時間:2026-10-28。 An enterprise-grade Spring Boot framework for stateless Model Context Protocol (MCP) servers in Java (MCP 2026-07-28). OAuth2 resource server, per-handler authorization, OpenTelemetry, Jakarta Validation, audit logging, GraalVM native-image — all opt-in via a one-dependency feature-module pattern.