Integrate tools using an MCP server¶

The Model Context Protocol (MCP) provides a standardized interface for AI agents to interact with external systems, tools, and data sources. Using an MCP server to provide tools to your agents offers several advantages over direct tool deployments:

• Centralized tool management: All tools are managed in one MCP server deployment
• Standardized interface: Tools follow the MCP protocol standard, making them compatible across different agent frameworks
• Dynamic tool registration: Tools can be added or modified without redeploying the agent (see Dynamic tool registration)
• Better separation of concerns: Tools are deployed separately from agents, enabling independent scaling and updates

This guide explains how to integrate tools using an MCP server with your agentic workflows, as implemented in the DataRobot Agentic Starter template. MCP endpoints can come from the Agentic Starter app, a standalone server built with the DataRobot MCP template, or the DataRobot Global MCP; this page focuses on connecting your agent application to the MCP URL your deployment uses.

Overview¶

The Model Context Protocol (MCP) fundamentally changes how agents access tools. Instead of defining tool logic directly within the agent's code, you deploy a standalone "Tool Server." Your agent then connects to this server as a client, requesting available tools and executing them via a standardized protocol.

The DataRobot Agentic Starter template connects MCP tools at runtime: LangGraph workflows receive MCP (and optional workflow) tools as the tools argument to graph_factory, using mcp_tools_context in custompy_adaptor (DRUM) and in register.py (DRAgent). You do not import the MCP server into agent code. Refer to the sections below for more information on how to use MCP tools in your agentic workflows.

MCP architecture¶

• The agent (client): The reasoning engine (e.g., a LangGraph application) that plans tasks. It does not contain tool code; it only knows how to ask the MCP server what tools are available.
• The MCP server: A web service hosting the logic for tools, resources, and prompts. It handles the actual execution of tasks (e.g., querying a database, calling an external API).
• The protocol: A standard interface that allows the agent and MCP server to communicate securely, regardless of the underlying infrastructure.

Integration workflow¶

To integrate tools using this architecture, follow this high-level process:

• Deploy or select an MCP endpoint: Use the DataRobot MCP template) to create and deploy an MCP server containing your tool logic. Or, connect through the DataRobot Global MCP for the built-in DataRobot tools.
• Connect the agent: Point the agent to your MCP server in the application’s .env file, using an external URL, a deployment or workload ID, or a local port. See Configure MCP server connection.
• Execute: The agent automatically discovers tools at runtime. You do not need to redeploy the agent to add new tools; you only update the MCP server.

Prerequisites¶

Before integrating MCP tools, ensure you have:

• A reachable MCP endpoint: a server built with the DataRobot MCP template or the DataRobot Global MCP (depending on your setup). The Agentic Starter template doesn't include an MCP server.
• An agentic workflow based on the DataRobot Agentic Starter template.
• The MCP endpoint URL and authentication credentials (if required).

For deploying a standalone MCP server, refer to the MCP template documentation. For URL patterns (local ports, deployment directAccess, gateway), see Connect agentic coding environments to MCP servers.

MCP server deployment¶

The Agentic Starter template doesn't include an MCP server. For the built-in DataRobot tools, you can use the DataRobot Global MCP without deploying anything. For your own tools, run a standalone MCP server built from the DataRobot MCP template, either locally for development or in DataRobot for production use.

Local deployment¶

To run a standalone MCP server on the same machine as your agent, use the MCP template project. The MCP template serves on port 8080 by default, which the Agentic Starter backend also uses. Before you start the server, set a different port in the MCP template project’s .env file:

MCP_SERVER_PORT=9000

The server is then available at http://localhost:9000/mcp/. To connect the agent to it, see Local development.

Production deployment¶

To deploy a standalone MCP server to DataRobot:

1. Deploy the server. In the MCP template project, run:

   task deploy
   

2. Get the deployment ID. Read the server's deployment outputs (for example, uv run pulumi stack output --json from the infra directory) and copy the MCP server's Deployment Id value. If you deployed the server to the Workload API, copy its Workload Id value instead.

3. For clients other than the agent, get the deployment endpoint. The MCP endpoint URL is:

   https://{DATAROBOT_URL}/api/v2/deployments/{DEPLOYMENT_ID}/directAccess/mcp
   

   Some environments use the DataRobot Global MCP instead of a per-deployment directAccess URL:

   https://{DATAROBOT_URL}/api/v2/genai/globalmcp/mcp
   

   See Using the DataRobot Global MCP for how Global MCP URLs fit alongside deployment endpoints.

