How to Configure Embabel for MCP Server Integration: A Complete Guide

Add the embabel-agent-mcpserver-autoconfigure dependency, annotate your configuration class with @McpServers, and define connection properties under the embabel.mcpservers.* namespace to enable automatic MCP client registration.

The embabel/embabel-agent repository provides a dedicated auto-configuration module that simplifies connecting Embabel-based agents to MCP (Model Context Protocol) servers. By leveraging Spring Boot's auto-configuration mechanism, you can activate MCP integration through annotations and externalized configuration without writing boilerplate connection code. This guide covers the essential steps to configure Embabel for MCP server integration using the actual source implementation.

Understanding Embabel's MCP Auto-Configuration Architecture

Embabel's MCP integration relies on three core auto-configuration classes that manage the client lifecycle. These components work together to instantiate the McpClient bean, activate server profiles, and expose health metrics through Spring Boot Actuator.

AgentMcpServerAutoConfiguration handles the primary bean registration. Located in embabel-agent-autoconfigure/embabel-agent-mcpserver-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/mcpserver/AgentMcpServerAutoConfiguration.java, this class scans for the @McpServers annotation and creates the McpClient instance based on active profiles.

McpServerActuatorAutoConfiguration provides observability support. Found in the same package as McpServerActuatorAutoConfiguration.java, this class conditionally registers the McpServerHealthIndicator when an MCP client bean is detected in the application context.

McpServerHealthIndicator exposes connection status via the Actuator endpoint. This implementation reports the initialization state (UP or DOWN) and connection details at /actuator/health under the mcpServer component key.

Step-by-Step Configuration Guide

Add the MCP Server Auto-Configuration Dependency

Include the embabel-agent-mcpserver-autoconfigure artifact in your build configuration to pull in the required client libraries and registration logic.

<dependency>
    <groupId>com.embabel</groupId>
    <artifactId>embabel-agent-mcpserver-autoconfigure</artifactId>
    <version>${embabel.version}</version>
</dependency>

This dependency triggers the auto-configuration classes when present on the classpath, eliminating the need for manual bean definition.

Activate MCP Profiles with the @McpServers Annotation

Create a configuration class and annotate it with @McpServers to declare which server profiles should be active. The annotation accepts an array of profile constants defined in com.embabel.agent.config.annotation.McpServers.

import com.embabel.agent.config.annotation.McpServers;
import org.springframework.context.annotation.Configuration;

@Configuration
@McpServers({McpServers.DOCKER_DESKTOP, McpServers.GITHUB})
public class EmbabelMcpConfig {
}

Valid profile constants include DOCKER_DESKTOP for local filesystem access via Docker Desktop and GITHUB for GitHub-specific MCP capabilities. You can also specify custom profile names as strings to match entries in your application.yml.

Configure Connection Properties in application.yml

Define server-specific connection parameters under the embabel.mcpservers.* namespace. Each profile can specify host, port, TLS settings, authentication credentials, and retry policies.

embabel:
  mcpservers:
    docker-desktop:
      enabled: true
    custom:
      enabled: true
      host: "mcp.mycompany.com"
      port: 443
      tls: true
      apiKey: "${MCP_API_KEY}"
      retry:
        maxAttempts: 3
        backoff: 2s

Use environment variables like ${MCP_API_KEY} for sensitive values to keep secrets out of version control. The properties map directly to the configuration objects instantiated by AgentMcpServerAutoConfiguration.

Inject and Use the McpClient Bean

Once configured, Spring Boot automatically injects a fully initialized McpClient bean into your components. Autowire this bean to send requests to the active MCP server.

import com.embabel.agent.mcp.McpClient;
import org.springframework.stereotype.Component;

@Component
public class SearchSkill {

    private final McpClient mcpClient;

    public SearchSkill(McpClient mcpClient) {
        this.mcpClient = mcpClient;
    }

    public String search(String query) {
        return mcpClient.ask("Search the web for: " + query);
    }
}

The client handles connection pooling, authentication, and protocol compliance based on the profile configuration provided in your YAML files.

Monitor Health with Spring Boot Actuator

Verify the integration status by querying the health endpoint. The McpServerHealthIndicator automatically registers when the MCP client is present, exposing connection details and initialization state.

curl -s http://localhost:8080/actuator/health | jq '.components.mcpServer'

A successful configuration returns a status of UP along with active profile details:

{
  "status": "UP",
  "details": {
    "profile": "CUSTOM",
    "host": "mcp.mycompany.com",
    "port": 443
  }
}

Core Configuration Classes Reference

The following source files implement the MCP integration in the embabel/embabel-agent repository:

• AgentMcpServerAutoConfiguration.java – Registers the McpClient bean and parses the @McpServers annotation to determine active profiles.
• McpServerActuatorAutoConfiguration.java – Conditionally enables health monitoring when an MCP client exists in the Spring context.
• McpServerHealthIndicator.java – Implements the HealthIndicator interface to report MCP connection status through Spring Boot Actuator.
• McpServers.java – The annotation interface located in embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/ that defines valid profile constants.
• README.md – Documentation for the auto-configuration module providing property references and quick-start examples.

Summary

• Add the embabel-agent-mcpserver-autoconfigure Maven dependency to enable auto-configuration support for MCP integration.
• Annotate a configuration class with @McpServers and specify profile constants like DOCKER_DESKTOP or custom identifiers to activate specific server configurations.
• Define connection parameters, authentication, and retry logic under the embabel.mcpservers.<profile> namespace in application.yml.
• Inject the auto-configured McpClient bean into your components to communicate with MCP servers without manual connection management.
• Monitor connection health via Spring Boot Actuator at /actuator/health, where McpServerHealthIndicator exposes real-time status and configuration details.

Frequently Asked Questions

What dependency is required to enable MCP server integration in Embabel?

You must add the embabel-agent-mcpserver-autoconfigure artifact to your project dependencies. This module contains AgentMcpServerAutoConfiguration and related classes that automatically configure the MCP client when present on the classpath.

How do I activate multiple MCP server profiles simultaneously?

Use the @McpServers annotation on a Spring @Configuration class and pass an array of profile identifiers. For example, @McpServers({McpServers.DOCKER_DESKTOP, McpServers.GITHUB}) activates both the Docker Desktop and GitHub profiles concurrently, creating separate configuration contexts for each.

Where are MCP server connection properties defined?

Connection properties reside in application.yml or application.properties under the embabel.mcpservers.* hierarchical namespace. Each profile has its own subsection where you specify host, port, tls, apiKey, and retry settings that map to the internal configuration objects processed by AgentMcpServerAutoConfiguration.

How can I monitor the health of the MCP connection?

The McpServerHealthIndicator automatically exposes MCP status through Spring Boot Actuator. Query the /actuator/health endpoint and inspect the mcpServer component in the JSON response to view the initialization state, active profile name, and connection endpoint details.

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