MCP Server Java SDK

Short answer: The official MCP Java SDK is a library for adding Model Context Protocol servers to Java applications. It lets a server expose tools, resources, prompts, completions, logging and notifications over STDIO, SSE or Streamable HTTP. The stable documentation selector showed v2.0.1 on 2026-09-29, with 2.1.0-SNAPSHOT listed separately. Confirm the version and API signatures in the official repository and MCP documentation before publishing or upgrading.

What the SDK provides

The SDK is not a hosted MCP service. It is a set of Java modules that your process embeds. A server can advertise capabilities during initialization, then handle concurrent client connections and protocol requests.

Capability	What your server can do
Tools	Expose typed operations that a client can discover and invoke.
Resources	Publish data by URI, including resource templates, subscriptions and list-change notifications.
Prompts	Offer reusable prompt templates and prompt requests.
Completions	Return argument suggestions while a client is building a request.
Protocol operations	Negotiate capabilities, send structured logs and notifications, and manage lifecycle messages.

Capabilities are configured; enabling the SDK does not automatically expose every feature. The project describes synchronous and asynchronous programming styles, Reactive Streams on public APIs, Project Reactor internally, and a synchronous facade for blocking applications.

Choose a transport

Transport	Use it when	Operational notes
STDIO	An MCP client launches your server as a child process.	Keep stdout reserved for protocol messages; write diagnostics to stderr.
Streamable HTTP	Clients connect to a remotely deployed HTTP endpoint.	Put authentication, TLS, limits and observability at your application or proxy boundary.
SSE	You maintain a deployment that still requires the older server transport.	The core guide lists SSE, while the 2.x roadmap says SSE is deprecated in favor of Streamable HTTP. Check the selected release guide.

Spring WebFlux and WebMVC transports are no longer shipped in this SDK; Spring AI 2.0+ provides those integrations and Spring Boot starters. Use the core SDK for a framework-neutral server or Spring AI when your application already runs on Spring.

Version and dependency setup

On the research date (2026-09-29), v2.0.1 was the current stable selector. The changelog dates 2.0.1 to 2026-08-19, calls 2.0.x active development, and lists 1.1.x and 0.18.x as security-patches-only lines. The 2.x line tracks the 2025-11-25 MCP specification according to the project roadmap. Treat those as time-sensitive project statements and recheck them before release.

<dependency>
  <groupId>io.modelcontextprotocol.sdk</groupId>
  <artifactId>mcp</artifactId>
  <version>2.0.1</version>
</dependency>

Prefer the matching SDK BOM and JSON module documented for your chosen release. The convenience artifact uses Jackson 3; the project also documents pluggable Jackson 2 and Jackson 3 modules. A 2.0 upgrade is a major-version migration: use the repository’s v2 migration guide rather than copying 1.x code.

Build a minimal Java server

The following follows the structure used by the official server guide: create a transport, declare server information and capabilities, register a tool specification, then build the server. Names can change between SDK releases, so copy the exact imports and builder signatures from the versioned guide linked above.

package example;

import io.modelcontextprotocol.server.McpServer;
import io.modelcontextprotocol.server.McpSyncServer;
import io.modelcontextprotocol.server.transport.StdioServerTransportProvider;
import io.modelcontextprotocol.spec.McpSchema;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
import io.modelcontextprotocol.spec.McpSchema.TextContent;
import io.modelcontextprotocol.spec.McpSchema.Tool;
import io.modelcontextprotocol.server.tool.SyncToolSpecification;
import com.fasterxml.jackson.databind.ObjectMapper;

public final class Main {
  public static void main(String[] args) {
    var transport = new StdioServerTransportProvider(new ObjectMapper());
    var echoTool = new SyncToolSpecification(
      new Tool("echo", "Echo text", "{\\"type\\":\\"object\\",\\"properties\\":{\\"text\\":{\\"type\\":\\"string\\"}},\\"required\\":[\\"text\\"]}"),
      (exchange, request) -> {
        var text = String.valueOf(request.arguments().getOrDefault("text", ""));
        return new CallToolResult(java.util.List.of(new TextContent(text)), false);
      });
    McpSyncServer server = McpServer.sync(transport)
      .serverInfo("java-example", "1.0.0")
      .capabilities(McpSchema.ServerCapabilities.builder().tools(true).build())
      .tools(echoTool)
      .build();
    Runtime.getRuntime().addShutdownHook(new Thread(server::close));
  }
}

