# How to Configure MCP Server Connections (STDIO and SSE) in Embabel Agent

> Configure MCP server connections in Embabel Agent using STDIO or SSE. Learn to set the protocol and base URL for seamless integration. Get started now!

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

---

**You can configure MCP server connections in the Embabel Agent by setting `spring.ai.mcp.server.protocol` to either `STDIO` (default) or `SSE`, with optional `base-url` configuration for remote HTTP endpoints.**

The Embabel Agent implements the Model Context Protocol (MCP) to communicate with external tools and services, supporting both local process-based and remote HTTP-based transports. Understanding how to configure MCP server connections allows you to deploy agents in diverse environments—from local development setups to containerized cloud architectures.

## Configuration Properties for MCP Server Connections

The Embabel Agent uses Spring Boot properties under the `spring.ai.mcp.server` namespace to control transport behavior. All connection parameters are centralized in your [`application.yml`](https://github.com/embabel/embabel-agent/blob/main/application.yml) or `application.properties` file.

### STDIO Transport Configuration

**STDIO** is the default transport protocol. When configured, the agent spawns the MCP server as a child process and communicates through standard input and output streams. This approach works out-of-the-box when the server binary is available on the system PATH.

```yaml
spring:
  ai:
    mcp:
      enabled: true
      server:
        protocol: STDIO  # Optional; STDIO is the default

```

Under this configuration, Spring AI’s auto-configuration instantiates a `ProcessMcpClient` that launches the `embabel-mcp` binary and wires the I/O streams directly.

### SSE Transport Configuration

**SSE** (Server-Sent Events) enables HTTP-based communication with remote MCP servers. Use this protocol when the agent and MCP server run in separate processes, containers, or pods.

```yaml
spring:
  ai:
    mcp:
      enabled: true
      server:
        protocol: SSE
        base-url: http://mcp.example.com:8080  # Required for SSE

```

When SSE is selected, the `WebMvcSseServerTransportProvider` auto-registers and manages persistent HTTP connections to the endpoint specified in `base-url`.

## Enabling Specific MCP Servers with Annotations

Use the `@EnableAgents` annotation to activate built-in MCP transports for specific services like Docker or Docker Desktop:

```java
@EnableAgents(mcpServers = { McpServers.DOCKER, McpServers.DOCKER_DESKTOP })
@Configuration
public class MyAgentConfig { }

```

The `McpServers` class provides constants for well-known server types. Note that `McpServers` has been deprecated since version 0.3.1 but remains available for backward compatibility. Source references for these annotations are located in [`embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/EnableAgents.java`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-autoconfigure/embabel-agent-platform-autoconfigure/src/main/java/com/embabel/agent/config/annotation/EnableAgents.java) and [`McpServers.java`](https://github.com/embabel/embabel-agent/blob/main/McpServers.java).

## Graceful Shutdown Handling for SSE Connections

SSE connections require explicit cleanup to prevent Tomcat from waiting up to 30 seconds for idle requests during application shutdown. The Embabel Agent includes `McpSseShutdownConfiguration` to handle this automatically.

Located at [`embabel-agent-mcp/embabel-agent-mcpserver/src/main/kotlin/com/embabel/agent/mcpserver/McpSseShutdownConfiguration.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-mcp/embabel-agent-mcpserver/src/main/kotlin/com/embabel/agent/mcpserver/McpSseShutdownConfiguration.kt), this configuration implements `ApplicationListener<ContextClosedEvent>`:

```kotlin
@Configuration
internal class McpSseShutdownConfiguration :
    ApplicationListener<ContextClosedEvent> {

    @Autowired(required = false)
    private var transportProvider: WebMvcSseServerTransportProvider? = null

    private val logger = LoggerFactory.getLogger(McpSseShutdownConfiguration::class.java)

    override fun onApplicationEvent(event: ContextClosedEvent) {
        val provider = transportProvider ?: return
        logger.info("Closing MCP SSE connections before Tomcat graceful shutdown")
        provider.closeGracefully()
            .timeout(SHUTDOWN_TIMEOUT)
            .onErrorResume { error ->
                logger.warn("MCP SSE graceful shutdown did not complete cleanly: {}", error.message)
                Mono.empty()
            }
            .block()
        logger.info("MCP SSE connections closed")
    }

    companion object {
        private val SHUTDOWN_TIMEOUT: Duration = Duration.ofSeconds(5)
    }
}

```

This shutdown hook ensures all SSE sessions close within a 5-second timeout, allowing the application to terminate cleanly without hanging on active HTTP connections.

## Testing Your MCP Server Connection

The Embabel Agent includes integration tests that verify protocol switching functionality. The `McpServerProtocolIntegrationTest` validates that the server starts with SSE transport when the property is set, while `McpClientToolGroupIntegrationTest` confirms tool invocation works over SSE.

Both tests use `@TestPropertySource` to override the default protocol:

```kotlin
@TestPropertySource(properties = ["spring.ai.mcp.server.protocol=SSE"])
class McpServerProtocolIntegrationTest {
    // Test implementation
}

```

These test classes reside in `embabel-agent-mcp/embabel-agent-mcpserver/src/test/kotlin/com/embabel/agent/mcpserver/`.

## Summary

- **STDIO** is the default MCP protocol, spawning a local child process for direct I/O communication.
- **SSE** enables remote HTTP connections via Server-Sent Events, requiring the `base-url` property.
- Configure protocols using `spring.ai.mcp.server.protocol` in your Spring Boot YAML.
- Enable specific server types with `@EnableAgents(mcpServers = { ... })`.
- The `McpSseShutdownConfiguration` class ensures graceful termination of SSE connections during shutdown.
- Integration tests verify protocol behavior using `@TestPropertySource` annotations.

## Frequently Asked Questions

### What is the default MCP protocol in Embabel Agent?

The default protocol is **STDIO**. If you omit the `spring.ai.mcp.server.protocol` property, the agent automatically uses process-based communication, spawning the `embabel-mcp` binary as a child process and communicating through its standard input and output streams.

### How do I connect to a remote MCP server using SSE?

Set `spring.ai.mcp.server.protocol` to `SSE` and specify the remote endpoint in `spring.ai.mcp.server.base-url`. The agent will then use HTTP Server-Sent Events to communicate with the MCP server, allowing deployment across separate containers or cloud instances.

### Why does the SSE configuration include a shutdown hook?

The `McpSseShutdownConfiguration` prevents Tomcat's graceful shutdown phase from hanging on idle SSE connections, which can delay application termination by up to 30 seconds. The configuration closes all SSE sessions within a 5-second timeout before the Tomcat shutdown completes.

### Is the McpServers annotation still supported?

Yes, but it is **deprecated since version 0.3.1**. While `McpServers.DOCKER` and `McpServers.DOCKER_DESKTOP` constants remain functional for backward compatibility, you should monitor the Embabel Agent changelog for future migration paths to newer configuration methods.