Skip to main content

​
Overview

Smart Routing is MCPHub’s intelligent tool discovery system that uses vector semantic search to automatically find the most relevant tools for any given task. Instead of manually specifying which tools to use, AI clients can describe what they want to accomplish, and Smart Routing will identify and provide access to the most appropriate tools.

​
How Smart Routing Works

​
1. Tool Indexing

When servers start up, Smart Routing automatically:
  • Discovers all available tools from MCP servers
  • Extracts tool metadata (names, descriptions, parameters)
  • Converts tool information to vector embeddings
  • Stores embeddings in PostgreSQL with pgvector
When a query is made:
  • User queries are converted to vector embeddings
  • Similarity search finds matching tools using cosine similarity
  • Dynamic thresholds filter out irrelevant results
  • Results are ranked by relevance score

​
3. Intelligent Filtering

Smart Routing applies several filters:
  • Relevance Threshold: Only returns tools above similarity threshold
  • Context Awareness: Considers conversation context
  • Tool Availability: Ensures tools are currently accessible
  • Permission Filtering: Respects user access permissions

​
4. Tool Execution

Found tools can be directly executed:
  • Parameter validation ensures correct tool usage
  • Error handling provides helpful feedback
  • Response formatting maintains consistency
  • Logging tracks tool usage for analytics

​
Prerequisites

Smart Routing requires additional setup compared to basic MCPHub usage:

​
Required Components

  1. PostgreSQL with pgvector: Vector database for embeddings storage
  2. Embedding Service: OpenAI API or compatible service
  3. Environment Configuration: Proper configuration variables

​
Using Smart Routing

​
Smart Routing Endpoint

Access Smart Routing through the special $smart endpoint:
  • HTTP MCP
  • SSE (Legacy)
http://localhost:3000/mcp/$smart

​
Troubleshooting

Symptoms:
  • Smart Routing not available
  • Database connection errors
  • Embedding storage failures
Solutions:
  1. Verify PostgreSQL is running
  2. Check DATABASE_URL format
  3. Ensure pgvector extension is installed
  4. Test connection manually:
psql $DATABASE_URL -c "SELECT 1;"
Symptoms:
  • Tool indexing failures
  • Query processing errors
  • API rate limit errors
Solutions:
  1. Verify API key validity
  2. Check network connectivity
  3. Monitor rate limits
  4. Test embedding service:
curl -X POST https://api.openai.com/v1/embeddings \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "test", "model": "text-embedding-3-small"}'
Symptoms:
  • Irrelevant tools returned
  • Low relevance scores
  • Missing expected tools
Solutions:
  1. Adjust similarity threshold
  2. Re-index tools with better descriptions
  3. Use more specific queries
  4. Check tool metadata quality
# Re-index all tools
curl -X POST http://localhost:3000/api/smart-routing/reindex \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Symptoms:
  • Slow query responses
  • High database load
  • Memory usage spikes
Solutions:
  1. Optimize database configuration
  2. Increase cache sizes
  3. Reduce batch sizes
  4. Monitor system resources
# Check system performance
curl http://localhost:3000/api/smart-routing/performance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Best Practices

​
Query Writing

Be Descriptive: Use specific, descriptive language in queries for better tool matching.
Include Context: Provide relevant context about your task or domain for more accurate results.
Use Natural Language: Write queries as you would describe the task to a human.

​
Tool Descriptions

Quality Metadata: Ensure MCP servers provide high-quality tool descriptions and metadata.
Regular Updates: Keep tool descriptions current as functionality evolves.
Consistent Naming: Use consistent naming conventions across tools and servers.

​
System Maintenance

Regular Re-indexing: Periodically re-index tools to ensure embedding quality.
Monitor Performance: Track query patterns and optimize based on usage.
Update Models: Consider updating to newer embedding models as they become available.

​
Next Steps

Authentication

User management and access control

Monitoring

System monitoring and analytics

API Reference

Complete Smart Routing API documentation

Configuration

Advanced configuration options
⌘I