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

> Learn how to use Embabel as an MCP server with this complete guide. Configure dependencies, annotate methods, and enable server settings to expose agents as tools.

- Repository: [Embabel/embabel-agent](https://github.com/embabel/embabel-agent)
- Tags: how-to-guide
- Published: 2026-08-08

---

**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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/pom.xml):

```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:

```xml
<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`](https://github.com/embabel/embabel-agent/blob/main/src/main/resources/application.yml) to enable the server and set the execution mode:

```yaml
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`:

```java
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`](https://github.com/embabel/embabel-agent/blob/main/application.yml):

```yaml
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`.