# Integrate tools using an MCP server

> Integrate tools using an MCP server - Learn how to integrate tools into your agentic workflows using
> the Model Context Protocol (MCP) server instead of direct tool deployments.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-04-24T16:03:56.229347+00:00` (UTC).

## Primary page

- [Integrate tools using an MCP server](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html): Full documentation for this topic (HTML).

## Sections on this page

- [Overview](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#overview): In-page section heading.
- [MCP architecture](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#mcp-architecture): In-page section heading.
- [Integration workflow](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#integration-workflow): In-page section heading.
- [Prerequisites](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#prerequisites): In-page section heading.
- [MCP server deployment](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#mcp-server-deployment): In-page section heading.
- [Local deployment](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#local-deployment): In-page section heading.
- [Production deployment](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#production-deployment): In-page section heading.
- [Configure MCP server connection](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#configure-mcp-server-connection): In-page section heading.
- [Local development](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#local-development): In-page section heading.
- [Production configuration](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#production-configuration): In-page section heading.
- [Use MCP tools in agents](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#use-mcp-tools-in-agents): In-page section heading.
- [LangGraph agents](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#langgraph-agents): In-page section heading.
- [Combine MCP tools with local tools](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#combine-mcp-tools-with-local-tools): In-page section heading.
- [Create custom MCP tools](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#create-custom-mcp-tools): In-page section heading.
- [Tool structure](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#tool-structure): In-page section heading.
- [Tool best practices](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#tool-best-practices): In-page section heading.
- [Comparison: MCP vs. ToolClient](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#comparison-mcp-vs-toolclient): In-page section heading.
- [Troubleshooting](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#troubleshooting): In-page section heading.
- [Agent can't connect to MCP server](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#agent-cant-connect-to-mcp-server): In-page section heading.
- [Tools not appearing](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#tools-not-appearing): In-page section heading.
- [Authentication issues](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#authentication-issues): In-page section heading.
- [Additional resources](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-tools-mcp.html#additional-resources): In-page section heading.

## Related documentation

- [Agentic AI](https://docs.datarobot.com/en/docs/agentic-ai/index.html): Linked from this page.
- [MCP](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/index.html): Linked from this page.
- [DataRobot Global MCP](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-mcp-clients.html#using-the-datarobot-global-mcp): Linked from this page.
- [Add tools to agents](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-tools-integrate.html): Linked from this page.
- [task](https://docs.datarobot.com/en/docs/agentic-ai/cli/commands/task.html): Linked from this page.
- [run](https://docs.datarobot.com/en/docs/agentic-ai/cli/commands/run.html): Linked from this page.

## Documentation content

# 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
- 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](https://github.com/datarobot-community/datarobot-agent-application). MCP endpoints can come from the Agentic Starter app, a standalone server built with the [DataRobot MCP template](https://github.com/datarobot-community/af-component-datarobot-mcp), or the [DataRobot Global MCP](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-mcp-clients.html#using-the-datarobot-global-mcp); this page focuses on connecting your agent application to the MCP URL your deployment uses.

> [!NOTE] MCP vs. local tool integration
> This documentation covers MCP server-based tool integration. For information about integrating tools using local tools (direct tool deployments), see [Add tools to agents](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-tools-integrate.html). To connect MCP clients in Cursor, Claude Desktop, or VS Code—including the DataRobot Global MCP and deployment URLs—see [Connect agentic coding environments to MCP servers](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-mcp-clients.html).

## 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](https://github.com/datarobot-community/datarobot-agent-application) includes built-in support for MCP tools through the `LangGraphAgent` base class, which provides the `mcp_tools` property that automatically connects to your configured MCP server.
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 : Create and deploy an MCP server containing your tool logic (using the DataRobot MCP template ), use the MCP server bundled with the DataRobot Agentic Starter template , or connect through the DataRobot Global MCP when your environment uses that service.
- Connect the agent : Configure your agent application to point to the MCP server's URL (for example, a deployment directAccess URL, a gateway URL, or a local dev URL).
- 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 , the MCP server included with the DataRobot Agentic Starter template , or the DataRobot Global MCP (depending on your setup).
- 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](https://github.com/datarobot-community/af-component-datarobot-mcp/blob/main/README.md). For URL patterns (local ports, deployment `directAccess`, gateway), see [Connect agentic coding environments to MCP servers](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-mcp-clients.html).

## MCP server deployment

The MCP server can be deployed either locally for development or to DataRobot for production use.

### Local deployment

For local development, start the MCP server using the development command:

```
cd mcp_server
dr task run mcp_server:dev
```

The MCP server will start on the configured port (default: `9000`) and be accessible at `http://localhost:9000/mcp/`.

### Production deployment

To deploy the MCP server to DataRobot:

1. Configure deployment settings: Update your Pulumi configuration or deployment settings.
2. Deploy the server: Use the deployment command: drrundeploy You can also usedr task run deploy, which is equivalent. For more on these commands, see the CLItaskandruncommands.
3. Get the deployment endpoint: After deployment, note the deployment ID and construct the MCP endpoint URL: https://{DATAROBOT_URL}/api/v2/deployments/{DEPLOYMENT_ID}/directAccess/mcp Some environments use theDataRobot Global MCPinstead of a per-deploymentdirectAccessURL: https://{DATAROBOT_URL}/api/v2/genai/globalmcp/mcp SeeUsing the DataRobot Global MCPfor how Global MCP URLs fit alongside deployment endpoints.
4. Configure the agent: Update your agent's configuration to use the production MCP endpoint (whichever URL your deployment provides).

