Index of every page on this site: llms.txt
All skills
github avatar

/java-mcp-server-generator

@f10fdb8 official
by githubgithub/awesome-copilot41k stars
5,399
Run it yourself

Use this skill when the user wants to create a Model Context Protocol (MCP) server in Java or in a Spring Boot app. Also use it when the user wants AI agents, such as GitHub Copilot or Claude, to use Java code, an API, or a database. Use it even if the user does not say "MCP". The skill makes a Maven or Gradle project with the MCP Java SDK 2.x, tools, JUnit tests, and client configuration. Do not use it for Quarkus/Quarkiverse MCP servers (use the `quarkus-mcp-server-sse` instruction), for an MCP client or for a server in another language.

Use this Skill: https://skilld.dev/gh/github/awesome-copilot/java-mcp-server-generator

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈143 tokens for metadata: the name and description. ≈3.2k when used: this file. ≈1.9k more on demand in 2 files.

Description uses 7.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈573 characters, or 7.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Java MCP Server Generator

Create a Model Context Protocol (MCP) server in Java with the official MCP Java SDK 2.x. SDK 2.0.x supports the MCP specification revision 2025-11-25 and the earlier revisions. SDK 3.x will add the revision 2026-07-28.

Workflow

Copy this checklist and track your progress:

  • Step 1: Create the project.
  • Step 2: Write the server.
  • Step 3: Write the tests.
  • Step 4: Build until the tests pass.
  • Step 5: Configure the client.

Step 1: Create the project

Use Maven by default. If the project uses Gradle or the user asks for Gradle, read references/gradle.md. Use it for Step 1, Step 4, and Step 5.

Make this layout:

project-name/
├── pom.xml
└── src/
    ├── main/java/com/example/McpServerApp.java
    └── test/java/com/example/McpServerAppTest.java

Write pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>mcp-server-demo</artifactId>
  <version>0.1.0</version>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.modelcontextprotocol.sdk</groupId>
        <artifactId>mcp-bom</artifactId>
        <version>2.0.1</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <dependency>
        <groupId>org.junit</groupId>
        <artifactId>junit-bom</artifactId>
        <version>6.1.3</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
    <dependency>
      <groupId>io.modelcontextprotocol.sdk</groupId>
      <artifactId>mcp</artifactId>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-simple</artifactId>
      <version>2.0.17</version>
      <scope>runtime</scope>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>3.6.2</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals>
              <goal>shade</goal>
            </goals>
            <configuration>
              <createDependencyReducedPom>false</createDependencyReducedPom>
              <transformers>
                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                  <mainClass>com.example.McpServerApp</mainClass>
                </transformer>
              </transformers>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>
  • The mcp artifact contains mcp-core and the Jackson 3 JSON mapper mcp-json-jackson3.
  • slf4j-simple writes the SDK logs to stderr.
  • The shade plugin makes one executable JAR with all dependencies.

Step 2: Write the server

Start from this template:

package com.example;

import java.util.List;
import java.util.Map;

import io.modelcontextprotocol.json.McpJsonDefaults;
import io.modelcontextprotocol.server.McpServer;
import io.modelcontextprotocol.server.McpServerFeatures.SyncToolSpecification;
import io.modelcontextprotocol.server.transport.StdioServerTransportProvider;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
import io.modelcontextprotocol.spec.McpSchema.Tool;

public final class McpServerApp {

    static SyncToolSpecification divideTool() {
        Tool tool = Tool.builder("divide", Map.of(
                        "type", "object",
                        "properties", Map.of(
                                "a", Map.of("type", "number", "description", "Dividend"),
                                "b", Map.of("type", "number", "description", "Divisor")),
                        "required", List.of("a", "b")))
                .description("Divide a by b.")
                .build();

        return SyncToolSpecification.builder()
                .tool(tool)
                .callHandler((exchange, request) -> {
                    double a = ((Number) request.arguments().get("a")).doubleValue();
                    double b = ((Number) request.arguments().get("b")).doubleValue();
                    if (b == 0) {
                        return CallToolResult.builder().addTextContent("b must not be zero.").isError(true).build();
                    }
                    return CallToolResult.builder().addTextContent(String.valueOf(a / b)).build();
                })
                .build();
    }

