# How to Configure MCP Clients to Connect to External MCP Servers in Embabel

> Learn how to configure MCP clients to connect to external MCP servers in Embabel. Enable agents and define transport connections in application.yml for resilient MCP clients.

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

---

**Enable the `@EnableAgents` annotation on your Spring Boot application class and define transport connections in [`application.yml`](https://github.com/embabel/embabel-agent/blob/main/application.yml) under the `spring.ai.mcp.client` namespace to create resilient `McpSyncClient` or `McpAsyncClient` beans.**

Embabel Agent provides built-in support for the Model Context Protocol (MCP) through Spring-based auto-configuration. To configure MCP clients to connect to external MCP servers in Embabel, you activate the framework via annotations and provide transport-specific settings in your YAML configuration. The `QuiteMcpClientAutoConfiguration` class in the `embabel/embel-agent` repository manages the lifecycle of these clients, ensuring fault-tolerant initialization even when external servers are unreachable.

## Activating MCP Clients with @EnableAgents

The entry point for MCP functionality is the `@EnableAgents` annotation, located at [`embel-agent-autoconfigure/embel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/EnableAgents.java`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-autoconfigure/embel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/EnableAgents.java). This annotation scans the classpath and activates the Spring profiles required for MCP client auto-configuration.

Activate MCP support using the `mcpServers` attribute:

```java
import com.embabel.agent.config.annotation.EnableAgents;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@EnableAgents(
    loggingTheme = "starwars",
    mcpServers = {"docker", "github"}
)
public class MyAgentApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyAgentApplication.class, args);
    }
}

```

Note that while the `mcpServers` attribute is deprecated, it remains functional for activating the MCP client layer.

## Configuring Transport Connections

Once activated, configure connection details under the `spring.ai.mcp.client` property prefix. These properties populate `McpClientCommonProperties` and define client metadata, behavior, and transport-specific settings.

### Core Configuration Properties

- `spring.ai.mcp.client.enabled`: Boolean flag to enable the MCP client layer
- `spring.ai.mcp.client.type`: Choose `SYNC` for `McpSyncClient` or `ASYNC` for `McpAsyncClient`
- `spring.ai.mcp.client.name`: Logical identifier for the client (e.g., "embel")
- `spring.ai.mcp.client.version`: Client version string
- `spring.ai.mcp.client.request-timeout`: Connection timeout (e.g., `30s`)
- `spring.ai.mcp.client.initialized`: Whether to initialize immediately on startup (default: `true`)

### STDIO Transport for Docker-Based Servers

For command-line or Docker container MCP servers, use the STDIO transport. This configuration launches a Docker container running `socat` to bridge STDIO to a TCP endpoint:

```yaml
spring:
  ai:
    mcp:
      client:
        enabled: true
        name: embel
        version: 1.0.0
        request-timeout: 30s
        type: SYNC
        stdio:
          connections:
            docker-mcp:
              command: docker
              args:
                - run
                - -i
                - --rm
                - alpine/socat
                - STDIO
                - TCP:host.docker.internal:8811

```

### HTTP SSE Transport for REST Endpoints

For HTTP-based MCP servers, configure the HTTP transport section with optional headers for authentication:

```yaml
spring:
  ai:
    mcp:
      client:
        enabled: true
        type: ASYNC
        http:
          connections:
            http-mcp:
              url: http://localhost:8080/mcp
              headers:
                Authorization: Bearer ${MCP_API_TOKEN}

```

## Understanding QuiteMcpClientAutoConfiguration

The `QuiteMcpClientAutoConfiguration` class (located at [`embel-agent-autoconfigure/embel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/platform/QuiteMcpClientAutoConfiguration.java`](https://github.com/embabel/embabel-agent/blob/main/embel-agent-autoconfigure/embel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/platform/QuiteMcpClientAutoConfiguration.java)) extends Spring AI's `McpClientAutoConfiguration` to provide resilient client creation.

For every transport available on the classpath, this auto-configuration creates the appropriate bean type:
- **McpSyncClient**: For synchronous, blocking operations
- **McpAsyncClient**: For reactive, non-blocking operations

If `spring.ai.mcp.client.initialized` is `true` (the default), the configuration invokes `client.initialize()` for synchronous clients or `client.initialize().block()` for asynchronous clients during bean construction.

### Fault-Tolerant Initialization Strategy

A critical feature of Embabel's implementation is its fault-tolerant initialization. If a client fails to initialize—such as when the external MCP server is offline—the `QuiteMcpClientAutoConfiguration` catches the exception, logs the error, and allows the application to continue starting. This prevents network issues from cascading into application startup failures.

## Summary

- **Activate with `@EnableAgents`**: Use the annotation with the `mcpServers` attribute to enable MCP client auto-configuration in your Embabel application
- **Configure via YAML**: Define properties under `spring.ai.mcp.client` to specify sync/async types, timeouts, and transport settings
- **Select transport type**: Use STDIO for Docker containers and command-line processes; use HTTP for REST endpoints
- **Leverage fault tolerance**: The `QuiteMcpClientAutoConfiguration` logs initialization failures without stopping the application context
- **Source reference**: Review [`QuiteMcpClientAutoConfiguration.java`](https://github.com/embabel/embabel-agent/blob/main/QuiteMcpClientAutoConfiguration.java) and [`EnableAgents.java`](https://github.com/embabel/embabel-agent/blob/main/EnableAgents.java) in the `embel-agent-autoconfigure` module for implementation details

## Frequently Asked Questions

### What is the difference between SYNC and ASYNC MCP client types?

The `type` property determines which Spring bean is instantiated. **SYNC** creates an `McpSyncClient` that blocks until operations complete, suitable for traditional imperative programming. **ASYNC** creates an `McpAsyncClient` that returns reactive types (Mono/Flux), ideal for high-concurrency scenarios using Spring WebFlux.

### How do I prevent application startup failure when an MCP server is unavailable?

Embabel's `QuiteMcpClientAutoConfiguration` handles this automatically. When initialization fails—whether due to network issues or server unavailability—the configuration catches the exception and logs the error without propagating it. This ensures your Spring Boot application starts even when external MCP servers are unreachable.

### Can I connect to multiple external MCP servers simultaneously?

Yes. Define multiple named connections under the transport section in your YAML configuration. Each entry under `stdio.connections` or `http.connections` creates a separate client bean. For example, you can configure both a `docker-mcp` and a `github-mcp` connection under the same `stdio` transport section.

### Where are the MCP client configuration properties defined?

The properties are defined in the `McpClientCommonProperties` class consumed by `QuiteMcpClientAutoConfiguration`. You can find usage examples in the repository's README under the "Consuming MCP Servers" section, and complete implementation details in [`QuiteMcpClientAutoConfiguration.java`](https://github.com/embabel/embabel-agent/blob/main/QuiteMcpClientAutoConfiguration.java) within the `embel-agent-autoconfigure` module.