Soklet

Soklet is a small Java library for building HTTP APIs, Model Context Protocol (MCP) servers, and Server-Sent Event (SSE) systems. Author typed Java handlers with clear HTTP and MCP semantics and built-in testing support. Bring your own application services and dependency injection.

Build HTTP APIs and MCP endpoints around the same application logic; the HTTP + MCP App shows a small example. Soklet embraces the Unix philosophy: build tools that each do one thing well, then let agents compose them into applications. Soklet handles the HTTP and MCP plumbing. You choose your database, JSON library, authentication, and other application infrastructure; the Toy Store App shows how those pieces fit together.

Soklet is commercially-friendly Open Source Software, proudly powering production systems since 2015.

Design Goals

First-class support for Model Context Protocol: typed tools, prompts, and resources for AI agents
Route HTTP/1.1 requests to typed Java methods
Built-in support for Server-Sent Events
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
Fine-grained telemetry and metrics collection
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

Installation

Soklet is a single JAR, available on Maven Central.

JDK 21+ is required for Soklet and its Servlet and OpenTelemetry adapters, including HTTP, SSE, and the dedicated MCP server.

For the required annotation-processor setup, see Building and Running.

Maven

<dependency>
  <groupId>com.soklet</groupId>
  <artifactId>soklet</artifactId>
  <version>4.0.0</version>
</dependency>

<dependency>
  <groupId>com.soklet</groupId>
  <artifactId>soklet</artifactId>
  <version>4.0.0</version>
</dependency>

Gradle

dependencies {
  implementation 'com.soklet:soklet:4.0.0'
}

dependencies {
  implementation 'com.soklet:soklet:4.0.0'
}

Direct Download

If you don't use Maven or Gradle, you can drop soklet-4.0.0.jar directly into your project. No other dependencies are required.

For startup, scoped execution, and embedded hosts, see Application Lifecycle.

Example Usage

Here we demonstrate building and running a single-file "hello world" HTTP API app with nothing but the soklet-4.0.0.jar and the JDK. There are no other libraries or frameworks, no Servlet container, no Maven build process - no special setup is required.

While a real production system will have more moving parts, this demonstrates that you can build server software without ceremony or dependencies.

Source Code

package com.soklet.example;

import com.soklet.*;
import com.soklet.annotation.*;

import java.time.*;
import java.util.*;

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á)
  // See "Request Handling" and "Response Writing"
  // for how data is parsed from the request and written to the response
  @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", List.of(contentLanguage)))
      .cookies(List.of(
        ResponseCookie.withName("lastRequest")
          .value(Instant.now().toString())
          .httpOnly(true)
          .secure(true)
          .maxAge(Duration.ofMinutes(5))
          .sameSite(ResponseCookie.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 sokletConfig = SokletConfig.withHttpServer(
      HttpServer.fromPort(8080)
    ).build();

    System.out.println("Starting Soklet");
    Soklet soklet = Soklet.run(sokletConfig);
    soklet.awaitShutdown();
  }
}

package com.soklet.example;

import com.soklet.*;
import com.soklet.annotation.*;

import java.time.*;
import java.util.*;

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á)
  // See "Request Handling" and "Response Writing"
  // for how data is parsed from the request and written to the response
  @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", List.of(contentLanguage)))
      .cookies(List.of(
        ResponseCookie.withName("lastRequest")
          .value(Instant.now().toString())
          .httpOnly(true)
          .secure(true)
          .maxAge(Duration.ofMinutes(5))
          .sameSite(ResponseCookie.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 sokletConfig = SokletConfig.withHttpServer(
      HttpServer.fromPort(8080)
    ).build();

    System.out.println("Starting Soklet");
    Soklet soklet = Soklet.run(sokletConfig);
    soklet.awaitShutdown();
  }
}

Want a better understanding of Soklet's capabilities? Start with Request Handling.

Want to build a tool that an AI agent can call? The MCP Quickstart takes you from an empty project to a running server and client call.

Want a minimum-viable "hello world" app you can easily clone and run? Check out the Barebones App.

Want to see how a real-world Soklet app looks? The Toy Store App covers topics like JSON marshaling, dependency injection, authentication/authorization, talking to a database, error handling, internationalization, and more.

Building and Running

You'll need to provide javac with these flags:

-parameters
-processor com.soklet.SokletProcessor

JDK 21+ is required.

If you need a JDK, Amazon provides Corretto - a free-to-use-commercially, production-ready distribution of OpenJDK that includes long-term support. Official Corretto Docker Images are also available.

Where's Maven? Where's Gradle?

The examples below use javac to build and java to run. Soklet systems can be structurally as simple as a "hello world" app.

For Maven and Gradle configuration, see Building and Running. The Toy Store App shows a complete Maven application.

Build

% javac -parameters -cp soklet-4.0.0.jar -processor com.soklet.SokletProcessor -d build src/com/soklet/example/App.java

% javac -parameters -cp soklet-4.0.0.jar -processor com.soklet.SokletProcessor -d build src/com/soklet/example/App.java

Run

% java -cp soklet-4.0.0.jar:build com/soklet/example/App

% java -cp soklet-4.0.0.jar:build com/soklet/example/App

Test

# 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!

# 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!

# 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

# 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

# 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

# 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

# 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á)

# 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á)

Credits

Soklet stands on the shoulders of giants. Internally, it embeds code from the following OSS projects, all of which have licenses that are suitable for commercial use:

Microhttp by Elliot Barlas - MIT License
Selenium - Apache 2.0 License
Apache Commons FileUpload - Apache 2.0 License
The Spring Framework - Apache 2.0 License

Do Zero-Dependency Libraries Interest You?

Similarly-flavored commercially-friendly OSS libraries are available. Pyranid is a modern JDBC interface that embraces SQL instead of an ORM, and Lokalized enables natural-sounding translations (i18n) via an expression language.