Model Context Protocol
Model Context Protocol
Soklet provides a Java-first server implementation of the Model Context Protocol. It exposes tools, prompts, resources, Skills, Apps metadata and UI resources, and durable Tasks over a dedicated HTTP listener while Soklet owns protocol validation, bounded execution, streaming, policy hooks, and wire serialization.
Soklet supports MCP 2026-07-28 and explicitly selected 2025-06-18 and 2025-11-25 compatibility profiles. Both 2025 profiles support synchronous tools, ordinary prompts and resources, argument completion, POST progress, and static catalog pagination. Optional sessions retain public client metadata and enable active-request cancelation. With HTTP transport admission, selected subscriptions, and effective change sources, those sessions also support authorized resource/catalog notification delivery over GET. Skills, Apps UI, durable Tasks, and multi-round input remain exclusive to 2026-07-28. See Compatibility and Scope for the complete supported profiles and limits.
Start with the MCP Quickstart for a complete greeting server using only the JDK and Soklet JAR, a curl call, and VS Code setup.
The model at a glance
- An
McpServerhas its own HTTP/1.1 listener and port. It is not mounted in Soklet's ordinary HTTP or SSE server. - The
2026-07-28path is stateless and starts without an initialization handshake. Both 2025 profiles start withinitialize; sessions are disabled by default. Explicit session configuration enables session IDs, remembered public client information/capabilities, and active-request cancelation. - One server can host multiple exact, non-root endpoint paths. Each endpoint has its own operation catalog and derived capabilities.
2026-07-28clients may callserver/discoveras their first request. Clients connect to the endpoint URL configured for them. Each endpoint and operation selects exact protocol revisions; there is no implicit latest revision. See version selection for 2025 initialization negotiation and subsequent version headers.- Modern and session-disabled 2025 requests do not require session affinity. Explicitly enabled 2025 sessions are node-local: initialization and later POST, GET, and DELETE requests must reach the same node. Node loss requires client reinitialization and resubscription. See multi-node deployments.
- On
2026-07-28, an application-ownedMcpTaskManagerbacked by shared durable infrastructure lets task work survive a client disconnect or server-node loss without introducing session affinity. - MCP messages use
POST;OPTIONSexists for CORS preflight. Modern and session-disabled 2025 views return405for GET/DELETE. Session-enabled 2025 views can enable freshly admitted DELETE to retire a session and, with selected subscriptions and effective change sources, leased GET to deliver authorized URI/catalog invalidations. GET admission alone grants no URI permission. See HTTP transport admission and legacy notification delivery. - The API runs on JDK 21 or newer and remains in the zero-runtime-dependency
com.soklet:sokletartifact.
The primary object graph is:
SokletConfig
└── McpServer
├── listener, limits, policy, protection, and observation
├── optional application-owned McpTaskManager
└── McpEndpointRegistry
└── one or more McpEndpoint values
├── tool registrations
├── prompt registrations
├── resource registrations and optional list handler
├── optional Skill bundles and locale groups
└── optional resource-subscription configuration
SokletConfig
└── McpServer
├── listener, limits, policy, protection, and observation
├── optional application-owned McpTaskManager
└── McpEndpointRegistry
└── one or more McpEndpoint values
├── tool registrations
├── prompt registrations
├── resource registrations and optional list handler
├── optional Skill bundles and locale groups
└── optional resource-subscription configuration
Minimal annotated endpoint
Annotations are processed at compile time by SokletProcessor; Soklet does not scan handler methods at runtime. Apply the Maven or Gradle processor setup before compiling the endpoint, and retain its generated classes and META-INF/soklet resources when packaging.
@McpServerEndpoint(
path = "/catalog/mcp",
name = "catalog",
version = "1.0.0",
instructions = "Use catalog.search for catalog lookups.",
protocolVersions = {McpProtocolVersion.V2026_07_28}
)
public final class CatalogEndpoint {
public record SearchResult(List<String> matches) {}
@McpTool(
name = "catalog.search",
title = "Catalog search",
description = "Searches the catalog",
protocolVersions = {McpProtocolVersion.V2026_07_28}
)
public SearchResult search(
@McpToolArgument(name = "query") String query,
@McpToolArgument(name = "limit") Optional<Integer> limit) {
return new SearchResult(searchCatalog(
query, limit.orElse(10)
));
}
}
@McpServerEndpoint(
path = "/catalog/mcp",
name = "catalog",
version = "1.0.0",
instructions = "Use catalog.search for catalog lookups.",
protocolVersions = {McpProtocolVersion.V2026_07_28}
)
public final class CatalogEndpoint {
public record SearchResult(List<String> matches) {}
@McpTool(
name = "catalog.search",
title = "Catalog search",
description = "Searches the catalog",
protocolVersions = {McpProtocolVersion.V2026_07_28}
)
public SearchResult search(
@McpToolArgument(name = "query") String query,
@McpToolArgument(name = "limit") Optional<Integer> limit) {
return new SearchResult(searchCatalog(
query, limit.orElse(10)
));
}
}
With generated endpoint metadata on the classpath, create mcpServer using the local development configuration, then attach it to Soklet:
SokletConfig config = SokletConfig.withMcpServer(mcpServer).build();
Soklet soklet = Soklet.run(config);
soklet.awaitShutdown();
SokletConfig config = SokletConfig.withMcpServer(mcpServer).build();
Soklet soklet = Soklet.run(config);
soklet.awaitShutdown();
Soklet.run(config) installs a JVM shutdown hook by default, coordinates every configured transport, and returns the Soklet instance after readiness. awaitShutdown() observes full finalization and returns the immutable ShutdownResult, or throws the lifecycle failure. awaitShutdownAsync() exposes the same outcome without blocking. Neither await method requests shutdown.
For tests and finite embedded work, Soklet.run(config, () -> { /* application work */ }) starts before the callback and requests/awaits shutdown when it ends. The callback runs on the caller, may throw checked exceptions, and receives no lifecycle handle. Startup failure skips it; callback failures are preserved after teardown with any lifecycle failure suppressed. The callback itself is not forcibly stopped by external shutdown. Supply a ShutdownCleanup with either explicit or scoped execution when resources require bounded cleanup after complete core shutdown. Explicit hosts request and await termination before closing shared dependencies. Console interaction is application-owned; see Server Configuration for complete examples.
The default admission controller accepts anonymous requests and is appropriate only for a deliberately public endpoint. Override it with admissionController(...) when the server requires authentication or authorization.
Discover and invoke over HTTP
With the example above running on port 8082, discover its catalog:
curl --fail-with-body --silent --show-error \
--request POST http://127.0.0.1:8082/catalog/mcp \
--header 'Host: 127.0.0.1:8082' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--header 'MCP-Protocol-Version: 2026-07-28' \
--header 'Mcp-Method: server/discover' \
--data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
curl --fail-with-body --silent --show-error \
--request POST http://127.0.0.1:8082/catalog/mcp \
--header 'Host: 127.0.0.1:8082' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--header 'MCP-Protocol-Version: 2026-07-28' \
--header 'Mcp-Method: server/discover' \
--data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
Call the tool with a Mcp-Name header matching its JSON name:
curl --fail-with-body --silent --show-error \
--request POST http://127.0.0.1:8082/catalog/mcp \
--header 'Host: 127.0.0.1:8082' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--header 'MCP-Protocol-Version: 2026-07-28' \
--header 'Mcp-Method: tools/call' \
--header 'Mcp-Name: catalog.search' \
--data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"catalog.search","arguments":{"query":"sprocket","limit":10},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
curl --fail-with-body --silent --show-error \
--request POST http://127.0.0.1:8082/catalog/mcp \
--header 'Host: 127.0.0.1:8082' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json, text/event-stream' \
--header 'MCP-Protocol-Version: 2026-07-28' \
--header 'Mcp-Method: tools/call' \
--header 'Mcp-Name: catalog.search' \
--data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"catalog.search","arguments":{"query":"sprocket","limit":10},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
These local examples use anonymous admission. Supply the application's required authorization credentials when connecting to an authenticated endpoint. Mcp-Name selects the tool or prompt name, resource URI, or task ID as appropriate. Discovery and other methods with no such selector must omit Mcp-Name; an unexpected name header is rejected as a header mismatch. Each mirrored value is limited to 16 KiB of decoded UTF-8 bytes, including resource URIs in Mcp-Name and custom Mcp-Param-* strings. Base64 encoding does not increase this allowance, and all headers must fit the aggregate HTTP header limit as well. For complete runnable source and client configuration, see the MCP Quickstart.
Selecting versions for 2025 clients
The annotated example above selects only 2026-07-28. To serve either 2025 revision at that URL, add the exact versions to both the endpoint annotation and the tool annotation, then recompile:
protocolVersions = {
McpProtocolVersion.V2025_06_18,
McpProtocolVersion.V2025_11_25,
McpProtocolVersion.V2026_07_28
}
protocolVersions = {
McpProtocolVersion.V2025_06_18,
McpProtocolVersion.V2025_11_25,
McpProtocolVersion.V2026_07_28
}
The client uses the configured URL, sends a 2025 initialize request, and sends the selected MCP-Protocol-Version header on later calls. It uses 2025 body framing; modern mirrored headers and modern _meta capability/version fields are unnecessary. Soklet does not create a second endpoint URL. This tool's object-shaped SearchResult works on both 2025 revisions. Sessions remain disabled until explicitly selected and configured. See Compatibility for the supported facilities and Endpoint Authoring for sessions and cancellation.
Clients that omit the version header on later calls, including affected VS Code configurations, need a dedicated endpoint serving exactly one overall revision, such as McpProtocolVersion.V2025_11_25. Declare that revision on the endpoint and its operations and configure the dedicated URL in the client. Headerless inference is unavailable on a mixed-revision endpoint, even with a session ID. A static 2025 header must select a configured legacy revision; it cannot make a 2025 initialization body use modern framing.
Programmatic endpoint
Programmatic registration produces the same immutable runtime model:
record SearchArguments(String query, Optional<Integer> limit) {}
record SearchResult(List<String> matches) {}
McpToolRegistration<SearchArguments> search = McpToolRegistration
.withName("catalog.search", Set.of(McpProtocolVersion.V2026_07_28))
.argumentAndOutputTypes(SearchArguments.class, SearchResult.class)
.handler((requestContext, arguments, invocationFeatures) ->
new SearchResult(searchCatalog(
arguments.getConvertedArguments().query(),
arguments.getConvertedArguments().limit().orElse(10)
)))
.title("Catalog search")
.description("Searches the catalog")
.build();
McpImplementation implementation = McpImplementation
.withNameAndVersion("catalog", "1.0.0")
.build();
McpEndpoint endpoint = McpEndpoint.withPath(
"/catalog/mcp", implementation,
Set.of(McpProtocolVersion.V2026_07_28))
.toolRegistrations(List.of(search))
.build();
McpEndpointRegistry registry = McpEndpointRegistry
.fromEndpoints(List.of(endpoint));
record SearchArguments(String query, Optional<Integer> limit) {}
record SearchResult(List<String> matches) {}
McpToolRegistration<SearchArguments> search = McpToolRegistration
.withName("catalog.search", Set.of(McpProtocolVersion.V2026_07_28))
.argumentAndOutputTypes(SearchArguments.class, SearchResult.class)
.handler((requestContext, arguments, invocationFeatures) ->
new SearchResult(searchCatalog(
arguments.getConvertedArguments().query(),
arguments.getConvertedArguments().limit().orElse(10)
)))
.title("Catalog search")
.description("Searches the catalog")
.build();
McpImplementation implementation = McpImplementation
.withNameAndVersion("catalog", "1.0.0")
.build();
McpEndpoint endpoint = McpEndpoint.withPath(
"/catalog/mcp", implementation,
Set.of(McpProtocolVersion.V2026_07_28))
.toolRegistrations(List.of(search))
.build();
McpEndpointRegistry registry = McpEndpointRegistry
.fromEndpoints(List.of(endpoint));
Registration order is discovery order. Tool names, prompt names, exact resource URIs, and resource templates must be unique within an endpoint. Capabilities are derived from the registered operations; there is no second set of capability switches to keep synchronized.
What Soklet implements
| Area | Public surface |
|---|---|
| Authoring | Compile-time annotations or staged programmatic builders; Skills use programmatic registration |
| Tools | Typed or immutable-JSON arguments, derived schemas, typed or explicit results, annotations, rate limits, interception, and sanitization |
| Prompts | Named templates with required or optional string arguments and ordered messages |
| Resources | Exact URIs, bounded URI templates, reads, descriptors, custom pagination, cache hints, and subscriptions |
| Skills | Immutable application-owned bundles, generated manifests, authorized file retrieval, locale groups, and custom pagination |
| Multi-round input | Declared form and URL elicitation with application- or framework-protected retry state |
| Tasks | Durable tool work, polling, input updates, cooperative cancelation, task notifications, and typed deferred-output validation through an application-owned manager |
| Invocation control | Request-scoped progress and cooperative cancelation |
| Policy | Host and Origin checks, default anonymous admission with a custom-controller override, request and tool rate limiting, bounded handler execution |
| Operations | Start/stop, immutable diagnostics, key rotation controls, and deterministic shutdown outcomes |
| Observation | Shared Soklet lifecycle and metrics hosts, trace correlation, and off-network simulation |
API guides by area
- Endpoint Authoring covers annotations, descriptor generation, programmatic endpoints, endpoint registration, and endpoint-local catalogs.
- Tools and Schemas covers the staged builder, typed conversion, schema profile, handler contexts, results, and content types.
- Prompts and Resources covers prompt arguments and messages, resource addressing, listing, pagination, cache policy, and content.
- Skills covers bundle authoring, generated manifests, integration with annotated endpoints, discovery versus access, and exact file retrieval.
- Apps attaches sandboxed web interfaces to tools, with static UI resources, host-mediated interactions, authorization, and useful non-Apps output.
- Input and Request State covers multi-round client requests, retries, state ownership, protection, and key rotation.
- Tasks covers capability negotiation, durable work creation, the manager SPI, polling, input, task cancelation, notifications, reconnects, and simulation.
- Progress and Subscriptions covers invocation features, request progress, cooperative request cancelation, resource and task event publishing, and stream bounds.
- Security and Policy covers admission identity, rate limiting, Host/Origin policy, mirrored headers, interception, and sanitization.
- MCP OAuth Integration shows application-owned token verification, Bearer challenges, scope decisions, and protected resource metadata.
- Server Configuration documents every
McpServer.Buildersetting, defaults, lifecycle, diagnostics, and shutdown. - Observability and Testing covers lifecycle callbacks, semantic metrics, trace correlation, and the simulator.
- Localization localizes framework-owned catalog text per request through a library-neutral, fail-atomic seam.
- Compatibility records wire behavior, unsupported features, and intentionally application-owned responsibilities.
- Production Readiness covers node loss, retry safety, reconnect recovery, durable work, and graceful drain.
- Public API Map organizes public types by functionality and identifies provisional Tasks and 2025 session APIs.
Before remote deployment
Every server must resolve a nonempty McpEndpointRegistry; by default, the builder discovers generated endpoint metadata from the classpath. Tool rate limiting is optional; configure an explicit quota or custom limiter when needed. The default McpAdmissionController accepts anonymous requests, so override it unless the endpoint is deliberately public. The listener binds to 127.0.0.1 by default; configure host(...), allowedHosts(...), authentication, authorization, any application quotas, and TLS termination deliberately before exposing it remotely. If Tasks are enabled, supply a shared durable manager, application worker infrastructure, idempotency, and a fleet-wide broadcast publisher rather than the in-memory development manager. Review MCP Tasks and Failures, Retries, And Durable Work before relying on reconnect or cross-node continuation.
MCP requires HTTP/1.1 between the proxy and Soklet; HTTP/1.0 receives 505. For nginx, configure proxy_http_version 1.1 and disable proxy buffering for SSE responses with proxy_buffering off.
MCP media negotiation requires parameter-free application/json and text/event-stream Accept ranges (apart from q). A range with charset or another media parameter does not match. JSON Content-Type accepts its supported charset parameter and permits an empty trailing parameter delimiter, for example application/json;.

