Embabel Agent MCP Server

Transform Java/Kotlin applications into Model Context Protocol (MCP) servers, exposing AI agents and goals as standardized MCP tools, resources, and prompts. Auto-configures Server-Sent Events (SSE) endpoints compatible with Claude Desktop and other MCP clients.

Package Information

• Group: com.embabel.agent
• Artifact: embabel-agent-mcpserver
• Version: 0.3.3
• Type: Maven (JAR)
• Language: Kotlin
• License: Apache-2.0

Quick Start

Installation

Maven:

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-mcpserver</artifactId>
    <version>0.3.3</version>
</dependency>

Gradle:

implementation("com.embabel.agent:embabel-agent-mcpserver:0.3.3")

Basic Configuration

Configure execution mode in application.properties:

# Synchronous mode (default)
spring.ai.mcp.server.type=SYNC

# Application name
spring.application.name=my-agent-api

For async mode:

spring.ai.mcp.server.type=ASYNC

Minimal Example

Export tools from Embabel objects:

import com.embabel.agent.mcpserver.McpToolExport
import com.embabel.agent.api.common.ToolObject

// Create tool object
val toolObject = ToolObject(
    objects = listOf(myToolInstance)
)

// Export to MCP
val export = McpToolExport.fromToolObject(toolObject)

Create a custom tool publisher:

import com.embabel.agent.mcpserver.McpExportToolCallbackPublisher
import org.springframework.ai.tool.ToolCallback
import org.springframework.stereotype.Service

@Service
class MyToolPublisher : McpExportToolCallbackPublisher {
    override val toolCallbacks: List<ToolCallback>
        get() = listOf(/* your tool callbacks */)

    override fun infoString(verbose: Boolean?, indent: Int): String {
        return "MyToolPublisher: ${toolCallbacks.size} tools"
    }
}

The server auto-discovers and registers publishers during initialization.

Core Capabilities

Tool Export

Export Embabel agents and goals as MCP tools with naming strategies and filtering. → Tool Export API | Tool Export Guide

Publishers

Create extensible tool, resource, and prompt publishers as Spring beans. → Publisher APIs | Publisher Guide

Server Strategies

Manage operations through unified interface supporting sync and async modes. → Server Strategy API | Mode Selection Guide

Configuration

Auto-configuration based on execution mode via Spring Boot. → Configuration API | Configuration Guide

Factories

Build resource and prompt specifications with convenient factory methods. → Factory APIs | Resource Guide

Tool Registry

Query and manage registered tools across execution modes. → Registry API

Domain Types

Core types for server info, execution modes, capabilities, and health status. → Domain Types API

Documentation Structure

Getting Started

• Installation & Setup - Complete setup walkthrough
• Execution Modes - Sync vs async modes
• Basic Configuration - Properties and options

Task-Oriented Guides

• Exporting Tools - Export from ToolObject and LlmReference
• Creating Publishers - Custom tool/resource/prompt publishers
• Resources and Prompts - Working with resources and prompts
• Dynamic Tool Management - Runtime tool operations
• Integration Patterns - Complete application examples

API Reference

• Tool Export - McpToolExport interface and factory methods
• Publishers - Tool, resource, and prompt publisher interfaces
• Server Strategy - McpServerStrategy and implementations
• Server Configuration - Configuration classes and conditions
• Factories - Resource and prompt factories
• Tool Registry - ToolRegistry interface and implementations
• Domain Types - Core domain models
• Extensions - Utility extension functions

Advanced Topics

• Architecture - Layered architecture and design patterns
• Embabel Integration - Framework integration details
• Performance - Optimization and considerations
• Error Handling - Error strategies and graceful degradation
• Custom Implementations - Extending base classes

Common Imports

Essential imports for typical usage:

// Tool export
import com.embabel.agent.mcpserver.McpToolExport
import com.embabel.agent.mcpserver.McpExportToolCallbackPublisher

// Publishers (choose based on mode)
import com.embabel.agent.mcpserver.sync.McpResourcePublisher
import com.embabel.agent.mcpserver.sync.McpPromptPublisher
import com.embabel.agent.mcpserver.async.McpAsyncResourcePublisher
import com.embabel.agent.mcpserver.async.McpAsyncPromptPublisher

// Factories (choose based on mode)
import com.embabel.agent.mcpserver.sync.SyncResourceSpecificationFactory
import com.embabel.agent.mcpserver.sync.McpPromptFactory
import com.embabel.agent.mcpserver.async.McpAsyncPromptFactory

// Server management
import com.embabel.agent.mcpserver.McpServerStrategy
import com.embabel.agent.mcpserver.ToolRegistry

// Domain types
import com.embabel.agent.mcpserver.domain.McpExecutionMode
import com.embabel.agent.mcpserver.domain.ServerInfo

// Spring AI
import org.springframework.ai.tool.ToolCallback

// Embabel types
import com.embabel.agent.api.common.ToolObject
import com.embabel.agent.api.common.LlmReference

// MCP protocol
import io.modelcontextprotocol.server.McpServerFeatures
import io.modelcontextprotocol.spec.McpSchema

See Complete Import Reference for all available imports organized by use case.

Configuration Properties

Integration with Embabel Agent Framework

This library seamlessly integrates with Embabel Agent Framework to automatically expose:

• Agent Goals → MCP tools (via built-in publishers)
• Starting Input Types → MCP prompts (via built-in publishers)
• Agent Resources → MCP resources (via custom publishers)

No manual configuration needed - agents are auto-discovered and exported on initialization.

→ Embabel Integration Details

Key Features

• Automatic Discovery: Spring component scanning finds and registers publishers
• Mode Flexibility: Switch between sync/async with single property
• Type Safety: Strong typing throughout API with Kotlin support
• Reactive: Mono-based operations for consistent reactive programming
• Extensible: Publisher pattern enables custom tools/resources/prompts
• MCP Compliant: Full Model Context Protocol support

Need Help?

• Getting Started: See Installation & Setup Guide
• Common Tasks: Browse Task-Oriented Guides
• API Details: Check API Reference
• Advanced Topics: Explore Advanced Documentation
• Examples: Review Integration Patterns