From bdba60df4967942025e6879898391e321fc54bea Mon Sep 17 00:00:00 2001 From: Pankaj Telang Date: Thu, 16 Oct 2025 13:02:51 -0400 Subject: [PATCH 1/4] Updated meta-mcp doc with the latest features --- docs/toolhive/guides-mcp/meta-mcp.mdx | 90 ++++++++++++++++++++++++--- 1 file changed, 82 insertions(+), 8 deletions(-) diff --git a/docs/toolhive/guides-mcp/meta-mcp.mdx b/docs/toolhive/guides-mcp/meta-mcp.mdx index 829ae80a..5dd6fe47 100644 --- a/docs/toolhive/guides-mcp/meta-mcp.mdx +++ b/docs/toolhive/guides-mcp/meta-mcp.mdx @@ -13,8 +13,10 @@ last_update: The meta-mcp server acts as an intelligent intermediary between AI clients and multiple MCP servers. It provides tool discovery, unified access to multiple MCP -servers through a single endpoint, and intelligent routing of requests to -appropriate MCP tools. +servers through a single endpoint, and routing of requests to the MCP servers. +When a required MCP server isn't installed, meta-mcp automatically searches the +ToolHive registry and dynamically installs the necessary server to complete the +task. :::info[Status] @@ -31,29 +33,48 @@ Key features include: 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 +- **Intelligent routing**: Routes requests to the requested MCP server and tool +- **Dynamic Server Installation**: Automatically discovers and installs missing + MCP servers from the ToolHive registry when needed for a task This approach helps you avoid problems associated with context overload and tool confusion by narrowing down the toolset to only those relevant for a given task. It also simplifies client configurations by providing a single access point to multiple MCP servers. -The meta-mcp workflow: +The meta-mcp workflow when relevant MCP server is installed: 1. Your AI client sends the request to meta-mcp 2. Meta-mcp uses hybrid search (semantic + keyword) to find relevant tools - across all connected MCP servers + across all installed 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 +The meta-mcp workflow when relevant MCP server is not installed: + +1. Your AI client sends the request to meta-mcp +2. Meta-mcp uses hybrid search (semantic + keyword) to find tools across all + installed MCP servers +3. Meta-mcp server returns the short list of matching tools to the client +4. AI client finds that none of the tools are suitable for the request +5. AI client sends a request to search the ToolHive registry for relevant + servers +6. Meta-mcp uses hybrid search (semantic + keyword) to find relevant servers +7. Meta-mcp server returns the short list of matching servers to the client +8. AI client requests installation of a MCP server +9. Meta-mcp server installs the MCP server automatically if no security + credentials are needed. If security credentials are needed, meta-mcp server + guides the user to ToolHive for entering the credentials +10. After installation, the flow is identical to the flow when a MCP server is + installed. + ## Metadata -## Usage +## Usage on local machine The meta-mcp server is specifically designed to work with [ToolHive groups](../guides-cli/group-management.md). The recommended setup is @@ -109,8 +130,12 @@ depends on the UI's API server for tool discovery and management. # Create the meta group thv group create meta -# Run meta-mcp in the dedicated group +# Run meta-mcp in the dedicated group with access to server from all groups thv run --group meta meta-mcp + +# Alternately, run meta-mcp in the dedicated group with access to servers +# from the specified server groups +thv run --group meta meta-mcp --env ALLOWED_GROUPS="default,test" ``` **Step 2: Configure your AI client for the meta group** @@ -149,6 +174,12 @@ thv list +## Deployment in Kubernetes + +Meta-mcp is supported in Kubernetes enviornment. Follow +[this guide](https://github.com/StacklokLabs/meta-mcp/blob/main/docs/kubernetes-integration.md) +for deployment. + ## Sample prompts Once meta-mcp is configured and running, you can use the same prompts you would @@ -189,6 +220,49 @@ Executes a specific tool with provided parameters after discovery. - `tool_name`: Name of the tool to execute - `parameters`: Dictionary of arguments required by the tool +### `list_tools` + +List all available tools across all MCP servers. + +**Parameters** + +None + +### `search_registry` + +Search for tools in the ToolHive registry when find_tool doesn't return a +relevant tool. + +**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") + +### `install_server` + +Install and start an MCP server from the ToolHive registry. + +**Parameters:** + +- `server_name`: Name of the server from search_registry() results (found in the + mcp_server_name field) + +## Advanced configuration using environment variables + +Meta-mcp server can be configured using following enviornment variables. + +- MAX_TOOLS_TO_RETURN: Number of tools to return from find_tool (default: 8) +- TOOL_DISTANCE_THRESHOLD: Distance threshold for tool similarity (default: 1.0) +- MAX_TOOL_RESPONSE_TOKENS: Maximum number of tokens to return from call_tool + (default: None) +- WORKLOAD_POLLING_INTERVAL: Polling interval for running MCP servers (default: + 60 seconds) +- REGISTRY_POLLING_INTERVAL: Polling interval for ToolHive registry (default: 24 + hours) +- RUNTIME_MODE: Runtime mode for MCP servers: docker or k8s (default: docker) + ## Recommended practices - **Use descriptive group names**: Keep meta-mcp in a dedicated group to From 823faebd74636dba94bc010b4a662df72f484497 Mon Sep 17 00:00:00 2001 From: nigel brown Date: Fri, 17 Oct 2025 12:24:55 +0100 Subject: [PATCH 2/4] add k8s meta-mcp info --- docs/toolhive/guides-mcp/meta-mcp.mdx | 45 +++++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/docs/toolhive/guides-mcp/meta-mcp.mdx b/docs/toolhive/guides-mcp/meta-mcp.mdx index 5dd6fe47..152a2277 100644 --- a/docs/toolhive/guides-mcp/meta-mcp.mdx +++ b/docs/toolhive/guides-mcp/meta-mcp.mdx @@ -176,9 +176,48 @@ thv list ## Deployment in Kubernetes -Meta-mcp is supported in Kubernetes enviornment. Follow -[this guide](https://github.com/StacklokLabs/meta-mcp/blob/main/docs/kubernetes-integration.md) -for deployment. +Meta-mcp is supported in Kubernetes environment and can be deployed using Helm. + +**Prerequisites:** + +- Kubernetes cluster with ToolHive operator installed +- Helm 3.x installed +- Access to the `toolhive-system` namespace +- Cluster-admin privileges or permissions to create ClusterRoles and ClusterRoleBindings (only needed for initial installation; upgrades require fewer permissions if RBAC hasn't changed) + +**Installation:** + +Install meta-mcp using Helm: + +```bash +helm upgrade meta-mcp oci://ghcr.io/stackloklabs/meta-mcp/meta-mcp \ + --version 0.0.8 \ + -n toolhive-system \ + --install +``` + +:::tip[Other versions] + +Version 0.0.8 is shown above, but other versions are available. You can browse all available versions on the [meta-mcp releases page](https://github.com/StacklokLabs/meta-mcp/releases) or list them using: + +```bash +helm show chart oci://ghcr.io/stackloklabs/meta-mcp/meta-mcp --version 0.0.8 +``` + +::: + +This command will: +- Install meta-mcp in the `toolhive-system` namespace +- Create the necessary MCPServer custom resource +- Configure meta-mcp to work with the ToolHive operator + +**Verification:** + +Check that meta-mcp is running: + +```bash +kubectl get mcpserver -n toolhive-system +``` ## Sample prompts From 2c7d4bfdb7719fac5a051b083ee7b2e2adf50d72 Mon Sep 17 00:00:00 2001 From: nigel brown Date: Fri, 17 Oct 2025 12:28:39 +0100 Subject: [PATCH 3/4] Fix the order of statements --- docs/toolhive/guides-mcp/meta-mcp.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/toolhive/guides-mcp/meta-mcp.mdx b/docs/toolhive/guides-mcp/meta-mcp.mdx index 152a2277..53600785 100644 --- a/docs/toolhive/guides-mcp/meta-mcp.mdx +++ b/docs/toolhive/guides-mcp/meta-mcp.mdx @@ -196,6 +196,11 @@ helm upgrade meta-mcp oci://ghcr.io/stackloklabs/meta-mcp/meta-mcp \ --install ``` +This command will: +- Install meta-mcp in the `toolhive-system` namespace +- Create the necessary MCPServer custom resource +- Configure meta-mcp to work with the ToolHive operator + :::tip[Other versions] Version 0.0.8 is shown above, but other versions are available. You can browse all available versions on the [meta-mcp releases page](https://github.com/StacklokLabs/meta-mcp/releases) or list them using: @@ -206,11 +211,6 @@ helm show chart oci://ghcr.io/stackloklabs/meta-mcp/meta-mcp --version 0.0.8 ::: -This command will: -- Install meta-mcp in the `toolhive-system` namespace -- Create the necessary MCPServer custom resource -- Configure meta-mcp to work with the ToolHive operator - **Verification:** Check that meta-mcp is running: From 471e329977f1487eb1d6d7a8ec5b646ed59f40d9 Mon Sep 17 00:00:00 2001 From: nigel brown Date: Fri, 17 Oct 2025 12:39:11 +0100 Subject: [PATCH 4/4] Add a better list command (crane) --- docs/toolhive/guides-mcp/meta-mcp.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/toolhive/guides-mcp/meta-mcp.mdx b/docs/toolhive/guides-mcp/meta-mcp.mdx index 53600785..6fc10bee 100644 --- a/docs/toolhive/guides-mcp/meta-mcp.mdx +++ b/docs/toolhive/guides-mcp/meta-mcp.mdx @@ -206,7 +206,11 @@ This command will: Version 0.0.8 is shown above, but other versions are available. You can browse all available versions on the [meta-mcp releases page](https://github.com/StacklokLabs/meta-mcp/releases) or list them using: ```bash -helm show chart oci://ghcr.io/stackloklabs/meta-mcp/meta-mcp --version 0.0.8 +# macOS +brew install crane + +# Then list tags +crane ls ghcr.io/stackloklabs/meta-mcp/meta-mcp ``` :::