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

> Configure MCP client connections in application.yml for external tools in Embabel. Specify server URL, credentials, and timeouts to enable automatic remote tool discovery and invocation.

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

---

**Configure `spring.ai.mcp.sync.client` or `spring.ai.mcp.async.client` properties in your [`application.yml`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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`](https://github.com/embabel/embabel-agent/blob/main/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:

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

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

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