meta-mcp server guide

Overview

The meta-mcp server acts as an intelligent intermediary between AI clients and multiple MCP servers. It provides semantic tool discovery, unified access to multiple MCP servers through a single endpoint, and intelligent routing of requests to appropriate MCP tools.

Key features include:

• Semantic Tool Discovery: Uses embeddings and hybrid search (semantic + BM25) to find the right tools for your tasks
• Unified Access: Single endpoint to access all your MCP servers without managing multiple connections
• Tool Management: Seamlessly manage large numbers of MCP tools across different servers
• Intelligent Routing: Automatically routes requests to the appropriate MCP server based on tool requirements

The meta-mcp server is developed by StacklokLabs and requires Python 3.13+.

Metadata

Expand to view the MCP server's metadata

Server metadata

Name: meta-mcp
Type: container
Description: MCP server that acts as an intelligent intermediary between AI clients and multiple MCP servers
Tier: Official
Status: Active
Transport: streamable-http
Image: ghcr.io/stackloklabs/meta-mcp:latest
Has Provenance: Yes

Permissions:
  Network:
Repository URL: https://github.com/StacklokLabs/meta-mcp
Popularity: 0 stars, 0 pulls
Last Updated: 2025-09-15T08:11:53Z

Tools:
  - find_tool
  - call_tool

Tags:
  mcp, proxy, gateway, intelligent

Example Command:
  thv run meta-mcp

Usage

UI

Prerequisites

• ToolHive UI (version >= 0.6.0) must be running
• ToolHive CLI (version >= 0.3.1)

1. Create a dedicated group for meta-mcp:

   Navigate to the Groups section and create a new group called meta. This ensures that AI clients are configured with only the meta-mcp server while other MCP servers remain available but not directly configured in clients.

2. Install meta-mcp in the dedicated group:

   In the UI, select the meta group and add the meta-mcp server from the registry.

3. Configure your AI client:

   Use the client configuration feature in the UI to register your AI client (like Cursor or Claude Desktop) with the meta group only.

4. Add other MCP servers to the default group:

   Install other MCP servers you want to access through meta-mcp in the default group. These will be discovered automatically by meta-mcp.

CLI

Prerequisites

• ToolHive UI (version >= 0.6.0) must be running for setup
• ToolHive CLI (version >= 0.3.1)

Step 1: Create a dedicated group and run meta-mcp

# Create the meta group
thv group create meta

# Run meta-mcp in the dedicated group
thv run --group meta meta-mcp

Step 2: Configure your AI client for the meta group

# Register your AI client with the meta group
# Examples for different clients:
thv client register cursor --group meta
thv client register claude-desktop --group meta

# Verify the configuration
thv client list-registered

Step 3: Add MCP servers to the default group

# Add MCP servers that you want to access through meta-mcp
thv run github
thv run filesystem
thv run time

# Verify the configuration - meta-mcp should be in 'meta' group, others in 'default'
thv ls

Advanced Usage: Custom configuration

If you need custom configuration for meta-mcp, you can specify environment variables:

# Run with custom ToolHive connection settings
TOOLHIVE_HOST=localhost TOOLHIVE_PORT=8080 thv run --group meta meta-mcp

# Run with custom polling interval (default: 60 seconds)
thv run --group meta --env POLLING_INTERVAL=30 meta-mcp

Kubernetes

meta-mcp.yaml

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServer
metadata:
  name: meta-mcp
  namespace: toolhive-system
  labels:
    app.kubernetes.io/name: meta-mcp
spec:
  name: meta-mcp
  registry: stacklok
  group: meta
  env:
    - name: TOOLHIVE_HOST
      value: "toolhive-api-server"
    - name: TOOLHIVE_PORT
      value: "8080"
    - name: POLLING_INTERVAL
      value: "60"

Apply the configuration:

kubectl apply -f meta-mcp.yaml

Then configure other MCP servers in the default group:

other-mcp-servers.yaml

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServer
metadata:
  name: github
spec:
  name: github
  registry: stacklok
  # group defaults to "default" if not specified
---
apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServer
metadata:
  name: filesystem
spec:
  name: filesystem
  registry: stacklok

Sample prompts

Once meta-mcp is configured and running, you can use it with natural language prompts. The server will automatically discover and route to appropriate tools:

Direct Task Examples:

• "Get the details of GitHub issue 1911 from stacklok/toolhive repo"
• "List recent PRs from stacklok/toolhive repo"

The meta-mcp workflow:

1. Your AI client sends the request to meta-mcp
2. Meta-mcp uses hybrid semantic and keyword search to find relevant tools across all connected MCP servers
3. Meta-mcp server returns the short list of matching tools to the client
4. Client selects one tool from the short list and uses meta-mcp to call that tool
5. Results are returned from meta-mcp to the client

Available tools

The meta-mcp server provides two main tools:

find_tool

Discovers available tools that match your requirements using hybrid semantic and keyword search.

Parameters:

• tool_description: Description of the task or capability needed (e.g., "web search", "analyze CSV file")
• tool_keywords: Space-separated keywords of the task or capability needed (e.g., "list issues github", "SQL query postgres")

call_tool

Executes a specific tool with provided parameters after discovery.

Parameters:

• server_name: Name of the MCP server providing the tool
• tool_name: Name of the tool to execute
• parameters: Dictionary of arguments required by the tool

Recommended practices

• Use descriptive group names: Keep meta-mcp in a dedicated group to maintain clean client configurations
• Regular updates: Keep both ToolHive and meta-mcp updated for the latest features and compatibility

Best Practice

Start with a small set of MCP servers in the default group and gradually add more as you become familiar with meta-mcp's tool discovery capabilities. This makes it easier to understand which tools are being used for different tasks.