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

> Learn to configure Spring profiles for Docker Desktop MCP integration in Embabel. Activate the docker-desktop profile and set up the application-docker-desktop.yml for seamless connection via STDIO.

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

---

**Activate the `docker-desktop` Spring profile and provide the MCP client configuration in [`application-docker-desktop.yml`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/McpServers.java) at [`embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/McpServers.java`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/application.yml)**:

```yaml
spring:
  profiles:
    active: docker-desktop

```

- **JVM system property**:

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

```

- **environment variable**:

```bash
export SPRING_PROFILES_ACTIVE=docker-desktop

```

### Step 2: Configure the MCP Client Connection

Create or edit [`src/main/resources/application-docker-desktop.yml`](https://github.com/embabel/embabel-agent/blob/main/src/main/resources/application-docker-desktop.yml) with the following MCP client configuration:

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

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

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