How to Configure Spring Profiles for Docker Desktop MCP Integration in Embabel

Activate the docker-desktop Spring profile and provide the MCP client configuration in application-docker-desktop.yml to connect Embabel to Docker Desktop's Model Context Protocol (MCP) server via STDIO-based Docker socat transport.

Embabel provides built-in support for Docker Desktop's Model Context Protocol (MCP) through a dedicated Spring profile named docker-desktop. When this profile is active, Embabel's auto-configuration machinery automatically creates an MCP client that bridges to the Docker-provided MCP server. This integration enables access to MCP tools like Brave Search, Fetch, Puppeteer, and Wikipedia directly from your Embabel agents.

Understanding the docker-desktop Spring Profile

The docker-desktop profile is the central mechanism for enabling Docker Desktop MCP integration in Embabel. According to the embabel-agent source code, this profile is referenced by the McpServers.DOCKER_DESKTOP constant defined in McpServers.java at embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/McpServers.java.

When you activate this profile, the QuiteMcpClientAutoConfiguration class—located at embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/autoconfigure/platform/QuiteMcpClientAutoConfiguration.java—conditionally creates the MCP client only when the profile is present. This design ensures that MCP functionality is opt-in and doesn't interfere with standard operation.

Step-by-Step Configuration

Step 1: Activate the docker-desktop Profile

You can activate the profile through any standard Spring Boot mechanism:

• in application.yml:

spring:
  profiles:
    active: docker-desktop

• JVM system property:

java -jar my-app.jar --spring.profiles.active=docker-desktop

• environment variable:

export SPRING_PROFILES_ACTIVE=docker-desktop

Step 2: Configure the MCP Client Connection

Create or edit src/main/resources/application-docker-desktop.yml with the following MCP client configuration:

spring:
  profiles:
    include: docker-desktop

  ai:
    mcp:
      client:
        enabled: true
        name: embabel
        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

This configuration uses Docker to run alpine/socat, which creates a STDIO-to-TCP bridge to host.docker.internal:8811—the standard Docker Desktop MCP server endpoint.

Step 3: Enable Agents with the Docker Desktop MCP Server

Annotate your main application class with @EnableAgents and reference the McpServers.DOCKER_DESKTOP constant:

import com.embabel.agent.config.annotation.EnableAgents;
import com.embabel.agent.config.annotation.McpServers;

@EnableAgents(mcpServers = {McpServers.DOCKER_DESKTOP})
@SpringBootApplication
public class MyAgentApp {
    public static void main(String[] args) {
        SpringApplication.run(MyAgentApp.class, args);
    }
}

Combining with Optional Logging Profiles

Embabel supports personality-based logging profiles that can be combined with docker-desktop:

java -jar my-agent-app.jar --spring.profiles.active=docker-desktop,severance

Available logging profiles include:

• severance — Severance-themed console output
• starwars — Star Wars-themed console output
• colossus — Colossus-themed console output

These profiles control console aesthetics without affecting MCP functionality.

How the Auto-Configuration Works

The Docker Desktop MCP integration relies on Spring Boot's conditional auto-configuration:

1. Profile detection: QuiteMcpClientAutoConfiguration checks for the docker-desktop profile using @Profile("docker-desktop")

2. Client creation: When the profile is active, the configuration class creates an MCP client with the properties defined in application-docker-desktop.yml

3. Graceful degradation: If the profile is not active, MCP client creation is skipped entirely. You can also explicitly disable MCP with spring.ai.mcp.client.enabled=false

4. Resilient operation: The QuiteMcpClientAutoConfiguration class (the "Quite" prefix indicates graceful failure handling) ensures that MCP connection failures don't crash your application

Customizing the MCP Connection

If you need to modify the default Docker Desktop MCP connection, copy the configuration from the example application-docker-desktop.yml and adjust these key properties:

Property	Purpose	Default
spring.ai.mcp.client.request-timeout	Request timeout duration	30s
spring.ai.mcp.client.type	Client type (SYNC/ASYNC)	SYNC
spring.ai.mcp.client.stdio.connections.*.command	The executable to run	docker
spring.ai.mcp.client.stdio.connections.*.args	Arguments passed to the command	run -i --rm alpine/socat STDIO TCP:host.docker.internal:8811

Prerequisites for Docker Desktop MCP

Before the integration works, you must:

1. Install Docker Desktop with MCP catalog support (version 4.40 or later)

2. Enable Use containerd for pulling and storing images in Docker Desktop settings

3. Install desired MCP tools from the Docker Desktop MCP catalog (Brave Search, Fetch, Puppeteer, Wikipedia, etc.)

4. Verify the MCP server is listening on port 8811 inside Docker Desktop

Summary

• The docker-desktop profile is required to enable Docker Desktop MCP integration in Embabel

• Configuration lives in application-docker-desktop.yml with STDIO-based Docker socat transport settings

• @EnableAgents(mcpServers = {McpServers.DOCKER_DESKTOP}) activates the integration in your application code

• QuiteMcpClientAutoConfiguration creates the client conditionally and handles failures gracefully

• Optional logging profiles (severance, starwars, colossus) can be combined for themed console output

• Prerequisites: Docker Desktop with MCP catalog and tools installed on port 8811

Frequently Asked Questions

What happens if I don't activate the docker-desktop profile?

Without the docker-desktop profile active, Embabel skips MCP client creation entirely. Your application runs normally but cannot access Docker Desktop's MCP tools. According to the source code in QuiteMcpClientAutoConfiguration.java, the auto-configuration class is annotated with @Profile("docker-desktop"), making it conditional on this specific profile.

Can I use a different port than 8811 for the MCP server?

Yes. Modify the args list in your application-docker-desktop.yml to change the target port. For example, to use port 9000, change the last argument to TCP:host.docker.internal:9000. Ensure your Docker Desktop MCP server is configured to listen on the matching port.

How do I verify that MCP tools are available to my Embabel agents?

Start your application with the docker-desktop profile and DEBUG logging enabled: --logging.level.com.embabel.agent=DEBUG. The logs will show MCP client initialization and available tool discovery. You can also inject List<McpClient> into a bean and inspect its contents programmatically.

Can I disable MCP without removing the profile?

Yes. Set spring.ai.mcp.client.enabled=false in your configuration. This property takes precedence and prevents MCP client creation even when the docker-desktop profile is active. This is useful for testing profile-specific behavior without actual MCP connectivity.

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