How to Use Embabel as an MCP Server: Complete Configuration Guide

To use Embabel as an MCP server, add the embabel-agent-mcpserver-autoconfigure dependency, annotate agent methods with @Export(remote = true), and set spring.ai.mcp.server.enabled=true to expose your agents as Model Context Protocol tools to external clients.

Embabel is an open-source agent framework that natively supports the Model Context Protocol (MCP), allowing external tools like Claude Desktop or VS Code extensions to discover and invoke your agents as standardized remote tools. This guide explains how to configure the embabel/embabel-agent repository to run as an MCP server, covering auto-configuration, security, and tool exposure.

Core Architecture and Auto-Configuration

Embabel's MCP integration is built on Spring Boot auto-configuration classes that automatically register server beans when the required dependencies are present on the classpath.

AgentMcpServerAutoConfiguration

The AgentMcpServerAutoConfiguration class is the primary entry point for MCP server functionality. Located at embabel-agent-autoconfigure/embabel-agent-mcpserver-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/mcpserver/AgentMcpServerAutoConfiguration.java, this configuration scans the com.embabel.agent.mcpserver package and registers either synchronous or asynchronous server beans depending on your spring.ai.mcp.server.type property setting.

AgentMcpServerSecurityAutoConfiguration

For production deployments, the AgentMcpServerSecurityAutoConfiguration class (found in embabel-agent-autoconfigure/embabel-agent-mcpserver-security-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/mcpserver/security/AgentMcpServerSecurityAutoConfiguration.java) automatically secures MCP endpoints. When the security starter is on the classpath, this configuration adds JWT-based Spring Security filters to all MCP routes (/sse/**, /mcp/**, /message/**), protecting your agents from unauthorized access.

McpServerHealthIndicator

Monitoring is provided by McpServerHealthIndicator, located in embabel-agent-autoconfigure/embabel-agent-mcpserver-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/mcpserver/McpServerHealthIndicator.java. This component registers a Spring Boot Actuator HealthIndicator that reports the server's initialization state—UP, DOWN, or initializing—allowing you to verify when the MCP server is ready for client connections.

McpToolFactory and Client Integration

The McpToolFactory bridges external MCP clients to Embabel's internal tool system. As documented in embabel-agent-docs/src/main/asciidoc/reference/tools/page.adoc, this factory converts McpSyncClient and McpAsyncClient instances into Embabel Tool objects, supporting filtering, grouping, and wrapping in UnfoldingTool facades. This enables your agents to consume external MCP servers while maintaining Embabel's tool abstraction.

Step-by-Step: Exposing Agents as MCP Tools

Follow these steps to expose your Embabel agents as MCP-compatible tools.

Add the MCP Server Dependency

Include the MCP server auto-configuration module in your pom.xml:

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

For secure deployments, also add the security starter:

<dependency>
    <groupId>com.embabel</groupId>
    <artifactId>embabel-agent-mcpserver-security-autoconfigure</artifactId>
    <version>1.0.0</version>
</dependency>

Configure Server Properties

Create or update src/main/resources/application.yml to enable the server and set the execution mode:

spring:
  ai:
    mcp:
      server:
        enabled: true
        type: SYNC  # or ASYNC for SSE-based streaming

The spring.ai.mcp.server.type property controls whether the server runs in synchronous HTTP-style mode or asynchronous Server-Sent Events (SSE) mode, as detailed in the MCP Integration documentation at embabel-agent-docs/src/main/asciidoc/reference/integrations/page.adoc.

Annotate Agent Methods

Any method you want to expose as an MCP tool must be annotated with @Export(remote = true) within a class annotated with @AchievesGoal:

package com.example.agent;

import com.embabel.agent.annotation.AchievesGoal;
import com.embabel.agent.annotation.Export;

@AchievesGoal
public class WeatherAgent {

    @Export(remote = true)
    public String getForecast(String city) {
        return "Sunny and 75 degrees in " + city;
    }
}

When the application starts, AgentMcpServerAutoConfiguration automatically detects these annotations and registers the methods as MCP tools, making them discoverable by clients at the /sse or /mcp endpoints.

Execution Modes and Security

Embabel supports both synchronous and asynchronous execution models, with optional JWT-based security.

Synchronous vs. Asynchronous Mode

Set spring.ai.mcp.server.type=SYNC for traditional request-response HTTP endpoints, or ASYNC for SSE-based streaming connections. The SYNC mode is ideal for simple tool invocations, while ASYNC supports long-running agent conversations and real-time updates.

Enabling JWT Security

When the security auto-configuration is present, configure JWT in your application.yml:

spring:
  ai:
    mcp:
      security:
        jwt:
          secret: ${MCP_JWT_SECRET}

The AgentMcpServerSecurityAutoConfiguration automatically applies a JWT validation filter to all MCP endpoints, requiring clients to present valid tokens in the Authorization header.

Summary

• AgentMcpServerAutoConfiguration registers the MCP server beans and scans for @Export(remote = true) annotations in embabel-agent-mcpserver-autoconfigure.
• AgentMcpServerSecurityAutoConfiguration provides JWT-based security when the security starter is included.
• McpServerHealthIndicator exposes server health status via Spring Boot Actuator.
• Configuration requires setting spring.ai.mcp.server.enabled=true and choosing SYNC or ASYNC execution mode.
• Tool exposure is achieved by annotating agent methods with @Export(remote = true) within @AchievesGoal classes.

Frequently Asked Questions

What is the Model Context Protocol (MCP) in Embabel?

The Model Context Protocol is an open standard that allows AI systems to expose tools and context to external clients in a uniform way. In Embabel, implementing MCP means your agents can be discovered and invoked by any MCP-compatible client (such as Claude Desktop or IDE extensions) as remote tools, using the auto-configuration provided by AgentMcpServerAutoConfiguration.

How do I secure my Embabel MCP server?

Add the embabel-agent-mcpserver-security-autoconfigure dependency to your classpath. This enables AgentMcpServerSecurityAutoConfiguration, which automatically configures Spring Security to validate JWT tokens on all MCP endpoints. Set your secret via the spring.ai.mcp.security.jwt.secret property.

Can I consume external MCP servers within Embabel?

Yes. Embabel's McpToolFactory (documented in embabel-agent-docs/src/main/asciidoc/reference/tools/page.adoc) bridges external McpSyncClient or McpAsyncClient instances to Embabel's internal Tool abstraction. This allows your agents to invoke tools from external MCP servers while using Embabel's standard tool invocation patterns.

How do I monitor the health of the MCP server?

The McpServerHealthIndicator class automatically registers with Spring Boot Actuator. Check the /actuator/health endpoint to see the MCP server status. The indicator reports whether the server is UP and ready to accept connections, or still initializing, based on the server's internal state managed by AgentMcpServerAutoConfiguration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}