Soklet Logo

Model Context Protocol

MCP Quickstart

Build the greeting tool from the homepage, run it on localhost, and call it from an MCP client. You need only JDK 21+ and the Soklet JAR.

The example serves MCP 2026-07-28 and 2025-11-25 at the same URL. The curl call uses the modern profile; the VS Code configuration selects November's profile explicitly.

Create a project

Download soklet-4.0.0.jar into an empty directory, then create the source directories shown below:

soklet-mcp-quickstart/
  soklet-4.0.0.jar
  src/example/
    GreetingsEndpoint.java
    App.java

No other libraries or build tools are required.

Define a tool

Save this as src/example/GreetingsEndpoint.java:

package example;

import com.soklet.McpProtocolVersion;
import com.soklet.annotation.McpServerEndpoint;
import com.soklet.annotation.McpTool;
import com.soklet.annotation.McpToolArgument;

@McpServerEndpoint(
  path = "/greetings/mcp",
  name = "greetings",
  version = "1.0.0",
  protocolVersions = {
    McpProtocolVersion.V2026_07_28,
    McpProtocolVersion.V2025_11_25
  }
)
public final class GreetingsEndpoint {
  public record Greeting(String message) {}

  @McpTool(
    name = "greet",
    description = "Greets someone by name",
    protocolVersions = {
      McpProtocolVersion.V2026_07_28,
      McpProtocolVersion.V2025_11_25
    }
  )
  public Greeting greet(@McpToolArgument(name = "name") String name) {
    return new Greeting("Hello, " + name + "!");
  }
}

Soklet derives and validates the tool's input and output schemas from these Java types. Both the endpoint and the tool declare the exact protocol revisions they serve.

Start the server

Save this as src/example/App.java:

package example;

import com.soklet.McpServer;
import com.soklet.Soklet;
import com.soklet.SokletConfig;

public final class App {
  public static void main(String[] args) throws InterruptedException {
    McpServer mcpServer = McpServer.withPort(8082)
      .host("127.0.0.1")
      .build();

    SokletConfig config = SokletConfig.withMcpServer(mcpServer).build();

    System.out.println("Starting MCP at http://127.0.0.1:8082/greetings/mcp");
    Soklet soklet = Soklet.run(config);
    soklet.awaitShutdown();
  }
}

From the project directory, compile the application:

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

The -parameters flag preserves Java parameter names. The explicit -processor flag enables Soklet's annotation processor, which generates the endpoint metadata needed at runtime, including on JDK 23+.

Start the server:

java -cp "build:soklet-4.0.0.jar" example.App

The classpath separator is : on macOS/Linux. On Windows, use "build;soklet-4.0.0.jar" instead.

The server discovers the generated endpoint metadata on the classpath and listens on 127.0.0.1:8082. Keep this application terminal open while calling the tool from another terminal. Use Ctrl+C in the application terminal to request JVM shutdown and join bounded lifecycle finalization.

MCP uses its own listener. This example needs neither a regular HTTP server nor a separate SSE server.

Call the tool

In a second terminal, run:

curl --fail-with-body --silent --show-error \
  http://127.0.0.1:8082/greetings/mcp \
  --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: greet' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "greet",
      "arguments": {"name": "Ada"},
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

The JSON-RPC response contains the structured greeting:

{"message":"Hello, Ada!"}

The modern profile needs no initialization handshake. Each request states its version and capabilities, and the Mcp-Method and Mcp-Name headers must match the JSON body. To inspect the endpoint's catalog, see discovery over HTTP.

Connect Visual Studio Code

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "soklet-greetings": {
      "type": "http",
      "url": "http://127.0.0.1:8082/greetings/mcp",
      "headers": {
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Start the configured MCP connection in VS Code, enable the greet tool for your agent, and ask it to greet Ada. Approve the tool invocation when the client asks.

This client uses the endpoint's 2025-11-25 profile: it initializes before calling tools and uses that revision's request format. The explicit version header is needed for the tested VS Code configuration. Sessions remain disabled in this example. Other clients must support one of the endpoint's declared revisions; check Compatibility and Scope before configuring them.

Troubleshooting and next steps

  • No endpoints discovered: enable SokletProcessor, rebuild, and retain the generated classes and META-INF/soklet resources on the runtime classpath. See compile-time descriptors for packaging and shading.
  • Port already in use: change withPort(8082) and update the port in your client URL.
  • HTTP 400 on a client call: use a declared protocol revision and its matching request format. The modern curl headers and _meta fields belong to 2026-07-28; the VS Code configuration selects 2025-11-25.
  • Every tool call returns -32603 "Internal error": Soklet could not run your handler. A common cause is an endpoint class without an accessible no-argument constructor: add one, or configure an InstanceProvider that can create the class. The server still starts and lists its tools, and the default log line omits the cause. Implement LifecycleObserver::didFinishMcpRequestHandling, described in Observability and Testing, to see the throwable.

This local example accepts anonymous requests and configures no application rate quota. Before exposing it remotely, configure authentication, authorization, public hosts, TLS termination, and deployment-appropriate rate limiting. Security and Policy, OAuth Integration, and Production Readiness cover those choices.

To serve an HTTP API and an MCP tool from the same service, follow the HTTP + MCP App. For an existing Maven or Gradle project, see Building and Running. Continue with Endpoint Authoring and Tools and Schemas to build tools around your own application services.

Previous
MCP Overview
Next
Endpoint Authoring