plano/docs/MCP_QUICK_START.md

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:

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:

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

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:

# 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
• RAG Agent Demo
• Agent Configuration Reference