Smart Routing

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

2. Semantic Search

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

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

Using Smart Routing

Smart Routing Endpoint

Access Smart Routing through the special $smart endpoint:

HTTP MCP
SSE (Legacy)

# Search across all servers
http://localhost:3000/mcp/$smart

# Search within a specific group
http://localhost:3000/mcp/$smart/{group}

# Search across all servers
http://localhost:3000/sse/$smart

# Search within a specific group
http://localhost:3000/sse/$smart/{group}

Group-Scoped Smart Routing

Smart Routing now supports group-scoped searches, allowing you to limit tool discovery to servers within a specific group:

Using Group-Scoped Smart Routing

Connect your AI client to a group-specific Smart Routing endpoint:

http://localhost:3000/mcp/$smart/production

This endpoint will only search for tools within servers that belong to the “production” group.Benefits:

Focused Results: Only tools from relevant servers are returned
Better Performance: Reduced search space for faster queries
Environment Isolation: Keep development, staging, and production tools separate
Access Control: Limit tool discovery based on user permissions

Example: Environment-Based Groups

Create groups for different environments:

# Development environment
http://localhost:3000/mcp/$smart/development

# Staging environment
http://localhost:3000/mcp/$smart/staging

# Production environment
http://localhost:3000/mcp/$smart/production

Each endpoint will only return tools from servers in that specific environment group.

Example: Team-Based Groups

Organize tools by team or department:

# Backend team tools
http://localhost:3000/mcp/$smart/backend-team

# Frontend team tools
http://localhost:3000/mcp/$smart/frontend-team

# DevOps team tools
http://localhost:3000/mcp/$smart/devops-team

This enables teams to have focused access to their relevant toolsets.

How It Works

When using $smart/{group}:

The system identifies the specified group
Retrieves all servers belonging to that group
Filters the tool search to only those servers
Returns results scoped to the group’s servers

If the group doesn’t exist or has no servers, the search will return no results.

Progressive Disclosure Mode

Progressive Disclosure is an optimization feature that reduces token usage when working with Smart Routing. When enabled, the tool discovery workflow changes from a 2-step to a 3-step process.

What is Progressive Disclosure?

By default, Smart Routing returns full tool information including complete parameter schemas in search_tools results. This can consume significant tokens when dealing with tools that have complex input schemas.Progressive Disclosure changes this behavior:

search_tools returns only tool names and descriptions (minimal info)
A new describe_tool endpoint provides full parameter schema on demand
call_tool executes the tool as before

This approach is particularly useful when:

Working with many tools with complex schemas
Token usage optimization is important
AI clients need to browse many tools before selecting one

Enabling Progressive Disclosure

Enable Progressive Disclosure through the Settings page or environment variable:Via Settings UI:

Navigate to Settings → Smart Routing
Enable the “Progressive Disclosure” toggle
The change takes effect immediately

Via Environment Variable:

SMART_ROUTING_PROGRESSIVE_DISCLOSURE=true

Standard Mode (Default)

When Progressive Disclosure is disabled (default), Smart Routing provides two tools:Workflow: search_tools → call_tool

Tool	Purpose
`search_tools`	Find tools by query, returns full tool info including `inputSchema`
`call_tool`	Execute a tool with the provided arguments

This mode is simpler but uses more tokens due to full schemas in search results.

Progressive Disclosure Mode

When Progressive Disclosure is enabled, Smart Routing provides three tools:Workflow: search_tools → describe_tool → call_tool

Tool	Purpose
`search_tools`	Find tools by query, returns only name and description
`describe_tool`	Get full schema for a specific tool (new)
`call_tool`	Execute a tool with the provided arguments

Example workflow:

AI calls search_tools with query “file operations”
Results show tool names and descriptions (minimal tokens)
AI calls describe_tool for a specific tool to get full inputSchema
AI calls call_tool with the correct arguments

This mode reduces token usage by only fetching full schemas when needed.

Response Format Comparison

Standard Mode search_tools response:

{
  "tools": [
    {
      "name": "read_file",
      "description": "Read contents of a file",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": { "type": "string", "description": "File path to read" },
          "encoding": { "type": "string", "default": "utf-8" }
        },
        "required": ["path"]
      }
    }
  ]
}

Progressive Disclosure Mode search_tools response:

{
  "tools": [
    {
      "name": "read_file",
      "description": "Read contents of a file"
    }
  ],
  "metadata": {
    "progressiveDisclosure": true,
    "guideline": "Use describe_tool to get the full parameter schema before calling."
  }
}

describe_tool response:

{
  "tool": {
    "name": "read_file",
    "description": "Read contents of a file",
    "inputSchema": {
      "type": "object",
      "properties": {
        "path": { "type": "string", "description": "File path to read" },
        "encoding": { "type": "string", "default": "utf-8" }
      },
      "required": ["path"]
    }
  }
}

Troubleshooting

Database Connection Issues

Symptoms:

Smart Routing not available
Database connection errors
Embedding storage failures

Solutions:

Verify PostgreSQL is running
Check DB_URL format
Ensure pgvector extension is installed
Test connection manually:

psql $DB_URL -c "SELECT 1;"

Embedding Service Problems

Symptoms:

Tool indexing failures
Query processing errors
API rate limit errors

Solutions:

Verify API key validity
Check network connectivity
Monitor rate limits
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"}'

Poor Search Results

Symptoms:

Irrelevant tools returned
Low relevance scores
Missing expected tools

Solutions:

Adjust similarity threshold
Re-index tools with better descriptions
Use more specific queries
Check tool metadata quality

# Re-index all tools
curl -X POST http://localhost:3000/api/smart-routing/reindex \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Performance Issues

Symptoms:

Slow query responses
High database load
Memory usage spikes

Solutions:

Optimize database configuration
Increase cache sizes
Reduce batch sizes
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

Get Started

Core Features

Configuration

Overview

How Smart Routing Works

1. Tool Indexing

2. Semantic Search

3. Intelligent Filtering

4. Tool Execution

Prerequisites

Required Components

Using Smart Routing

Smart Routing Endpoint

Group-Scoped Smart Routing

Progressive Disclosure Mode

Troubleshooting

Best Practices

Query Writing

Tool Descriptions

System Maintenance

Next Steps

Authentication

Monitoring

API Reference

Configuration

Get Started

Core Features

Configuration

​Overview

​How Smart Routing Works

​1. Tool Indexing

​2. Semantic Search

​3. Intelligent Filtering

​4. Tool Execution

​Prerequisites

​Required Components

​Using Smart Routing

​Smart Routing Endpoint

​Group-Scoped Smart Routing

​Progressive Disclosure Mode

​Troubleshooting

​Best Practices

​Query Writing

​Tool Descriptions

​System Maintenance

​Next Steps

Authentication

Monitoring

API Reference

Configuration

Overview

How Smart Routing Works

1. Tool Indexing

2. Semantic Search

3. Intelligent Filtering

4. Tool Execution

Prerequisites

Required Components

Using Smart Routing

Smart Routing Endpoint

Group-Scoped Smart Routing

Progressive Disclosure Mode

Troubleshooting

Best Practices

Query Writing

Tool Descriptions

System Maintenance

Next Steps