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

> Integrate Embabel with your MCP server seamlessly. Follow this guide to add dependencies, annotate your config, and define connection properties for automatic client registration. Get started today!

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

---

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

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

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

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

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

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

```

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

```json
{
  "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`](https://github.com/embabel/embabel-agent/blob/main/AgentMcpServerAutoConfiguration.java)** – Registers the `McpClient` bean and parses the `@McpServers` annotation to determine active profiles.
- **[`McpServerActuatorAutoConfiguration.java`](https://github.com/embabel/embabel-agent/blob/main/McpServerActuatorAutoConfiguration.java)** – Conditionally enables health monitoring when an MCP client exists in the Spring context.
- **[`McpServerHealthIndicator.java`](https://github.com/embabel/embabel-agent/blob/main/McpServerHealthIndicator.java)** – Implements the `HealthIndicator` interface to report MCP connection status through Spring Boot Actuator.
- **[`McpServers.java`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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.