CtrlK
CommunityDocumentationLog inGet started
Tessl Logo

tessl/maven-com-embabel-agent--embabel-agent-mcpserver

Discover and Export available Agent(s) as MCP Servers

Overview
Eval results
Files

getting-started.mddocs/guides/

Getting Started with Embabel Agent MCP Server

Complete walkthrough for setting up and using embabel-agent-mcpserver in your project.

Prerequisites

  • Java 17 or higher
  • Spring Boot application
  • Maven or Gradle build system
  • Basic knowledge of Kotlin (examples in Kotlin)

Step 1: Add Dependency

Maven

Add to your pom.xml:

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

Gradle

Add to your build.gradle.kts:

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

Step 2: Configure Execution Mode

Create or update application.properties:

# Choose execution mode (SYNC is default)
spring.ai.mcp.server.type=SYNC

# Set application name (optional)
spring.application.name=my-agent-api

Modes:

  • SYNC: Synchronous operations (blocking, simpler)
  • ASYNC: Asynchronous operations (non-blocking, scalable)

See Execution Modes Guide for detailed comparison.

Step 3: Create a Tool Publisher

Tool publishers expose functionality as MCP tools. Create a Spring service:

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

@Service
class HelloWorldPublisher : McpExportToolCallbackPublisher {

    override val toolCallbacks: List<ToolCallback>
        get() = listOf(createHelloTool())

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

    private fun createHelloTool(): ToolCallback {
        // Implementation depends on your tool framework
        // See Tool Export Guide for details
        TODO("Create your ToolCallback implementation")
    }
}

Step 4: Run Your Application

Start your Spring Boot application:

./mvnw spring-boot:run

Or with Gradle:

./gradlew bootRun

The MCP server automatically:

  1. Detects execution mode from configuration
  2. Discovers all publisher beans
  3. Registers tools, resources, and prompts
  4. Exposes SSE endpoints for MCP clients

Step 5: Verify Server Operation

Check server initialization in logs:

[main] INFO  - Embabel Agent MCP SYNC Server
[main] INFO  - Version: 0.3.3
[main] INFO  - Registered tools: helloBanner, ...

The helloBanner tool is automatically available and displays server information.

Next Steps

Export Existing Tools

If you have Embabel ToolObject instances:

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

@Service
class MyToolsPublisher : McpExportToolCallbackPublisher {
    override val toolCallbacks: List<ToolCallback>
        get() {
            val toolObject = ToolObject(
                objects = listOf(myTool1, myTool2),
                namingStrategy = { "myapp_$it" }
            )
            return McpToolExport.fromToolObject(toolObject).toolCallbacks
        }

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

See Exporting Tools Guide for detailed examples.

Add Resources

Expose static or dynamic resources:

import com.embabel.agent.mcpserver.sync.McpResourcePublisher
import com.embabel.agent.mcpserver.sync.SyncResourceSpecificationFactory
import io.modelcontextprotocol.server.McpServerFeatures
import org.springframework.stereotype.Service

@Service
class DocsPublisher : McpResourcePublisher {
    override fun resources(): List<McpServerFeatures.SyncResourceSpecification> {
        return listOf(
            SyncResourceSpecificationFactory.staticSyncResourceSpecification(
                uri = "app://docs/readme",
                name = "README",
                description = "Application documentation",
                content = "# My Application\n\nWelcome!",
                mimeType = "text/markdown"
            )
        )
    }

    override fun infoString(verbose: Boolean?, indent: Int): String =
        "DocsPublisher: ${resources().size} resources"
}

See Resources and Prompts Guide for more examples.

Add Prompts

Create prompts for AI clients:

import com.embabel.agent.mcpserver.sync.McpPromptPublisher
import com.embabel.agent.mcpserver.sync.McpPromptFactory
import com.embabel.common.core.types.Named
import com.embabel.common.core.types.Described
import io.modelcontextprotocol.server.McpServerFeatures
import org.springframework.stereotype.Service

@Service
class TaskPromptsPublisher : McpPromptPublisher {

