Skip to content

Commit cedfaa8

Browse files
hannesrudolphhannesrudolph
committed
Add documentation for the use_mcp_tool and its functionality
1 parent fc019e5 commit cedfaa8

File tree

1 file changed

+178
-0
lines changed

1 file changed

+178
-0
lines changed

‎docs/features/tools/use-mcp-tool.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# use_mcp_tool
2+
3+
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.
4+
5+
## Parameters
6+
7+
The tool accepts these parameters:
8+
9+
- `server_name` (required): The name of the MCP server providing the tool
10+
- `tool_name` (required): The name of the tool to execute
11+
- `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.
12+
13+
## What It Does
14+
15+
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).
16+
17+
## When is it used?
18+
19+
- When specialized functionality not available in core tools is needed
20+
- When domain-specific operations are required
21+
- When integration with external systems or services is needed
22+
- When working with data that requires specific processing or analysis
23+
- When accessing proprietary tools through a standardized interface
24+
25+
## Key Features
26+
27+
- Uses the standardized MCP protocol via the `@modelcontextprotocol/sdk` library
28+
- Supports multiple transport mechanisms (StdioClientTransport and SSEClientTransport)
29+
- Validates arguments using Zod schema validation on both client and server sides
30+
- Processes multiple response content types: text, image, and resource references
31+
- Manages server lifecycle with automatic restarts when server code changes
32+
- Provides an "always allow" mechanism to bypass approval for trusted tools
33+
- Works with the companion `access_mcp_resource` tool for resource retrieval
34+
- Maintains proper error tracking and handling for failed operations
35+
- Supports configurable timeouts (1-3600 seconds, default: 60 seconds)
36+
- Allows file watchers to automatically detect and reload server changes
37+
38+
## Limitations
39+
40+
- Depends on external MCP servers being available and connected
41+
- Limited to the tools provided by connected servers
42+
- Tool capabilities vary between different MCP servers
43+
- Network issues can affect reliability and performance
44+
- Requires user approval before execution (unless in the "always allow" list)
45+
- Cannot execute multiple MCP tool operations simultaneously
46+
47+
## How It Works
48+
49+
When the `use_mcp_tool` tool is invoked, it follows this process:
50+
51+
1. **Initialization and Validation**:
52+
- The system verifies that the MCP hub is available
53+
- Confirms the specified server exists and is connected
54+
- Validates the requested tool exists on the server
55+
- Arguments are validated against the tool's schema definition
56+
- Timeout settings are extracted from server configuration (default: 60 seconds)
57+
58+
2. **Execution and Communication**:
59+
- The system selects the appropriate transport mechanism:
60+
- `StdioClientTransport`: For communicating with local processes via standard I/O
61+
- `SSEClientTransport`: For communicating with HTTP servers via Server-Sent Events
62+
- A request is sent with validated server name, tool name, and arguments
63+
- Communication uses the `@modelcontextprotocol/sdk` library for standardized interactions
64+
- Request execution is tracked with timeout handling to prevent hanging operations
65+
66+
3. **Response Processing**:
67+
- Responses can include multiple content types:
68+
- Text content: Plain text responses
69+
- Image content: Binary image data with MIME type information
70+
- Resource references: URIs to access server resources (works with `access_mcp_resource`)
71+
- The system checks the `isError` flag to determine if error handling is needed
72+
- Results are formatted for display in the Roo interface
73+
74+
4. **Resource and Error Handling**:
75+
- The system uses WeakRef patterns to prevent memory leaks
76+
- A consecutive mistake counter tracks and manages errors
77+
- File watchers monitor for server code changes and trigger automatic restarts
78+
- The security model requires approval for tool execution unless in the "always allow" list
79+
80+
## Security and Permissions
81+
82+
The MCP architecture provides several security features:
83+
84+
- Users must approve tool usage before execution (by default)
85+
- Specific tools can be marked for automatic approval in the "always allow" list
86+
- Server configurations are validated with Zod schemas for integrity
87+
- Configurable timeouts prevent hanging operations (1-3600 seconds)
88+
- Server connections can be enabled or disabled through the UI
89+
90+
## Examples When Used
91+
92+
- Analyzing specialized data formats using server-side processing tools
93+
- Generating images or other media through AI models hosted on external servers
94+
- Executing complex domain-specific calculations without local implementation
95+
- Accessing proprietary APIs or services through a controlled interface
96+
- Retrieving data from specialized databases or data sources
97+
98+
## Usage Examples
99+
100+
Requesting weather forecast data with text response:
101+
```
102+
<use_mcp_tool>
103+
<server_name>weather-server</server_name>
104+
<tool_name>get_forecast</tool_name>
105+
<arguments>
106+
{
107+
"city": "San Francisco",
108+
"days": 5,
109+
"format": "text"
110+
}
111+
</arguments>
112+
</use_mcp_tool>
113+
```
114+
115+
Analyzing source code with a specialized tool that returns JSON:
116+
```
117+
<use_mcp_tool>
118+
<server_name>code-analysis</server_name>
119+
<tool_name>complexity_metrics</tool_name>
120+
<arguments>
121+
{
122+
"language": "typescript",
123+
"file_path": "src/app.ts",
124+
"include_functions": true,
125+
"metrics": ["cyclomatic", "cognitive"]
126+
}
127+
</arguments>
128+
</use_mcp_tool>
129+
```
130+
131+
Generating an image with specific parameters:
132+
```
133+
<use_mcp_tool>
134+
<server_name>image-generation</server_name>
135+
<tool_name>create_image</tool_name>
136+
<arguments>
137+
{
138+
"prompt": "A futuristic city with flying cars",
139+
"style": "photorealistic",
140+
"dimensions": {
141+
"width": 1024,
142+
"height": 768
143+
},
144+
"format": "webp"
145+
}
146+
</arguments>
147+
</use_mcp_tool>
148+
```
149+
150+
Accessing a resource through a tool that returns a resource reference:
151+
```
152+
<use_mcp_tool>
153+
<server_name>database-connector</server_name>
154+
<tool_name>query_and_store</tool_name>
155+
<arguments>
156+
{
157+
"database": "users",
158+
"type": "select",
159+
"fields": ["name", "email", "last_login"],
160+
"where": {
161+
"status": "active"
162+
},
163+
"store_as": "active_users"
164+
}
165+
</arguments>
166+
</use_mcp_tool>
167+
```
168+
169+
Tool with no required arguments:
170+
```
171+
<use_mcp_tool>
172+
<server_name>system-monitor</server_name>
173+
<tool_name>get_current_status</tool_name>
174+
<arguments>
175+
{}
176+
</arguments>
177+
</use_mcp_tool>
178+
```

0 commit comments

Comments
 (0)