For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
  • Getting Started
    • Welcome
    • Contributing
  • Concepts
    • Columns
    • Seed Datasets
    • Agent Rollout Ingestion
    • Custom Columns
    • Validators
    • Processors
    • Person Sampling
    • Traces
    • Architecture & Performance
    • Deployment Options
    • Security
  • Tutorials
    • Overview
    • The Basics
    • Structured Outputs, Jinja Expressions, and Conditional Generation
    • Seeding with an External Dataset
    • Providing Images as Context
    • Generating Images
    • Image-to-Image Editing
  • Recipes
    • Recipe Cards
  • Plugins
    • Overview
    • Example Plugin
    • FileSystemSeedReader Plugins
    • Discover
  • Code Reference
    • Overview
      • Overview
      • seed_readers
      • processors
      • mcp
      • column_generators
      • Seed Reader API
      • Processor API
      • MCP Runtime API
        • Errors
        • Facade
        • Factory
        • Io
        • Registry
      • Column Generator API
  • Dev Notes
    • Overview
    • Push Datasets to Hugging Face Hub
    • Text-to-SQL for Nemotron Super
    • Async All the Way Down
    • Owning the Model Stack
    • Data Designer Got Skills
NVIDIANVIDIA
Developer-friendly docs for your API
Privacy Policy | Your Privacy Choices | Terms of Service | Accessibility | Corporate Policies | Product Security | Contact

Copyright © 2026, NVIDIA Corporation.

LogoLogoNeMo Data Designer
On this page
  • Module Contents
  • Classes
  • Functions
  • Data
  • API
Code ReferenceEngine Extension APIMCP Runtime API

data_designer.engine.mcp.facade

||View as Markdown|
Previous

Errors

Next

Factory

Module Contents

Classes

NameDescription
MCPFacadeLightweight facade scoped to a specific ToolConfig.

Functions

NameDescription
_convert_canonical_tool_calls_to_dictsConvert canonical ToolCall objects to the internal dict format for ChatMessage.

Data

DEFAULT_TOOL_REFUSAL_MESSAGE

API

1DEFAULT_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.
 
1class data_designer.engine.mcp.facade.MCPFacade(
2    tool_config: data_designer.config.mcp.ToolConfig,
3    secret_resolver: data_designer.engine.secret_resolver.SecretResolver,
4    mcp_provider_registry: data_designer.engine.model_provider.MCPProviderRegistry
5)

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.

1tool_alias: str

The alias for this tool configuration.

1providers: list[str]

List of MCP provider names for this configuration.

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

1allow_tools: list[str] | None

Optional allowlist of permitted tool names.

1timeout_sec: float | None

Timeout in seconds for MCP tool calls.

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

Count the number of tool calls in a completion response.

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

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

1get_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:

MCPConfigurationError

If allowed tools are not found on any provider.

DuplicateToolNameError

If the same tool name appears in multiple providers.

1process_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:

completion_response
data_designer.engine.models.clients.types.ChatCompletionResponse

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:

MCPToolError

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

MCPToolError

If tool execution fails or times out.

MCPConfigurationError

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

1refuse_completion_response(
2    completion_response: data_designer.engine.models.clients.types.ChatCompletionResponse,
3    refusal_message: str | None = None
4) -> 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:

completion_response
data_designer.engine.models.clients.types.ChatCompletionResponse

The canonical ChatCompletionResponse containing tool calls.

refusal_message
str | NoneDefaults to None

Optional custom refusal message.

Returns:

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

A list of ChatMessages to append to the conversation history.

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

Resolve secret references in an MCP provider’s api_key.

1_build_assistant_tool_message(
2    response: str | None,
3    tool_calls: list[dict[str, typing.Any]],
4    reasoning_content: str | None = None
5) -> data_designer.engine.models.utils.ChatMessage

Build the assistant message containing tool call requests.

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

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

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