mirror of
https://github.com/katanemo/plano.git
synced 2026-06-17 15:25:17 +02:00
132 lines
3.6 KiB
Markdown
132 lines
3.6 KiB
Markdown
# MCP Agent Description - Quick Start
|
|
|
|
## What This Feature Does
|
|
|
|
When processing agent filter chains in Brightstaff, the system can now automatically fetch tool descriptions from MCP (Model Context Protocol) endpoints. These descriptions are used by the LLM router to intelligently select the appropriate agent for handling user requests.
|
|
|
|
## Configuration
|
|
|
|
### Basic Setup
|
|
|
|
Add agents with MCP URLs to your `arch_config.yaml`:
|
|
|
|
```yaml
|
|
agents:
|
|
- id: rag_agent
|
|
url: mcp://host.docker.internal:10501
|
|
|
|
- id: query_rewriter
|
|
url: mcp://host.docker.internal:10500
|
|
tool: rewrite_query_with_archgw # Optional: specify tool name
|
|
|
|
listeners:
|
|
- type: agent
|
|
port: 8001
|
|
router: arch_agent_router
|
|
agents:
|
|
- id: rag_agent
|
|
description: "RAG agent for document retrieval" # Fallback if MCP fails
|
|
filter_chain:
|
|
- query_rewriter
|
|
```
|
|
|
|
### MCP URL Formats
|
|
|
|
Three formats are supported:
|
|
|
|
```yaml
|
|
# 1. Basic - uses agent id as tool name
|
|
url: mcp://localhost:10500
|
|
|
|
# 2. Tool in path
|
|
url: mcp://localhost:10500/my_tool_name
|
|
|
|
# 3. Tool as query parameter
|
|
url: mcp://localhost:10500?tool=my_tool_name
|
|
```
|
|
|
|
## How It Works
|
|
|
|
1. **Request arrives** at agent listener
|
|
2. **Agent selector** needs to choose which agent to handle request
|
|
3. **For MCP agents**, description is fetched from endpoint:
|
|
```
|
|
GET http://host:port/sse/tools/list
|
|
Accept: text/event-stream
|
|
```
|
|
4. **Tool description extracted** from SSE response
|
|
5. **LLM router uses descriptions** to select best agent
|
|
6. **Selected agent processes** the request through its filter chain
|
|
|
|
## Example MCP Response
|
|
|
|
Your MCP server should respond to `/sse/tools/list` with:
|
|
|
|
```
|
|
data: {"tools": [{"name": "rewrite_query_with_archgw", "description": "Rewrites user queries using LLM for better retrieval", "inputSchema": {...}}]}
|
|
```
|
|
|
|
## Fallback Behavior
|
|
|
|
If MCP endpoint fails or returns empty description:
|
|
- System logs a warning
|
|
- Falls back to `description` field from arch_config.yaml
|
|
- Processing continues normally
|
|
|
|
## Logging
|
|
|
|
Enable debug logging to see MCP interactions:
|
|
|
|
```bash
|
|
RUST_LOG=debug cargo run
|
|
```
|
|
|
|
Look for logs like:
|
|
```
|
|
Agent rag_agent is an MCP agent, fetching tool description from: mcp://host.docker.internal:10501
|
|
Fetched MCP description for agent rag_agent: Rewrites user queries...
|
|
```
|
|
|
|
## Testing
|
|
|
|
Test your MCP endpoint manually:
|
|
|
|
```bash
|
|
# Check if endpoint is accessible
|
|
curl -H "Accept: text/event-stream" http://localhost:10500/sse/tools/list
|
|
|
|
# Expected response format
|
|
data: {"tools": [{"name": "my_tool", "description": "My tool description"}]}
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Failed to fetch MCP description"
|
|
- Check if MCP server is running
|
|
- Verify URL format is correct
|
|
- Ensure `/sse/tools/list` endpoint exists
|
|
- Check network connectivity
|
|
|
|
### "MCP tool description is empty"
|
|
- Verify MCP server returns tool in response
|
|
- Check tool name matches configuration
|
|
- Ensure `description` field is populated in MCP response
|
|
|
|
### "Tool not found"
|
|
- Verify tool name in config matches MCP server
|
|
- Check if tool is listed in `/sse/tools/list` response
|
|
- Try without explicit tool name (uses agent id)
|
|
|
|
## Best Practices
|
|
|
|
1. **Always provide fallback descriptions** in arch_config.yaml
|
|
2. **Use descriptive tool names** that match your config
|
|
3. **Keep MCP servers running** before starting Brightstaff
|
|
4. **Monitor logs** for MCP fetch failures
|
|
5. **Test MCP endpoints** independently before integration
|
|
|
|
## See Also
|
|
|
|
- [MCP Agent Integration Documentation](./MCP_AGENT_INTEGRATION.md)
|
|
- [RAG Agent Demo](../demos/use_cases/rag_agent/README.md)
|
|
- [Agent Configuration Reference](../demos/use_cases/rag_agent/arch_config.yaml)
|