How to Configure MCP Client Connections in application.yml for External Tools in Embabel

Configure spring.ai.mcp.sync.client or spring.ai.mcp.async.client properties in your application.yml to specify the external MCP server URL, authentication credentials, and connection timeouts, enabling Embabel agents to discover and invoke remote tools automatically.

Embabel leverages Spring AI’s Model Context Protocol (MCP) integration to connect agents with external tool servers. To route your Embabel agent to external MCP endpoints rather than local implementations, you must define the client connection parameters in the standard Spring Boot application.yml configuration file.

MCP Client Configuration Architecture

Embabel’s MCP support is implemented through two distinct configuration modes in the embabel-agent-mcpserver module. The McpSyncServerConfiguration class (located at embabel-agent-mcp/embabel-agent-mcpserver/src/main/kotlin/com/embabel/agent/mcpserver/sync/config/McpSyncServerConfiguration.kt) handles synchronous client connections using the spring.ai.mcp.sync.client property prefix. For asynchronous operations, the McpAsyncServerConfiguration class (at embabel-agent-mcp/embabel-agent-mcpserver/src/main/kotlin/com/embabel/agent/mcpserver/async/config/McpAsyncServerConfiguration.kt) manages connections under spring.ai.mcp.async.client.

Both configurations rely on Spring Boot’s @ConditionalOnProperty mechanism, ensuring that the McpClient bean is only instantiated when the required connection properties are present.

Required application.yml Properties

To establish connectivity with an external MCP server, configure the following properties in your src/main/resources/application.yml:

• base-url: The HTTP endpoint of the external MCP server (e.g., https://mcp.example.com/api)
• api-key: Authentication token passed in requests; use environment variable placeholders like ${MCP_API_KEY} to avoid hardcoding secrets
• connect-timeout: TCP connection timeout as an ISO-8601 duration (e.g., 5s)
• read-timeout: HTTP read timeout for requests (e.g., 30s)
• retry.max-attempts: Number of retry attempts for transient failures (e.g., 3)
• retry.backoff: Delay between retry attempts (e.g., 2s)

Configuration Examples

Sync Client Setup for External Tools

Use the sync configuration when your Embabel agent requires blocking I/O operations for tool execution:

spring:
  ai:
    mcp:
      sync:
        client:
          base-url: https://mcp.example.com/api
          api-key: ${MCP_API_KEY}
          connect-timeout: 5s
          read-timeout: 30s
          retry:
            max-attempts: 3
            backoff: 2s

Async Client Configuration

For non-blocking reactive operations, configure the async client:

spring:
  ai:
    mcp:
      async:
        client:
          base-url: https://mcp.example.com/api
          api-key: ${MCP_API_KEY}
          connect-timeout: 5s
          read-timeout: 30s
          retry:
            max-attempts: 3
            backoff: 2s

Disabling External MCP for Local Development

To disable external connections and rely on local tool implementations:

spring:
  ai:
    mcp:
      sync:
        client:
          enabled: false

How External Tools Are Integrated

Once configured, the McpClient bean is injected into McpToolExport (located at embabel-agent-mcp/embabel-agent-mcpserver/src/main/kotlin/com/embabel/agent/mcpserver/McpToolExport.kt). This component fetches tool definitions, resources, and prompts from the remote server. The ExportToolCallbackPublisher (at embabel-agent-mcp/embabel-agent-mcpserver/src/main/kotlin/com/embabel/agent/mcpserver/ExportToolCallbackPublisher.kt) then exposes these as standard Spring AI ToolCallback instances, making external tools available to your Embabel agent without requiring code changes.

Summary

• Configure spring.ai.mcp.sync.client or spring.ai.mcp.async.client in application.yml to connect to external MCP servers
• Set base-url and api-key for authentication and endpoint discovery
• Use enabled: false to disable external connections during local testing
• The configuration activates beans in McpSyncServerConfiguration or McpAsyncServerConfiguration that inject clients into the tool export pipeline

Frequently Asked Questions

What is the difference between sync and async MCP client modes in Embabel?

The sync mode uses McpSyncServerConfiguration for blocking I/O operations, suitable for simple request-response tool calls. The async mode leverages McpAsyncServerConfiguration for non-blocking reactive operations, ideal for high-concurrency scenarios where the agent must handle multiple simultaneous tool invocations without blocking threads.

How do I secure the MCP API key in production?

Use environment variable placeholders like ${MCP_API_KEY} in your application.yml instead of hardcoding values. Spring Boot resolves these at runtime from system environment variables or external secret management systems, ensuring credentials never appear in source control.

Can I configure multiple external MCP servers in one application.yml?

The current Embabel MCP starter configuration supports single server connections per mode via the base-url property. To connect to multiple external MCP servers simultaneously, you would need to define custom McpClient beans programmatically or run separate agent instances with distinct Spring profiles.

Why are my external tools not appearing in the Embabel agent?

Verify that the base-url is reachable from the agent’s network and the api-key is valid. Check that enabled is not set to false in your configuration. Ensure your classpath includes the embabel-agent-mcpserver module, and review application logs for connection errors during McpToolExport initialization.

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