Quick Start

This guide gets you from zero to a running MCP server with jooby-mcp in a few steps.

1. Add the dependency

In your pom.xml:

<dependency>
    <groupId>io.github.kliushnichenko</groupId>
    <artifactId>jooby-mcp</artifactId>
    <version>${jooby.mcp.version}</version>
</dependency>

2. Add the annotation processor

Configure the Maven Compiler Plugin so the APT processor generates the MCP server class:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>io.github.kliushnichenko</groupId>
                <artifactId>jooby-mcp-apt</artifactId>
                <version>${jooby.mcp.version}</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

3. Configure the MCP server

In application.conf, define at least one MCP server. The key (e.g. default) must match what the annotation processor expects (see Customizing default server to change it).

Note: Since 1.4.0 the default transport is Streamable HTTP, not SSE. Set transport: "sse" explicitly if you need SSE.

SSE transport

mcp.default {
  name: "my-awesome-mcp-server"     # Required
  version: "0.1.0"                  # Required
  transport: "sse"                  # Optional (default: streamable-http)
  sseEndpoint: "/mcp/sse"           # Optional (default: /mcp/sse)
  messageEndpoint: "/mcp/message"   # Optional (default: /mcp/message)
}

Streamable HTTP transport (default)

mcp.default {
  name: "my-awesome-mcp-server"
  version: "0.1.0"
  transport: "streamable-http"
  mcpEndpoint: "/mcp/streamable"    # Optional (default: /mcp)
  disallowDelete: true              # Optional (default: false)
  keepAliveInterval: 45             # Optional, in seconds
  instructions: "..."               # Optional: server instructions for clients
}

Stateless Streamable HTTP

mcp.default {
  name: "my-awesome-mcp-server"
  version: "0.1.0"
  transport: "stateless-streamable-http"
  mcpEndpoint: "/mcp/stateless-streamable"   # Optional (default: /mcp)
}

• keepAliveInterval — Sends periodic keep-alive messages when set to a positive number (seconds). Off by default.
• instructions — Shown to clients during initialization. Use it to describe how to use the server.

4. Implement tools, prompts, or resources

Add one or more classes with @Tool, @Prompt, or @Resource (and related) annotations. See Tools, Prompts, and Resources for examples, or browse the example project.

5. Register the MCP module

After building, the processor generates a DefaultMcpServer class (or a custom name if configured). Install the module in your Jooby app:

{
    install(new JacksonModule());              // Required for JSON-RPC
    install(AvajeInjectModule.of());           // Or your preferred DI module
    install(new McpModule(new DefaultMcpServer()));
}

Your MCP server is now available at the configured endpoint. Next, define Tools, Prompts, or Resources.