1. Pin one SDK version and import its matching packages.
2. Run the class as the command configured by your MCP client.
3. Send logs to stderr; any non-protocol stdout output can break STDIO framing.
4. Use the guide’s asynchronous builders when tool work is I/O-bound or long-running.

Configure capabilities deliberately

The server capability builder can enable resources (including subscription and list-change flags), tools, prompts, completions and logging. Advertise only what you implement. Clients may hide features that were not negotiated, and advertising an unimplemented operation creates confusing failures.

var capabilities = McpSchema.ServerCapabilities.builder()
    .tools(true)
    .resources(true, true, true)
    .prompts(true)
    .completions(true)
    .logging()
    .build();

Expose resources, prompts and completions

Tools are only one part of an MCP server. Add URI-based resource handlers for documents or live data, resource templates when the URI contains variables, prompt handlers for reusable interactions, and completion handlers for arguments. Implement list-change and subscription notifications only when your backing store can produce correct change events. The official guide’s request and result types are the authority for exact handler signatures.

HTTP deployment checklist

• Select Streamable HTTP for a new remote deployment unless a client requires SSE.
• Terminate TLS at your application or a trusted reverse proxy.
• Authenticate before dispatching tool calls; the SDK exposes pluggable hooks, not a complete authorization policy.
• Set request and response size limits. v2.0.1 bounded STDIO and HTTP reads to a configurable maximum.
• Apply per-connection and per-tool timeouts, cancellation, concurrency limits and back-pressure.
• Keep secrets out of prompts, logs and resource payloads.
• Record request IDs, tool names, durations and failures without logging sensitive arguments.

Testing and reliability

Test initialization and capability negotiation, malformed arguments, unknown tools, cancellation, client disconnects, concurrent calls, oversized messages and downstream timeouts. Exercise both success and protocol error results. The project says it checks against the MCP conformance test suite; that is a project statement, not an independent test result.

Performance and cost

The SDK itself is a library, so hosting cost comes from your Java process, network and downstream services. Reuse clients and connection pools, avoid blocking calls on reactive threads, stream large resources where supported, and cap payload sizes. Measure tool latency at the handler boundary and separately measure model and downstream API time. A synchronous facade is convenient for blocking code; asynchronous APIs improve throughput when work is naturally concurrent.

Troubleshooting

Symptom	Likely cause	Fix
Client cannot initialize	Version or capability mismatch.	Pin matching client and server versions; inspect the initialize exchange and advertised capabilities.
STDIO server exits immediately	Main process ended or an exception was written without a visible log.	Keep the server handle alive, add a shutdown hook, and log diagnostics to stderr.
JSON parse or framing errors	Human-readable output was written to stdout.	Reserve stdout for protocol bytes; redirect logging to stderr.
Tool arguments are empty or rejected	Input schema does not match handler assumptions.	Declare required properties and validate every argument before use.
HTTP requests hang	Missing timeout, blocked downstream call or proxy buffering.	Set connect/read/tool timeouts, inspect proxy settings and propagate cancellation.
Spring classes are missing	Using a Spring transport from the core SDK.	Use Spring AI 2.0+ WebFlux/WebMVC integration or stay with core transports.
Upgrade breaks compilation	2.x contains breaking changes.	Follow the official v2 migration guide and update imports and builders together.

Or skip the browser setup

If your MCP tool needs website images or PDFs, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP or PDF; it accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and each response reports the verdict in X-Page-Verdict and billing in X-Billed.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for full-page and element shots, device presets, dark mode, custom CSS and JavaScript, waits, blocking, headers, cookies, geolocation, resizing, caching, signed links, async webhooks, bulk capture and usage data. Its MCP server provides take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients. Plans include 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account and start with the 1,000 monthly shots.

FAQ

Is this an MCP server framework?

It is the official Java SDK library used inside your application. You still deploy and secure the resulting process or HTTP service.

Should a new service use SSE?

For new remote services, evaluate Streamable HTTP first. SSE remains in the core transport documentation, while the 2.x roadmap marks it deprecated.

Do I need Spring?

No. Core transports work without an external web framework. Choose Spring AI when you need its WebFlux or WebMVC integration.

Where do I find exact method signatures?

Use the server guide and source for the exact SDK version you pinned; builder and package names can change across major releases.