For detailed deployment instructions, refer to the [MCP template README](https://github.com/datarobot-community/af-component-datarobot-mcp/blob/main/README.md).

## Configure MCP server connection

To connect your agent to an MCP server, you need to configure the MCP server endpoint and authentication in your agent's environment variables or configuration.

### Local development

For local development, configure the MCP server connection in your `.env` file:

```
# .env
# MCP Server Configuration
MCP_SERVER_PORT=9000
```

The MCP server uses one of two ports by default:

- Port 8080 when deployed using the DataRobot MCP template
- Port 9000 when deployed using the DataRobot Agentic Starter template

Make sure to use the correct port when configuring the agent.

### Production configuration

For production deployments, configure the MCP server using environment variables.
This process is handled automatically by the template.

> [!NOTE] MCP server authentication
> If your MCP server requires authentication, ensure that `DATAROBOT_API_TOKEN` is set in your environment, as the MCP client will use it automatically for authenticated requests. HTTP MCP endpoints often expect both `Authorization: Bearer` and `x-datarobot-api-token` headers; the client typically supplies these from your DataRobot API credentials. For the same headers in Cursor, Claude Desktop, and VS Code, see [Connect agentic coding environments to MCP servers](https://docs.datarobot.com/en/docs/agentic-ai/agentic-mcp/agentic-mcp-clients.html).

## Use MCP tools in agents

The `LangGraphAgent` base class (used in the [DataRobot Agentic Starter template](https://github.com/datarobot-community/datarobot-agent-application)) provides automatic MCP tool integration through the `mcp_tools` property.

### LangGraph agents

For LangGraph agents, MCP tools are automatically available through the `mcp_tools` property:

```
# agent/agent/myagent.py
from datarobot_genai.core.agents import make_system_prompt
from datarobot_genai.langgraph.agent import LangGraphAgent
from langchain.agents import create_agent
from typing import Any

class MyAgent(LangGraphAgent):
    """Agent that uses MCP tools for external integrations."""

    @property
    def agent_planner(self) -> Any:
        return create_agent(
            self.llm(),
            tools=self.mcp_tools,  # MCP tools are automatically available
            system_prompt=make_system_prompt(
                "You are a content planner. Use available tools to gather information and plan content."
            ),
            name="planner_agent",
        )
```

The `mcp_tools` property automatically:

- Connects to the configured MCP server
- Discovers available tools
- Converts MCP tools to LangChain-compatible tools
- Handles authentication if required

### Combine MCP tools with local tools

You can combine MCP tools with local tools by merging the tool lists:

```
# agent/agent/myagent.py
from datarobot_genai.core.agents import make_system_prompt
from datarobot_genai.langgraph.agent import LangGraphAgent
from langchain.agents import create_agent
from langchain_core.tools import Tool
from typing import Any

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")

class MyAgent(LangGraphAgent):
    """Agent that uses both MCP tools and local tools."""

    @property
    def agent_planner(self) -> Any:
        # Combine MCP tools with local tools
        local_tools = [DateTimeTool()]
        all_tools = list(self.mcp_tools) + local_tools

        return create_agent(
            self.llm(),
            tools=all_tools,
            system_prompt=make_system_prompt(
                "You are a content planner. Use available tools to gather information and plan content."
            ),
            name="planner_agent",
        )
```

## Create custom MCP tools

To add custom tools to your MCP server, use the [DataRobot MCP template](https://github.com/datarobot-community/af-component-datarobot-mcp). 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:

```
# dr_mcp/app/recipe/tools/my_custom_tool.py
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
```

> [!NOTE] MCP template repository
> The path and imports above refer to the [DataRobot MCP template](https://github.com/datarobot-community/af-component-datarobot-mcp) repository structure.

### 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](https://github.com/datarobot-community/af-component-datarobot-mcp/blob/main/docs/custom_tools.md).

## Comparison: MCP vs. ToolClient

| Feature | MCP Server | ToolClient (Direct Deployment) |
| --- | --- | --- |
| Tool management | Centralized in one server | Each tool deployed separately |
| Protocol | MCP standard protocol | DataRobot custom protocol |
| Tool discovery | Automatic via MCP | Manual configuration per tool |
| Dynamic updates | Tools can be added/modified without agent redeployment | Requires agent redeployment for new tools |
| Framework compatibility | Works with any MCP-compatible framework | DataRobot-specific |
| Deployment complexity | Single MCP server deployment | Multiple tool deployments |
| Scaling | Scale MCP server independently | Scale each tool independently |

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 MCP server is running: # For local developmentcurl-ihttp://localhost:9000/mcp# For production (deployment MCP endpoint)curl-ihttps://{DATAROBOT_URL}/api/v2/deployments/{DEPLOYMENT_ID}/directAccess/mcp# If your environment uses the DataRobot Global MCPcurl-ihttps://{DATAROBOT_URL}/api/v2/genai/globalmcp/mcp
2. Check environment variables:
3. Verify network connectivity:

### 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