Skip to main content

use_mcp_tool

The use_mcp_tool tool enables interaction with external tools provided by connected Model Context Protocol (MCP) servers. It extends Roo's capabilities with domain-specific functionality through a standardized protocol.

Parameters​

The tool accepts these parameters:

  • server_name (required): The name of the MCP server providing the tool
  • tool_name (required): The name of the tool to execute
  • arguments (required/optional): A JSON object containing the tool's input parameters, following the tool's input schema. May be optional for tools that require no input.

What It Does​

This tool allows Roo to access specialized functionality provided by external MCP servers. Each MCP server can offer multiple tools with unique capabilities, extending Roo beyond its built-in functionality. The system validates arguments against schemas, manages server connections, and processes responses of various content types (text, image, resource).

When is it used?​

  • When specialized functionality not available in core tools is needed
  • When domain-specific operations are required
  • When integration with external systems or services is needed
  • When working with data that requires specific processing or analysis
  • When accessing proprietary tools through a standardized interface

Key Features​

  • Uses the standardized MCP protocol via the @modelcontextprotocol/sdk library
  • Supports multiple transport mechanisms (StdioClientTransport and SSEClientTransport)
  • Validates arguments using Zod schema validation on both client and server sides
  • Processes multiple response content types: text, image, and resource references
  • Manages server lifecycle with automatic restarts when server code changes
  • Provides an "always allow" mechanism to bypass approval for trusted tools
  • Works with the companion access_mcp_resource tool for resource retrieval
  • Maintains proper error tracking and handling for failed operations
  • Supports configurable timeouts (1-3600 seconds, default: 60 seconds)
  • Allows file watchers to automatically detect and reload server changes

Limitations​

  • Depends on external MCP servers being available and connected
  • Limited to the tools provided by connected servers
  • Tool capabilities vary between different MCP servers
  • Network issues can affect reliability and performance
  • Requires user approval before execution (unless in the "always allow" list)
  • Cannot execute multiple MCP tool operations simultaneously

Server Configuration​

MCP servers can be configured globally or at the project level:

  • Global Configuration: Managed through the Roo Code extension settings in VS Code. These apply across all projects unless overridden.
  • Project-level Configuration: Defined in a .roo/mcp.json file within your project's root directory.
  • This allows project-specific server setups.
  • Project-level servers take precedence over global servers if they share the same name.
  • Since .roo/mcp.json can be committed to version control, it simplifies sharing configurations with your team.

How It Works​

When the use_mcp_tool tool is invoked, it follows this process:

  1. Initialization and Validation:

    • The system verifies that the MCP hub is available
    • Confirms the specified server exists and is connected
    • Validates the requested tool exists on the server
    • Arguments are validated against the tool's schema definition
    • Timeout settings are extracted from server configuration (default: 60 seconds)

  2. Execution and Communication:

    • The system selects the appropriate transport mechanism:
      • StdioClientTransport: For communicating with local processes via standard I/O
      • SSEClientTransport: For communicating with HTTP servers via Server-Sent Events
    • A request is sent with validated server name, tool name, and arguments
    • Communication uses the @modelcontextprotocol/sdk library for standardized interactions
    • Request execution is tracked with timeout handling to prevent hanging operations

  3. Response Processing:

    • Responses can include multiple content types:
      • Text content: Plain text responses
      • Image content: Binary image data with MIME type information
      • Resource references: URIs to access server resources (works with access_mcp_resource)
    • The system checks the isError flag to determine if error handling is needed
    • Results are formatted for display in the Roo interface

  4. Resource and Error Handling:

    • The system uses WeakRef patterns to prevent memory leaks
    • A consecutive mistake counter tracks and manages errors
    • File watchers monitor for server code changes and trigger automatic restarts
    • The security model requires approval for tool execution unless in the "always allow" list

Security and Permissions​

The MCP architecture provides several security features:

  • Users must approve tool usage before execution (by default)
  • Specific tools can be marked for automatic approval in the "always allow" list
  • Server configurations are validated with Zod schemas for integrity
  • Configurable timeouts prevent hanging operations (1-3600 seconds)
  • Server connections can be enabled or disabled through the UI

Examples When Used​

  • Analyzing specialized data formats using server-side processing tools
  • Generating images or other media through AI models hosted on external servers
  • Executing complex domain-specific calculations without local implementation
  • Accessing proprietary APIs or services through a controlled interface
  • Retrieving data from specialized databases or data sources

Usage Examples​

Requesting weather forecast data with text response:

<use_mcp_tool>
<server_name>weather-server</server_name>
<tool_name>get_forecast</tool_name>
<arguments>
{
  "city": "San Francisco",
  "days": 5,
  "format": "text"
}
</arguments>
</use_mcp_tool>

Analyzing source code with a specialized tool that returns JSON:

<use_mcp_tool>
<server_name>code-analysis</server_name>
<tool_name>complexity_metrics</tool_name>
<arguments>
{
  "language": "typescript",
  "file_path": "src/app.ts",
  "include_functions": true,
  "metrics": ["cyclomatic", "cognitive"]
}
</arguments>
</use_mcp_tool>

Generating an image with specific parameters:

<use_mcp_tool>
<server_name>image-generation</server_name>
<tool_name>create_image</tool_name>
<arguments>
{
  "prompt": "A futuristic city with flying cars",
  "style": "photorealistic",
  "dimensions": {
    "width": 1024,
    "height": 768
  },
  "format": "webp"
}
</arguments>
</use_mcp_tool>

Accessing a resource through a tool that returns a resource reference:

<use_mcp_tool>
<server_name>database-connector</server_name>
<tool_name>query_and_store</tool_name>
<arguments>
{
  "database": "users",
  "type": "select",
  "fields": ["name", "email", "last_login"],
  "where": {
    "status": "active"
  },
  "store_as": "active_users"
}
</arguments>
</use_mcp_tool>

Tool with no required arguments:

<use_mcp_tool>
<server_name>system-monitor</server_name>
<tool_name>get_current_status</tool_name>
<arguments>
{}
</arguments>
</use_mcp_tool>
Is this documentation incorrect or incomplete? Report an issue on GitHub