> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcphub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart Routing

> AI-powered tool discovery using vector semantic search

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

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:

<Tabs>
  <Tab title="HTTP MCP">
    ```
    # Search across all servers
    http://localhost:3000/mcp/$smart

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

  <Tab title="SSE (Legacy)">
    ```
    # Search across all servers
    http://localhost:3000/sse/$smart

    # Search within a specific group
    http://localhost:3000/sse/$smart/{group}
    ```
  </Tab>
</Tabs>

### Group-Scoped Smart Routing

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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Example: Environment-Based Groups">
    Create groups for different environments:

    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion title="Example: Team-Based Groups">
    Organize tools by team or department:

    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion title="How It Works">
    When using `$smart/{group}`:

    1. The system identifies the specified group
    2. Retrieves all servers belonging to that group
    3. Filters the tool search to only those servers
    4. Returns results scoped to the group's servers

    If the group doesn't exist or has no servers, the search will return no results.
  </Accordion>
</AccordionGroup>

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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Enabling Progressive Disclosure">
    Enable Progressive Disclosure through the Settings page or environment variable:

    **Via Settings UI:**

    1. Navigate to Settings → Smart Routing
    2. Enable the "Progressive Disclosure" toggle
    3. The change takes effect immediately

    **Via Environment Variable:**

    ```bash theme={null}
    SMART_ROUTING_PROGRESSIVE_DISCLOSURE=true
    ```
  </Accordion>

  <Accordion title="Including Server Descriptions in search_tools">
    By default, `search_tools` lists only server names in its tool description. To include each server's description (or upstream instructions) alongside the name, set:

    ```bash theme={null}
    SMART_ROUTING_SERVER_DESCRIPTION_MODE=full
    ```

    Use `names` (default) to keep the legacy compact list.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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:**

    1. AI calls `search_tools` with query "file operations"
    2. Results show tool names and descriptions (minimal tokens)
    3. AI calls `describe_tool` for a specific tool to get full `inputSchema`
    4. AI calls `call_tool` with the correct arguments

    This mode reduces token usage by only fetching full schemas when needed.
  </Accordion>

  <Accordion title="Response Format Comparison">
    **Standard Mode search\_tools response:**

    ```json theme={null}
    {
      "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:**

    ```json theme={null}
    {
      "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:**

    ```json theme={null}
    {
      "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"]
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

{/* ### Advanced Queries

Smart Routing supports various query types:

<AccordionGroup>
<Accordion title="Task-Based Queries">
  ```bash
  # What you want to accomplish
  curl -X POST http://localhost:3000/mcp/$smart \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/search",
      "params": {
        "query": "send a message to a slack channel"
      }
    }'
  ```
</Accordion>

<Accordion title="Domain-Specific Queries">
  ```bash
  # Specific domain or technology
  curl -X POST http://localhost:3000/mcp/$smart \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/search",
      "params": {
        "query": "database operations SQL queries"
      }
    }'
  ```
</Accordion>

<Accordion title="Action-Oriented Queries">
  ```bash
  # Specific actions
  curl -X POST http://localhost:3000/mcp/$smart \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/search",
      "params": {
        "query": "create file upload to github repository"
      }
    }'
  ```
</Accordion>

<Accordion title="Context-Aware Queries">
  ```bash
  # Include context for better results
  curl -X POST http://localhost:3000/mcp/$smart \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/search",
      "params": {
        "query": "automated testing web application",
        "context": {
          "project": "e-commerce website",
          "technologies": ["React", "Node.js"],
          "environment": "staging"
        }
      }
    }'
  ```
</Accordion>
</AccordionGroup> */}

{/* ## Performance Optimization

### Embedding Cache

Smart Routing caches embeddings to improve performance:

```bash
# Configure cache settings
EMBEDDING_CACHE_TTL=3600        # Cache for 1 hour
EMBEDDING_CACHE_SIZE=10000      # Cache up to 10k embeddings
EMBEDDING_CACHE_CLEANUP=300     # Cleanup every 5 minutes
```

### Batch Processing

Tools are indexed in batches for efficiency:

```bash
# Batch size for embedding generation
EMBEDDING_BATCH_SIZE=100

# Concurrent embedding requests
EMBEDDING_CONCURRENCY=5

# Index update frequency
INDEX_UPDATE_INTERVAL=3600      # Re-index every hour
```

### Database Optimization

Optimize PostgreSQL for vector operations:

```sql
-- Create indexes for better performance
CREATE INDEX ON tool_embeddings USING hnsw (embedding vector_cosine_ops);

-- Adjust PostgreSQL settings
ALTER SYSTEM SET shared_preload_libraries = 'vector';
ALTER SYSTEM SET max_connections = 200;
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET effective_cache_size = '1GB';
```

## Monitoring and Analytics

### Smart Routing Metrics

Monitor Smart Routing performance:

```bash
# Get Smart Routing statistics
curl http://localhost:3000/api/smart-routing/stats \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
```

Response includes:

- Query count and frequency
- Average response time
- Embedding cache hit rate
- Most popular tools
- Query patterns

### Tool Usage Analytics

Track which tools are found and used:

```bash
# Get tool usage analytics
curl http://localhost:3000/api/smart-routing/analytics \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
```

Metrics include:

- Tool discovery rates
- Execution success rates
- User satisfaction scores
- Query-to-execution conversion

### Performance Monitoring

Monitor system performance:

```bash
# Database performance
curl http://localhost:3000/api/smart-routing/db-stats \
-H "Authorization: Bearer YOUR_JWT_TOKEN"

# Embedding service status
curl http://localhost:3000/api/smart-routing/embedding-stats \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## Advanced Features

### Custom Embeddings

Use custom embedding models:

```bash
# Hugging Face models
EMBEDDING_SERVICE=huggingface
HUGGINGFACE_MODEL=sentence-transformers/all-MiniLM-L6-v2
HUGGINGFACE_API_KEY=your_api_key

# Local embedding service
EMBEDDING_SERVICE=local
EMBEDDING_SERVICE_URL=http://localhost:8080/embeddings
```

### Query Enhancement

Enhance queries for better results:

```json
{
"queryEnhancement": {
  "enabled": true,
  "expandAcronyms": true,
  "addSynonyms": true,
  "contextualExpansion": true
}
}
```

### Result Filtering

Filter results based on criteria:

```json
{
"resultFiltering": {
  "minRelevanceScore": 0.7,
  "maxResults": 10,
  "preferredServers": ["fetch", "playwright"],
  "excludeServers": ["deprecated-server"]
}
}
```

### Feedback Learning

Improve results based on user feedback:

```bash
# Provide feedback on search results
curl -X POST http://localhost:3000/api/smart-routing/feedback \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d '{
  "queryId": "search-123",
  "toolName": "fetch_html",
  "rating": 5,
  "successful": true,
  "comments": "Perfect tool for the task"
}'
``` */}

## Troubleshooting

<AccordionGroup>
  <Accordion title="Database Connection Issues">
    **Symptoms:**

    * Smart Routing not available
    * Database connection errors
    * Embedding storage failures

    **Solutions:**

    1. Verify PostgreSQL is running
    2. Check DB\_URL format
    3. Ensure pgvector extension is installed
    4. Test connection manually:

    ```bash theme={null}
    psql $DB_URL -c "SELECT 1;"
    ```
  </Accordion>

  <Accordion title="Embedding Service Problems">
    **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:

    ```bash theme={null}
    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"}'
    ```
  </Accordion>

  <Accordion title="Poor Search Results">
    **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

    ```bash theme={null}
    # Re-index all tools
    curl -X POST http://localhost:3000/api/smart-routing/reindex \
      -H "Authorization: Bearer YOUR_JWT_TOKEN"
    ```
  </Accordion>

  <Accordion title="Performance Issues">
    **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

    ```bash theme={null}
    # Check system performance
    curl http://localhost:3000/api/smart-routing/performance \
      -H "Authorization: Bearer YOUR_JWT_TOKEN"
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

### Query Writing

<Tip>
  **Be Descriptive**: Use specific, descriptive language in queries for better tool matching.
</Tip>

<Tip>
  **Include Context**: Provide relevant context about your task or domain for more accurate results.
</Tip>

<Tip>**Use Natural Language**: Write queries as you would describe the task to a human.</Tip>

### Tool Descriptions

<Warning>
  **Quality Metadata**: Ensure MCP servers provide high-quality tool descriptions and metadata.
</Warning>

<Warning>**Regular Updates**: Keep tool descriptions current as functionality evolves.</Warning>

<Warning>
  **Consistent Naming**: Use consistent naming conventions across tools and servers.
</Warning>

### System Maintenance

<Info>**Regular Re-indexing**: Periodically re-index tools to ensure embedding quality.</Info>

<Info>**Monitor Performance**: Track query patterns and optimize based on usage.</Info>

<Info>
  **Update Models**: Consider updating to newer embedding models as they become available.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield" href="/features/authentication">
    User management and access control
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/features/monitoring">
    System monitoring and analytics
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/smart-routing">
    Complete Smart Routing API documentation
  </Card>

  <Card title="Configuration" icon="cog" href="/configuration/environment-variables">
    Advanced configuration options
  </Card>
</CardGroup>