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,236 @@
+---
+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 Stacklok 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 ToolHive 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 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
+
+:::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. :::