MCP Server Kickstart is a minimal Java/MCP framework that lets you quickly expose tools as MCP endpoints over three transports: Streaming (default HTTP), SSE, and STDIO. You annotate your tool methods with @McpTool and their parameters with @McpParam; the server automatically handles JSON serialization, schema generation, and error handling. By default the server runs in Streaming mode, serving at http://localhost:8090/mcp, where each registered tool becomes an endpoint action you can call via MCP clients. You can also start the server in SSE mode (for clients like Codeium/KiloCode) or in STDIO mode (for Claude Desktop or Cline) using the respective command flags or startup parameters described in the README. The framework includes a built-in Jetty server for HTTP-based transports and offers a fluent builder API to configure server name, version, port, and the list of tool instances.

To use the server, create a tool class annotated with @McpTool for each operation you want to expose. Each parameter must be annotated with @McpParam and provided descriptions to aid automatic JSON schema generation. Start the server via the provided Java snippet, Gradle, or a runnable JAR, and then connect with a compatible MCP client over SSE/Streaming or STDIO depending on your chosen transport. The project also demonstrates common integration patterns for clients like IntelliJ, Codeium/KiloCode, Claude Desktop, and Docker-based deployments.

Prerequisites:

• Java Runtime / JDK 11+ installed
• Optional: Docker if you prefer containerized runs
• Optional: Gradle or Maven if you want to build from source

Install steps:

1. Clone the repository: git clone https://github.com/qaware/mcp-server-kickstart.git cd mcp-server-kickstart

2. Build the project (Gradle): ./gradlew build

   or if using Maven (if the project supports it):

   mvn -B -DskipTests package

3. Run locally (examples)

   • Via Java run (from built jar or runnable jar): java -jar build/libs/mcp-server-kickstart-all-<version>.jar
   • Via Gradle run (exposes default HelloWorldTools): ./gradlew run
   • Via Docker (recommended for containerized deployments): docker build -t mcp-server-kickstart . docker run -i --rm mcp-server-kickstart

4. Docker-specific notes:

   • STDIO transport is used by default in Docker examples. The container communicates over standard input/output.
   • To expose specific tools, pass the fully-qualified class names as arguments to the java -jar command or configure in your Docker CMD accordingly.

5. Example usage with a tool in code (as shown in the README):

   • Implement a tool class with methods annotated by @McpTool and parameters annotated by @McpParam, then register the tool with McpServer.create().start().

Prerequisites summary:

• JDK 11+ for building and running
• Docker if you want containerized execution
• Optional build tools (Gradle/Maven) if you prefer building from source

Tips and common issues:

• Transport behavior: Streaming is the default; use --sse for SSE mode and --stdio for STDIO mode when launching from a jar or via container arguments.
• Debug logs: The server logs registrations and requests. In STDIO mode, logs typically appear in the client’s log directory when spawned by a client.
• JSON schema: The framework auto-generates JSON schemas for primitive types, Strings, arrays, and common collections, reducing manual schema work.
• Integration: The README shows example configurations for Codeium/KiloCode, IntelliJ, Claude Desktop, and Docker; adapt the mcpServers entries to your environment and client expectations.
• Ports and URLs: Streaming defaults to http://localhost:8090/mcp; SSE uses /sse. When using STDIO, there is no HTTP URL, only STDIN/STDOUT communication.
• Tool discovery: Tools are registered and printed during startup for easier debugging and verification.
• Environment variables: You can pass SERVER_URL or other client-facing configs via env blocks in mcp config when using GUI clients or containerized deployments.