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

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 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.

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.

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:

@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 and 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, this configuration implements ApplicationListener<ContextClosedEvent>:

@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:

@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.

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