    public static void main(String[] args) {
        McpServer.sync(new StdioServerTransportProvider(McpJsonDefaults.getMapper()))
                .serverInfo("demo", "0.1.0")
                .capabilities(ServerCapabilities.builder().tools(false).build())
                .tools(divideTool())
                .build();
    }
}

Then change the template to match the request of the user:

  1. Replace divideTool() with the tools that the user asks for. Make one method for each tool.
  2. Give each tool a JSON Schema inputSchema and a description. The description tells the model when to use the tool.
  3. When the client must get machine-readable data, add .outputSchema(Map) to the tool. Return the data with CallToolResult.builder().structuredContent(map). Also add the same data as text content for older clients.
  4. Mark a read-only tool with .annotations(ToolAnnotations.builder().readOnlyHint(true).build()). Use destructiveHint(true) for a destructive tool.
  5. Add resources, resource templates, and prompts only when the user asks for them. Also enable them in ServerCapabilities.

Use stdio by default. Read references/streamable-http.md only when the user asks for a remote server, an HTTP server, or Spring Boot.

Step 3: Write the tests

The test starts the server as a subprocess and connects to it with the SDK client. Write a test for each tool and for each error result:

package com.example;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.nio.file.Path;
import java.util.Map;

import org.junit.jupiter.api.AfterAll;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;

import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.json.McpJsonDefaults;
import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
import io.modelcontextprotocol.spec.McpSchema.TextContent;

class McpServerAppTest {

    private static McpSyncClient client;

    @BeforeAll
    static void startServer() {
        String java = Path.of(System.getProperty("java.home"), "bin", "java").toString();
        ServerParameters server = ServerParameters.builder(java)
                .args("-cp", System.getProperty("java.class.path"), McpServerApp.class.getName())
                .build();
        client = McpClient.sync(new StdioClientTransport(server, McpJsonDefaults.getMapper())).build();
        client.initialize();
    }

    @AfterAll
    static void stopServer() {
        client.close();
    }

    @Test
    void divide() {
        CallToolResult result = client.callTool(
                CallToolRequest.builder("divide").arguments(Map.of("a", 6, "b", 3)).build());
        assertEquals("2.0", ((TextContent) result.content().get(0)).text());
    }

    @Test
    void divideByZero() {
        CallToolResult result = client.callTool(
                CallToolRequest.builder("divide").arguments(Map.of("a", 1, "b", 0)).build());
        assertTrue(result.isError());
        assertTrue(((TextContent) result.content().get(0)).text().contains("must not be zero"));
    }
}
  • The test uses the java command of the JDK that runs Maven. Do not use the java command from PATH.
  • The test uses the real stdio transport and the real JSON-RPC messages.

Step 4: Build until the tests pass

  1. Run mvn verify. This command compiles the code, runs the tests, and makes target/mcp-server-demo-0.1.0.jar.
  2. If a test fails, read the error. Fix the server or the test.
  3. Run mvn verify again.
  4. Continue only when the build is successful.

Step 5: Configure the client

For VS Code, write .vscode/mcp.json:

{
  "servers": {
    "demo": {
      "type": "stdio",
      "command": "java",
      "args": ["-jar", "/absolute/path/to/project/target/mcp-server-demo-0.1.0.jar"]
    }
  }
}

For Claude Desktop, put the same command and args in claude_desktop_config.json, below the mcpServers key.

For an HTTP server, use the client configuration in references/streamable-http.md.

Tell the user these facts:

  • java -jar target/mcp-server-demo-0.1.0.jar starts the stdio server. The server waits for a host on stdin. The SDK logs go to stderr.
  • To test the server manually, start the MCP Inspector with the same command. The Inspector uses Node.js.

Gotchas