4. Configure the agent. Set the deployment ID or Workload ID in your agent application's .env file. See Production configuration.

For detailed deployment instructions, refer to the MCP template README.

Configure MCP server connections¶

To connect your agent to an MCP server, set one of the following in the Agentic Starter project's .env file. When more than one is set, the agent uses the first one in this table. If none are set, the agent runs without MCP tools.

For example, to use the DataRobot Global MCP for the built-in DataRobot tools:

EXTERNAL_MCP_URL=https://{DATAROBOT_URL}/api/v2/genai/globalmcp/mcp
EXTERNAL_MCP_HEADERS='{"Authorization": "Bearer <DATAROBOT_API_TOKEN>"}'

The agent doesn't send its DataRobot credentials to an EXTERNAL_MCP_URL, so include the API key in EXTERNAL_MCP_HEADERS.

Local development¶

To connect the agent to an MCP server running on your machine, set the server's port in the Agentic Starter project's .env file:

MCP_SERVER_PORT=9000

Leave MCP_WORKLOAD_ID, MCP_DEPLOYMENT_ID, and EXTERNAL_MCP_URL unset, because they take precedence over MCP_SERVER_PORT. When the agent runs locally, it always uses the settings in .env.

Production configuration¶

To connect a deployed agent to an MCP server deployed in DataRobot, set its ID in .env:

MCP_DEPLOYMENT_ID=<deployment ID>
# Or, for a server on the Workload API:
# MCP_WORKLOAD_ID=<workload ID>

dr run deploy passes MCP_WORKLOAD_ID, MCP_DEPLOYMENT_ID, EXTERNAL_MCP_URL, EXTERNAL_MCP_HEADERS, and EXTERNAL_MCP_TRANSPORT to the deployed agent as runtime parameters. MCP_SERVER_PORT is not passed, because it only applies to your local machine. To point a deployed agent at another server, change the setting in .env and run dr run deploy again, or edit the runtime parameter on the deployment in DataRobot.

Use MCP tools in agents¶

In the current DataRobot Agentic Starter template (LangGraph), MCP tools are passed into your graph_factory(llm, tools, verbose) as the tools list. The template merges MCP discovery with any workflow tools before calling MyAgent.

LangGraph agents¶

For LangGraph agents, pass the tools argument through to each create_agent node:

from datarobot_genai.core.agents import make_system_prompt
from langchain.agents import create_agent

def graph_factory(llm, tools, verbose=False):
    planner = create_agent(
        llm,
        tools=tools,
        system_prompt=make_system_prompt(
            "You are a content planner. Use available tools to gather information and plan content."
        ),
        name="planner_agent",
        debug=verbose,
    )
    ...

