> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/datadesigner/llms.txt.
> For full documentation content, see https://docs.nvidia.com/nemo/datadesigner/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/datadesigner/_mcp/server.

# data\_designer.engine.mcp.facade

## Module Contents

### Classes

| Name                                                  | Description                                         |
| ----------------------------------------------------- | --------------------------------------------------- |
| [`MCPFacade`](#data_designerenginemcpfacademcpfacade) | Lightweight facade scoped to a specific ToolConfig. |

### Functions

| Name                                                                                                            | Description                                                                     |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`_convert_canonical_tool_calls_to_dicts`](#data_designerenginemcpfacade_convert_canonical_tool_calls_to_dicts) | Convert canonical ToolCall objects to the internal dict format for ChatMessage. |

### Data

[`DEFAULT_TOOL_REFUSAL_MESSAGE`](#data_designerenginemcpfacadedefault_tool_refusal_message)

### API

```python
DEFAULT_TOOL_REFUSAL_MESSAGE = Tool call refused: You have reached the maximum number of tool-calling turns. Please provide your final response without requesting additional tool calls.
```

```python
class data_designer.engine.mcp.facade.MCPFacade(
    tool_config: data_designer.config.mcp.ToolConfig,
    secret_resolver: data_designer.engine.secret_resolver.SecretResolver,
    mcp_provider_registry: data_designer.engine.model_provider.MCPProviderRegistry
)
```

Lightweight facade scoped to a specific ToolConfig.

MCPFacade provides a clean interface for MCP tool operations within the context
of a specific tool configuration. It handles tool call extraction, validation,
and execution using the mcp.io module for communication.

This mirrors the ModelFacade pattern where each facade is scoped to a specific
configuration while sharing underlying resources through caching in the io module.

```python
tool_alias: str
```

The alias for this tool configuration.

```python
providers: list[str]
```

List of MCP provider names for this configuration.

```python
max_tool_call_turns: int
```

Maximum number of tool-calling turns permitted in a single generation.

A turn is one iteration where the LLM requests tool calls. With parallel
tool calling, a single turn may execute multiple tools simultaneously.

```python
allow_tools: list[str] | None
```

Optional allowlist of permitted tool names.

```python
timeout_sec: float | None
```

Timeout in seconds for MCP tool calls.

```python
get_tool_call_count(completion_response: data_designer.engine.models.clients.types.ChatCompletionResponse) -> int
```

Count the number of tool calls in a completion response.

```python
has_tool_calls(completion_response: data_designer.engine.models.clients.types.ChatCompletionResponse) -> bool
```

Returns True if tool calls are present in the completion response.

```python
get_tool_schemas() -> list[dict[str, typing.Any]]
```

Get OpenAI-compatible tool schemas for this configuration.

Fetches tools from all providers in the configuration and applies
allow\_tools filtering if specified. Uses cached results from mcp\_io.

**Returns:**

`list[dict[str, typing.Any]]`

List of tool schemas in OpenAI function calling format.

**Raises:**

If allowed tools are not found on any provider.

If the same tool name appears in multiple providers.

```python
process_completion_response(completion_response: data_designer.engine.models.clients.types.ChatCompletionResponse) -> list[data_designer.engine.models.utils.ChatMessage]
```

Process an LLM completion response and execute any tool calls.

This is the primary method for handling tool calls from an LLM response.
It extracts the response content, reasoning content, and all tool calls
from the completion response, executes each tool call (including parallel
tool calls), and returns the messages for continuing the conversation.

**Parameters:**

The canonical ChatCompletionResponse from the model client.

**Returns:**

`list[data_designer.engine.models.utils.ChatMessage]`

A list of ChatMessages to append to the conversation history:

* If tool calls were present: \[assistant\_message\_with\_tool\_calls, \*tool\_response\_messages]
* If no tool calls: \[assistant\_message]

**Raises:**

If a requested tool is not in the allowed tools list.

If tool execution fails or times out.

If a requested tool is not found on any configured provider.

```python
refuse_completion_response(
    completion_response: data_designer.engine.models.clients.types.ChatCompletionResponse,
    refusal_message: str | None = None
) -> list[data_designer.engine.models.utils.ChatMessage]
```

Refuse tool calls without executing them.

Used when the tool call turn budget is exhausted. Returns messages
that include the assistant's tool call request but with refusal
responses instead of actual tool results.

**Parameters:**

The canonical ChatCompletionResponse containing tool calls.

Optional custom refusal message.

**Returns:**

`list[data_designer.engine.models.utils.ChatMessage]`

A list of ChatMessages to append to the conversation history.

```python
_resolve_provider(provider: data_designer.config.mcp.MCPProviderT) -> data_designer.config.mcp.MCPProviderT
```

Resolve secret references in an MCP provider's api\_key.

```python
_build_assistant_tool_message(
    response: str | None,
    tool_calls: list[dict[str, typing.Any]],
    reasoning_content: str | None = None
) -> data_designer.engine.models.utils.ChatMessage
```

Build the assistant message containing tool call requests.

```python
_execute_tool_calls_from_canonical(tool_calls: list[data_designer.engine.models.clients.types.ToolCall]) -> list[data_designer.engine.models.utils.ChatMessage]
```

Execute canonical ToolCall objects and return tool response messages.

```python
_find_resolved_provider_for_tool(tool_name: str) -> data_designer.config.mcp.MCPProviderT
```

Find the provider that has the given tool and return it with resolved api\_key.

```python
data_designer.engine.mcp.facade._convert_canonical_tool_calls_to_dicts(tool_calls: list[data_designer.engine.models.clients.types.ToolCall]) -> list[dict[str, typing.Any]]
```

Convert canonical ToolCall objects to the internal dict format for ChatMessage.