Build an MCP Server in Java: Tools, Transport, and Verification

An MCP server in Java is a small process that exposes tools an AI assistant can call, handles requests over a transport, and returns structured results. It follows the same Model Context Protocol (MCP) spec used by other language implementations, so it connects to any MCP-compatible client. Tools like fenbs let your team record the design decisions behind each tool, so the next engineer starts from agreed rules rather than guessing at intent.

Java is a practical choice when your existing stack runs on the JVM, when you need static typing for tool schemas, or when your organization requires it. The MCP concepts are the same as in any other language: define tools, handle requests, return typed results. The Java-specific work is choosing the SDK, wiring a transport, and managing JSON serialization.

What an MCP server does

An MCP server advertises a list of tools. Each tool has a name, a description the AI reads to decide whether to use it, and an input schema. When a client calls a tool, the server runs the handler and returns a result. The server never decides which tool to call — that is the AI client's job. The server only needs to accept valid calls and return useful answers. The MCP spec defines the wire format and session lifecycle in detail.

Set up the Java project

The official MCP Java SDK provides the server runtime, request routing, and transport adapters. Add it from Maven Central as a Maven or Gradle dependency. The SDK uses Java records and other features introduced in recent versions, so check the repository for the minimum JDK required. A standard single-module project with a main class that creates and starts the server is enough to begin.

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

Define a tool

A tool definition tells the client what the tool does and what parameters it accepts. Supply a name, a description, and an input schema object. The handler receives the parsed arguments and returns a result. Write descriptions carefully: the AI reads them verbatim to decide whether to call the tool, so an imprecise description leads to misuse. Keep each tool focused on one operation.

server.addTool(
  Tool.builder()
    .name("get_project_status")
    .description("Returns the current status of a named project.")
    .inputSchema(schema)
    .handler(args -> getStatus(args.getString("name")))
    .build()
);

Group related tools under a shared prefix so a client can understand the server's scope at a glance. A server that exposes ten tools about a single database is easier to reason about than one that mixes concerns. Decide the full tool surface before writing handlers, and record which tools may mutate state and which are read-only.

Choose a transport

MCP supports two transports: stdio for local clients, and an HTTP-based server-sent events (SSE) transport for remote access. Stdio is simpler to set up and test. The client process spawns the server and communicates over standard input and output with no network configuration needed. If the server needs to serve multiple clients or run on a shared host, use the SSE transport behind HTTPS.

Start with stdio unless you have a specific need for remote access. Stdio servers are harder to misconfigure locally and can be moved to an SSE deployment later. Document the transport choice as a decision, including the reason, so teammates know what changing it would require.

Verify each tool before connecting an AI client

Use the MCP Inspector to test tools directly before adding a full AI client. The Inspector is a lightweight CLI that connects to any MCP server, lists its tools, and lets you send test calls with chosen arguments. Check that each tool returns the correct shape, handles invalid inputs with an error rather than a crash, and that the server exits cleanly when the transport closes.

• Call each tool with valid input and confirm the result matches the documented schema.
• Send a tool call with a missing required parameter and confirm the server returns an error.
• Call a tool name that does not exist and confirm the server responds with a protocol-level error.
• Close the Inspector and confirm the server process exits without hanging threads.
• Check that handler logs include enough detail to diagnose a failed call in production.

Capture decisions before the server reaches a team

A server that grows without recorded decisions becomes difficult to extend safely. Which tools may mutate data? What should happen when a downstream service is unavailable? What input validation goes beyond the schema? These are design choices that the next maintainer needs. fenbs keeps Decisions and rules alongside tasks, so every connected assistant reads them at the start of a session before touching the server.

How to record Java MCP server decisions with fenbs

Connect fenbs to your development assistant and add decisions from the first day the server is shared. A short note per decision costs little and prevents repeated questions.

1. Create a free account and start a project for the MCP server. Write a one-sentence goal and the context a new engineer needs to get started.
2. Add the first Decisions and rules: which tools are read-only, how errors are handled, and why you chose the transport you did. Name the person who made each call.
3. Create a task for each tool you plan to build. Put the tool's description text in the note so it can be reviewed alongside the code.
4. Connect your AI coding assistant via Integrations. It reads the current rules and open tasks at the start of each session.
5. Before ending a session, ask the assistant to save progress on the tasks it touched and flag any open questions for the next person.