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

Enable the @EnableAgents annotation on your Spring Boot application class and define transport connections in 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. This annotation scans the classpath and activates the Spring profiles required for MCP client auto-configuration.

Activate MCP support using the mcpServers attribute:

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:

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:

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) 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 and 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 within the embel-agent-autoconfigure module.

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