    private val factory = McpPromptFactory()

    override fun prompts(): List<McpServerFeatures.SyncPromptSpecification> {
        val goal = object : Named, Described {
            override val name = "createTask"
            override val description = "Create a new task"
        }

        return listOf(
            factory.syncPromptSpecificationForType(
                goal = goal,
                inputType = TaskInput::class.java
            )
        )
    }

    override fun infoString(verbose: Boolean?, indent: Int): String =
        "TaskPromptsPublisher: ${prompts().size} prompts"
}

data class TaskInput(
    val title: String,
    val description: String,
    val priority: Int
)

See Resources and Prompts Guide for prompt creation details.

Common Patterns

Multiple Publishers

Create separate publishers for different concerns:

@Service
class ApiToolsPublisher : McpExportToolCallbackPublisher { /* API tools */ }

@Service
class UtilityToolsPublisher : McpExportToolCallbackPublisher { /* Utility tools */ }

@Service
class ResourcesPublisher : McpResourcePublisher { /* Resources */ }

@Service
class PromptsPublisher : McpPromptPublisher { /* Prompts */ }

All publishers are automatically discovered and registered.

Conditional Publishers

Activate publishers based on profiles or properties:

@Service
@Profile("development")
class DevToolsPublisher : McpExportToolCallbackPublisher {
    // Only active in development profile
}

@Service
@ConditionalOnProperty("features.experimental.enabled")
class ExperimentalPublisher : McpExportToolCallbackPublisher {
    // Only active when feature flag is enabled
}

Mode-Specific Publishers

Publishers for specific execution modes:

// Sync mode only (default)
@Service
@ConditionalOnProperty(
    value = ["spring.ai.mcp.server.type"],
    havingValue = "SYNC",
    matchIfMissing = true
)
class SyncPublisher : McpResourcePublisher { /* ... */ }

// Async mode only
@Service
@ConditionalOnProperty(
    value = ["spring.ai.mcp.server.type"],
    havingValue = "ASYNC"
)
class AsyncPublisher : McpAsyncResourcePublisher { /* ... */ }

Troubleshooting

No Tools Registered

Symptom: Server starts but no tools appear (except helloBanner)

Solutions:

  1. Ensure publishers are annotated with @Service or @Component
  2. Check that publishers are in component-scanned packages
  3. Verify toolCallbacks property returns non-empty list
  4. Check logs for registration errors

Wrong Execution Mode

Symptom: Publishers not activating or wrong publisher types

Solutions:

  1. Check spring.ai.mcp.server.type property value
  2. Use correct publisher interfaces:
    • Sync: McpResourcePublisher, McpPromptPublisher
    • Async: McpAsyncResourcePublisher, McpAsyncPromptPublisher
  3. Verify conditional annotations match configured mode

Tool Registration Fails

Symptom: Errors during tool registration

Solutions:

  1. Verify tool specifications are correctly formed
  2. Check for duplicate tool names
  3. Ensure naming strategies produce valid names
  4. Review error logs for specific failure reasons

Server Not Accessible

Symptom: MCP clients cannot connect

Solutions:

  1. Verify server is running (check logs)
  2. Check SSE endpoint configuration
  3. Ensure no firewall blocking connections
  4. Verify client configuration points to correct endpoint

Example Applications

See Integration Patterns Guide for complete working examples:

  • Simple tool exporter
  • Multi-publisher application
  • Dynamic tool management
  • Resource and prompt integration
  • Embabel framework integration

Related Guides

tessl i tessl/maven-com-embabel-agent--embabel-agent-mcpserver@0.3.1

docs

guides

configuration.md

creating-publishers.md

dynamic-management.md

execution-modes.md

exporting-tools.md

getting-started.md

integration-patterns.md

resources-and-prompts.md

index.md

tile.json