Add comprehensive usage guide for meta-mcp MCP server

This guide documents how to use the meta-mcp server with ToolHive for intelligent tool discovery and unified access to multiple MCP servers. Includes setup instructions along with practical examples and best practices.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: ptelang

docs/toolhive/guides-mcp/meta-mcp.mdx

@@ -0,0 +1,205 @@
+---
+title: meta-mcp server guide
+sidebar_label: meta-mcp
+description: Using the meta-mcp server with ToolHive for intelligent tool discovery and unified MCP server access.
+last_update:
+  author: stacklok-claude
+  date: 2025-09-18
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import MCPMetadata from '@site/src/components/MCPMetadata';
+
+## 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](https://github.com/StacklokLabs/meta-mcp) and requires Python 3.13+.
+
+## Metadata
+
+<MCPMetadata name='meta-mcp' />
+
+## Usage
+
+<Tabs groupId='mode' queryString='mode'>
+<TabItem value='ui' label='UI' default>
+
+:::info[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.
+
+</TabItem>
+<TabItem value='cli' label='CLI'>
+
+:::info[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**
+
+```bash
+# 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**
+
+```bash
+# 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**
+
+```bash
+# 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:
+
+```bash
+# 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
+```
+
+</TabItem>
+<TabItem value='k8s' label='Kubernetes'>
+
+```yaml title="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:
+
+```bash
+kubectl apply -f meta-mcp.yaml
+```
+
+Then configure other MCP servers in the default group:
+
+```yaml title="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
+```
+
+</TabItem>
+</Tabs>
+
+## 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 form the short list and uses meta-mcp to call that tool
+4. 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
+
+:::tip[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.
+:::