At runtime, tools includes MCP tools resolved via mcp_tools_context (see the template's custompy_adaptor and register.py). That flow:

• Connects to the configured MCP server
• Discovers available tools
• Exposes LangChain-compatible tools to the graph
• Applies authentication headers and authorization context when required

Supported built-in MCP tools¶

For the standalone DataRobot MCP template, built-in tools currently include:

• DataRobot platform tools: catalog_*, modeling_*, models_get_bestmodel, deployment_*, predict_*, vdb_*, datarobot_usecases_list, usecases_list_assets, and datarobot_docs_fetch_page
• Data connector tools: confluence_*, jira_*, gdrive_*, and microsoft_graph_* (OAuth configuration required)
• DataRobot platform tools: catalog_*, modeling_*, models_get_bestmodel, deployment_*, predict_*, vdb_*, datarobot_usecases_list, usecases_list_assets, and datarobot_docs_fetch_page.
• Data connector tools: confluence_*, jira_*, gdrive_*, and microsoft_graph_* (OAuth configuration required).
• Web search tools: perplexity_* and tavily_* (API keys required).

For the full tool-by-tool inventory, see Supported built-in MCP tools in the MCP overview.

Combine MCP tools with local tools¶

Add local tools inside graph_factory by extending the list (MCP tools are already in tools):

from langchain_core.tools import Tool

class DateTimeTool(Tool):
    """Local datetime tool."""
    name = "datetime_tool"
    description = "Returns the current date and time."

    def run(self, query: str = "") -> str:
        from datetime import datetime
        return datetime.now().strftime("%Y-%m-%d %H:%M:%S")

def graph_factory(llm, tools, verbose=False):
    local_tools = [DateTimeTool()]
    all_tools = list(tools) + local_tools
    planner = create_agent(
        llm,
        tools=all_tools,
        system_prompt=make_system_prompt("You are a content planner..."),
        name="planner_agent",
        debug=verbose,
    )
    ...

Create custom MCP tools¶

To add custom tools to your MCP server, use the DataRobot MCP template. The template provides a structured approach for creating tools, resources, and prompts.

Tool structure¶

Custom MCP tools are defined using the @dr_mcp_tool decorator:

from app.base.core.mcp_instance import dr_mcp_tool
from app.base.core.common import get_sdk_client

@dr_mcp_tool(tags={"custom", "recipe", "your-domain"})
async def my_custom_tool(input_param: str, optional_param: int = 10) -> str:
    """
    Brief description of what your tool does.

    This description helps LLMs understand when and how to use your tool.
    Be specific about the tool's purpose and behavior.

    Args:
        input_param: Description of the required parameter
        optional_param: Description of the optional parameter

    Returns:
        Description of what the tool returns
    """
    # Use the DataRobot SDK client for API operations
    client = get_sdk_client()

    # Your custom logic here
    result = f"Processed {input_param} with {optional_param}"

    return result

Tool best practices¶

When creating MCP tools, follow these best practices:

• Clear descriptions: Provide detailed docstrings—LLMs use these to understand tool capabilities
• Type hints: Always use type hints for parameters and return values
• Error handling: Implement proper error handling and return meaningful error messages
• Async functions: Tools should be async functions for better performance
• Tags: Use descriptive tags to categorize tools (helps with tool filtering)
• SDK client: Use get_sdk_client() for DataRobot API access

For more information on creating custom MCP tools, see the MCP template custom tools documentation.

Comparison: MCP vs. ToolClient¶

Choose MCP server integration when:

• You want centralized tool management
• You need dynamic tool registration
• You're using multiple agents that share tools
• You want standard protocol compliance

Choose ToolClient integration when:

• You need fine-grained control over individual tool deployments
• Tools have very different scaling requirements
• You prefer DataRobot-specific tool management features

Troubleshooting¶

Agent can't connect to MCP server¶

Symptoms: Agent errors mention MCP connection failures or tools not available.

Solutions:

1. Verify the MCP server is running:

   # For local development (use the port set in MCP_SERVER_PORT)
   curl -i http://localhost:{MCP_SERVER_PORT}/mcp
   
   # For production (deployment MCP endpoint)
   curl -i https://{DATAROBOT_URL}/api/v2/deployments/{DEPLOYMENT_ID}/directAccess/mcp
   
   # If your environment uses the DataRobot Global MCP
   curl -i https://{DATAROBOT_URL}/api/v2/genai/globalmcp/mcp
   

2. Check environment variables:

   • Verify that one of MCP_WORKLOAD_ID, MCP_DEPLOYMENT_ID, EXTERNAL_MCP_URL, or MCP_SERVER_PORT is set. If none is set, the agent runs without MCP tools.
   • If a setting has no effect, check whether a setting with higher precedence is also set (see Configure MCP server connection), and remove the ones you don't use.
   • Verify MCP_SERVER_PORT matches the port the local MCP server listens on (for local development).
   • Check that DATAROBOT_API_TOKEN is set (for authenticated connections).

3. Verify network connectivity:

   • Ensure the agent can reach the MCP server endpoint.
   • Check firewall settings if deploying across networks.
   • Verify SSL certificates for HTTPS endpoints.

Tools not appearing¶

Symptoms: MCP server is connected, but the agent cannot use tools.

Solutions:

1. Check tool registration: Verify that tools are properly registered in the MCP server.
2. Review tool metadata: Ensure tool descriptions and schemas are correctly defined.
3. Check server logs: Review MCP server logs for tool registration errors.
4. Verify agent configuration: Confirm that the mcp_tools property is being used correctly.

Authentication issues¶

Symptoms: MCP server requests fail with authentication errors.

Solutions:

1. Verify API token: Ensure DATAROBOT_API_TOKEN is set and valid.
2. Check token permissions: Verify the token has necessary permissions for MCP server access.
3. Review server configuration: Check that the MCP server is configured to accept the authentication method used.

Additional resources¶

• Connect agentic coding environments to MCP servers — DataRobot Global MCP, deployment and local URLs, and client configuration (Cursor, Claude Desktop, VS Code)
• DataRobot MCP template - template for creating and deploying MCP servers
• DataRobot Agentic Starter template - Application template with MCP integration
• MCP Protocol Documentation - Official MCP protocol specification
• Add tools to agents - Documentation for ToolClient-based tool integration
• MCP Client Setup Guide - Guide for configuring MCP clients