SDK 2.x changed many patterns of SDK 0.x and 1.x. Do not copy examples from earlier versions. Read the migration guide for the full list.

  • Use the builders that take the required fields first: Tool.builder(name, inputSchema), Resource.builder(uri, name), Prompt.builder(name), TextContent.builder(text), and ReadResourceResult.builder(contents). The builders without arguments are deprecated.
  • A required field must not be null. A null value causes an IllegalArgumentException.
  • Tool names must have 1 to 128 characters: letters, digits, _, -, and .. The server builder rejects an incorrect name with an IllegalArgumentException. addTool() at runtime does not check the name.
  • inputSchema and outputSchema are Map<String, Object> values. The JsonSchema record is deprecated.
  • The server checks each schema against JSON Schema 2020-12 when you call build() or addTool(). An incorrect schema causes an IllegalArgumentException.
  • The SDK validates the tool arguments against inputSchema. It also validates structuredContent against outputSchema. If the validation fails, the client gets a tool result with isError set to true. Thus, the handler gets only valid arguments.
  • If a tool has an outputSchema, return structuredContent in each successful result. Without it, the SDK returns a tool result with isError set to true.
  • Return CallToolResult with isError(true) for an error that the model must read.
  • Do not throw an exception or an McpError for a tool failure. The client gets a JSON-RPC error, not a tool result. Many hosts do not show this error to the model.
  • In a stdio server, stdout is the protocol channel. Do not call System.out.println().
  • Log with SLF4J to stderr. The default console appender of Logback writes to stdout. If you use Logback, set its target to System.err.
  • The Spring transports moved to Spring AI 2.0 and later (group org.springframework.ai). Do not use the io.modelcontextprotocol.sdk:mcp-spring-* artifacts.
  • Do not use the deprecated SSE transports. Use Streamable HTTP for a remote server.
  • The revision 2026-07-28 deprecates these features (SEP-2577). Do not add them to a new server:
    • Sampling (exchange.createMessage()): Call the LLM provider API directly.
    • Protocol logging (exchange.loggingNotification()): Use SLF4J.
    • Roots (exchange.listRoots()): Get paths from tool arguments, resource URIs, or the server configuration.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning28d5 checks · Risk SAFE
  • Gen Agent Trust Hub28d

    This skill provides templates and instructions for generating Model Context Protocol (MCP) servers in Java using Maven or Gradle. It follows standard software development practices, uses official SDK libraries, and includes security-focused guidance for implementing HTTP transports with Host and Origin validation to prevent DNS rebinding attacks.

  • Socket28d

    No alerts

  • Snyk28d

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at f10fdb8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month
Other metadata
compatibility
JDK 17 or later, Maven 3.9 or later or Gradle 9 or later, and network access to download dependencies. The MCP Inspector also uses Node.js.
  • MCP
  • java
  • model-context-protocol
  • sdk
  • maven
  • gradle
  • reactive
  • spring-boot

README badge

README badge for github/awesome-copilot/java-mcp-server-generator

Generates a complete Model Context Protocol server project in Java using the official MCP Java SDK with Maven or Gradle build configuration. Includes templates for tool, resource, and prompt handlers with reactive streams support via Project Reactor.

Generated from the current SKILL.md.

Does this skill support both Maven and Gradle?
Yes. The skill provides complete templates for both Maven (pom.xml) and Gradle (build.gradle.kts) project setups.
What Java version is required?
Java 17 or later. Both the Maven and Gradle templates target Java 17 as the minimum version.
Does this use the official MCP Java SDK?
Yes. The skill generates projects using the official Model Context Protocol Java SDK (io.modelcontextprotocol.sdk:mcp).
Can I use Spring Boot with this skill?
The skill mentions optional Spring Boot integration but does not provide Spring Boot-specific templates or configuration in the SKILL.md content shown.
What capabilities does the generated server support?
The generated server supports tools, resources, and prompts as core MCP capabilities, with handlers for each included in the templates.

Generated from the current SKILL.md. These answers refresh after source changes.