# Soklet > Soklet is a zero-dependency Java HTTP/1.1 and Server-Sent Event + MCP server, well-suited for building RESTful APIs and tool-backed agentic systems. - **Type:** MCP server - **Install:** `agentstack add mcp-soklet-soklet` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [soklet](https://agentstack.voostack.com/s/soklet) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [soklet](https://github.com/soklet) - **Source:** https://github.com/soklet/soklet - **Website:** https://www.soklet.com ## Install ```sh agentstack add mcp-soklet-soklet ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About [](https://central.sonatype.com/artifact/com.soklet/soklet) [](https://github.com/soklet/soklet/actions/workflows/ci.yml) [](https://javadoc.soklet.com) [](CHANGELOG.md) ### What Is It? A small [HTTP/1.1 server](https://github.com/ebarlas/microhttp) and route handler for Java, well-suited for building RESTful APIs, broadcasting [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events), and providing [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) functionality. Zero dependencies. Dependency Injection friendly. Optionally powered by [JEP 444: Virtual Threads](https://openjdk.org/jeps/444). Soklet codes like a library, not a framework. **Note: this README provides a high-level overview of Soklet.** **For details, please refer to the official documentation at [https://www.soklet.com](https://www.soklet.com).** ### Why? The Java web ecosystem is missing an HTTP server solution that is dependency-free but offers support for [Server-Sent Events (SSE)](/docs/server-sent-events) and [Model Context Protocol (MCP)](/docs/mcp) along with hooks for dependency injection and annotation-based request handling. Soklet aims to fill this void. Soklet provides the plumbing to build "transactional" REST APIs as well as agentic systems that vend results via [HTTP response streaming](https://www.soklet.com/docs/response-writing#streaming-responses) or [SSE](https://www.soklet.com/docs/server-sent-events), and expose tools, prompts, and resources via [MCP](https://www.soklet.com/docs/mcp). It does not make technology choices on your behalf (but [an example of how to build a full-featured API is available](https://www.soklet.com/docs/toystore-app)). It does not natively support [Reactive Programming](https://en.wikipedia.org/wiki/Reactive_programming) or similar methodologies. It _does_ give you the foundation to build your system, your way. Soklet is [commercially-friendly Open Source Software](https://www.soklet.com/docs/licensing), proudly powering production systems since 2015. ### Design Goals - Main focus: routing HTTP/1.1 requests to Java methods - Near-instant startup - Zero dependencies - Immutability/thread-safety - Small, comprehensible codebase - auditable end-to-end by a human or AI agent - No runtime classpath scanning or autoconfiguration (explicit behavior, statically analyzable) - Contract/interface-driven: bring your own implementations for almost anything - Thorough, high-quality documentation - Extensive support for [automated unit and integration testing](https://www.soklet.com/docs/testing) - Fine-grained [telemetry and metrics collection](https://www.soklet.com/docs/metrics-collection) - Best-in-class support for [Server-Sent Events](https://www.soklet.com/docs/server-sent-events) - First-class support for [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - [Servlet Integration](https://www.soklet.com/docs/servlet-integration) for legacy code ### Design Non-Goals - SSL/TLS (your load balancer should provide TLS termination) - HTTP/2, HTTP/3 (also handled by your load balancer) - WebSockets - Dictate which technologies to use (Guice vs. Dagger, Gson vs. Jackson, etc.) - "Batteries included" authentication and authorization ### Do Zero-Dependency Libraries Interest You? Similarly-flavored commercially-friendly OSS libraries are available. - [Pyranid](https://www.pyranid.com) - makes working with JDBC pleasant - [Lokalized](https://www.lokalized.com) - natural-sounding translations (i18n) via expression language ### License [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) ### Installation Soklet is a single JAR, available on Maven Central. JDK 17+ is required (or JDK 21+ for [Server-Sent Events](https://www.soklet.com/docs/server-sent-events) and [MCP](https://www.soklet.com/docs/mcp)). #### Maven ```xml com.soklet soklet 3.4.0 ``` #### Gradle ```groovy repositories { mavenCentral() } dependencies { implementation 'com.soklet:soklet:3.4.0' } ``` #### Direct Download If you don't use Maven or Gradle, you can drop [soklet-3.4.0.jar](https://repo1.maven.org/maven2/com/soklet/soklet/3.4.0/soklet-3.4.0.jar) directly into your project. No other dependencies are required. ### Code Sample Here we demonstrate building and running a single-file Soklet application with nothing but the [soklet-3.4.0.jar](https://repo1.maven.org/maven2/com/soklet/soklet/3.4.0/soklet-3.4.0.jar) and the JDK. There are no other libraries or frameworks, no Servlet container, no Maven or Gradle build process - no special setup is required. Soklet systems can be structurally as simple as a "hello world" app. While a real production system will have more moving parts, this demonstrates that you _can_ build server software without ceremony or dependencies. ```java package com.soklet.example; public class App { // Canonical example @GET("/") public String index() { return "Hello, world!"; } // Echoes back the path parameter, which must be a LocalDate @GET("/echo/{date}") public LocalDate echo(@PathParameter LocalDate date) { return date; } // Formats request body locale for display and customizes the response. // Example: fr-CA ⇒ francês (Canadá) @POST("/language") public Response languageFor(@RequestBody Locale locale) { Locale systemLocale = Locale.forLanguageTag("pt-BR"); String contentLanguage = systemLocale.toLanguageTag(); return Response.withStatusCode(200) .body(locale.getDisplayName(systemLocale)) .headers(Map.of("Content-Language", Set.of(contentLanguage))) .cookies(Set.of( ResponseCookie.withName("lastRequest") .value(Instant.now().toString()) .httpOnly(true) .secure(true) .maxAge(Duration.ofMinutes(5)) .sameSite(SameSite.LAX) .build() )) .build(); } // Start the server and listen on :8080 public static void main(String[] args) throws Exception { // Use out-of-the-box defaults SokletConfig config = SokletConfig.withHttpServer( HttpServer.fromPort(8080) ).build(); try (Soklet soklet = Soklet.fromConfig(config)) { soklet.start(); System.out.println("Soklet started, press [enter] to exit"); soklet.awaitShutdown(ShutdownTrigger.ENTER_KEY); } } } ``` Here we use raw `javac` to build and `java` to run. This example requires JDK 17+ to be installed on your machine ([or see this example of using Docker for Soklet apps](https://github.com/soklet/barebones-app?tab=readme-ov-file#building-and-running-with-docker)). If you need a JDK, Amazon provides [Corretto](https://aws.amazon.com/corretto/) - a free-to-use-commercially, production-ready distribution of [OpenJDK](https://openjdk.org/) that includes long-term support. #### Build ```shell javac -parameters -cp soklet-3.4.0.jar -processor com.soklet.SokletProcessor -d build src/com/soklet/example/App.java ``` #### Run ```shell java -cp soklet-3.4.0.jar:build com/soklet/example/App ``` #### Test ```shell # Hello, world % curl -i 'http://localhost:8080/' HTTP/1.1 200 OK Content-Length: 13 Content-Type: text/plain; charset=UTF-8 Date: Sun, 21 Mar 2024 16:19:01 GMT Hello, world! ``` ```shell # Acceptable path parameter % curl -i 'http://localhost:8080/echo/2024-12-31' HTTP/1.1 200 OK Content-Length: 10 Content-Type: text/plain; charset=UTF-8 Date: Sun, 21 Mar 2024 16:19:01 GMT 2024-12-31 ``` ```shell # Illegal path parameter % curl -i 'http://localhost:8080/echo/abc' HTTP/1.1 400 Bad Request Content-Length: 21 Content-Type: text/plain; charset=UTF-8 Date: Sun, 21 Mar 2024 16:19:01 GMT HTTP 400: Bad Request ``` ```shell # Language request body % curl -i -X POST 'http://localhost:8080/language' -d 'fr-CA' HTTP/1.1 200 OK Content-Language: pt-BR Content-Length: 18 Content-Type: text/plain; charset=UTF-8 Date: Sun, 21 Mar 2024 16:19:01 GMT Set-Cookie: lastRequest=2024-04-21T16:19:01.115336Z; Max-Age=300; Secure; HttpOnly; SameSite=Lax francês (Canadá) ``` ### Building Real-World Apps Of course, real-world apps have more moving parts than a "hello world" example. [The Toy Store App](https://www.soklet.com/docs/toystore-app) showcases how you might build a robust production system with Soklet. Feature highlights include: - Authentication and role-based authorization - Basic CRUD operations - Dependency injection via [Google Guice](https://github.com/google/guice) - Relational database integration via [Pyranid](https://www.pyranid.com) - Context-awareness via [ScopedValue (JEP 481)](https://openjdk.org/jeps/481) - Internationalization via the JDK and [Lokalized](https://www.lokalized.com) - JSON requests/responses via [Gson](https://github.com/google/gson) - Logging via [SLF4J](https://slf4j.org/) / [Logback](https://logback.qos.ch/) - Metrics collection via [`MetricsCollector`](https://javadoc.soklet.com/com/soklet/MetricsCollector.html) - Automated unit and integration tests via [JUnit](https://junit.org) - Ability to run in [Docker](https://www.docker.com/) ### What Else Does It Do? #### Request Handling Soklet maps HTTP requests to plain Java methods known as Resource Methods ([`ResourceMethod`](https://javadoc.soklet.com/com/soklet/ResourceMethod.html)). Annotate them with [`@GET`](https://javadoc.soklet.com/com/soklet/annotation/GET.html), [`@POST`](https://javadoc.soklet.com/com/soklet/annotation/POST.html), [`@PUT`](https://javadoc.soklet.com/com/soklet/annotation/PUT.html), [`@PATCH`](https://javadoc.soklet.com/com/soklet/annotation/PATCH.html), [`@DELETE`](https://javadoc.soklet.com/com/soklet/annotation/DELETE.html), [`@HEAD`](https://javadoc.soklet.com/com/soklet/annotation/HEAD.html), [`@OPTIONS`](https://javadoc.soklet.com/com/soklet/annotation/OPTIONS.html), or [`@SseEventSource`](https://javadoc.soklet.com/com/soklet/annotation/SseEventSource.html) for SSE. MCP endpoints are declared separately with [`@McpServerEndpoint`](https://javadoc.soklet.com/com/soklet/annotation/McpServerEndpoint.html) and handler annotations like [`@McpTool`](https://javadoc.soklet.com/com/soklet/annotation/McpTool.html), [`@McpPrompt`](https://javadoc.soklet.com/com/soklet/annotation/McpPrompt.html), and [`@McpResource`](https://javadoc.soklet.com/com/soklet/annotation/McpResource.html). Soklet discovers them at compile time via the [`SokletProcessor`](https://javadoc.soklet.com/com/soklet/SokletProcessor.html) annotation processor, avoiding classpath scans at startup. See the [Request Handling](https://www.soklet.com/docs/request-handling) docs for details. #### Access To Request Data Resource Methods ([`ResourceMethod`](https://javadoc.soklet.com/com/soklet/ResourceMethod.html)) can accept a [`Request`](https://javadoc.soklet.com/com/soklet/Request.html) parameter and inspect [`HttpMethod`](https://javadoc.soklet.com/com/soklet/HttpMethod.html) values. ```java @GET("/example") public void example(Request request /* param name is arbitrary */) { // Here, it would be HttpMethod.GET HttpMethod httpMethod = request.getHttpMethod(); // Just the path, e.g. "/example" String path = request.getPath(); // The raw path and query, e.g. "/example?test=123" String rawPathAndQuery = request.getRawPathAndQuery(); // Request body as bytes, if available Optional body = request.getBody(); // Request body marshaled to a string, if available. // Charset defined in "Content-Type" header is used to marshal. // If not specified, UTF-8 is assumed Optional bodyAsString = request.getBodyAsString(); // Query parameter values by name Map> queryParameters = request.getQueryParameters(); // Shorthand for plucking the first query param value by name Optional queryParameter = request.getQueryParameter("test"); // Header values by name (names are case-insensitive) Map> headers = request.getHeaders(); // Shorthand for plucking the first header value by name (case-insensitive) Optional header = request.getHeader("Accept-Language"); // Parsed W3C trace context from traceparent/tracestate, if present Optional traceContext = request.getTraceContext(); // Request cookies by name (names are case-insensitive) Map> cookies = request.getCookies(); // Shorthand for plucking the first cookie value by name (case-insensitive) Optional cookie = request.getCookie("cookie-name"); // Form parameters by name (application/x-www-form-urlencoded) Map> fps = request.getFormParameters(); // Shorthand for plucking the first form parameter value by name Optional fp = request.getFormParameter("fp-name"); // Is this a multipart request? boolean multipart = request.isMultipart(); // Multipart fields by name Map> mpfs = request.getMultipartFields(); // Shorthand for plucking the first multipart field by name Optional mpf = request.getMultipartField("file-input"); // CORS information, if available Optional cors = request.getCors(); // Ordered locales via Accept-Language parsing List locales = request.getLocales(); // Charset as specified by "Content-Type" header, if available Optional charset = request.getCharset(); // Content type component of "Content-Type" header, if available Optional contentType = request.getContentType(); } ``` #### Value Conversions Soklet converts textual request inputs to Java types using a [`ValueConverterRegistry`](https://javadoc.soklet.com/com/soklet/converter/ValueConverterRegistry.html) populated with [`ValueConverter`](https://javadoc.soklet.com/com/soklet/converter/ValueConverter.html). Conversions are applied to parameters annotated with [`@QueryParameter`](https://javadoc.soklet.com/com/soklet/annotation/QueryParameter.html), [`@PathParameter`](https://javadoc.soklet.com/com/soklet/annotation/PathParameter.html), [`@RequestHeader`](https://javadoc.soklet.com/com/soklet/annotation/RequestHeader.html), [`@RequestCookie`](https://javadoc.soklet.com/com/soklet/annotation/RequestCookie.html), [`@FormParameter`](https://javadoc.soklet.com/com/soklet/annotation/FormParameter.html), and [`@Multipart`](https://javadoc.soklet.com/com/soklet/annotation/Multipart.html). Supply your own registry (or additional converters) via [`SokletConfig`](https://javadoc.soklet.com/com/soklet/SokletConfig.html) to support custom types. #### Request Body Parsing Configure a [`RequestBodyMarshaler`](https://javadoc.soklet.com/com/soklet/RequestBodyMarshaler.html) however you like - here we accept JSON: ```java SokletConfig config = SokletConfig.withHttpServer( HttpServer.fromPort(8080) ).requestBodyMarshaler(new RequestBodyMarshaler() { // This example uses Google's GSON static final Gson GSON = new Gson(); @NonNull @Override public Optional marshalRequestBody( @NonNull Request request, @NonNull ResourceMethod resourceMethod, @NonNull Parameter parameter, @NonNull Type requestBodyType ) { // Let GSON turn the request body into an instance // of the specified type. // // Note that this method has access to all runtime information // about the request, which provides the opportunity to, for example, // examine annotations on the method/parameter which might // inform custom marshaling strategies. return Optional.of(GSON.fromJson( request.getBodyAsString().orElseThrow(), requestBodyType )); } }).build(); ``` Then, apply: ```java public record Employee ( UUID id, String name ) {} // Accepts a JSON-formatted Record type as input @POST("/employees") public void createEmployee(@RequestBody Employee employee) { System.out.printf("TODO: create %s\n", employee.name()); } ``` #### Response Writing To control how response data is surfaced to clients (e.g. JSON), provide handler functions ([`ResourceMethodHandler`](https://javadoc.soklet.com/com/soklet/ResponseMarshaler.ResourceMethodHandler.html) and [`ThrowableHandler`](https://javadoc.soklet.com/com/soklet/ResponseMarshaler.ThrowableHandler.html)) to Soklet as shown below. … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [soklet](https://github.com/soklet) - **Source:** [soklet/soklet](https://github.com/soklet/soklet) - **License:** Apache-2.0 - **Homepage:** https://www.soklet.com Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-soklet-soklet - Seller: https://agentstack.voostack.com/s/soklet - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.