Skip to main content

Meta-mcp MCP server guide

Overview​

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

Status

The meta-mcp server is currently experimental. If you try it out, please share your feedback on the Stacklok Discord community.

Key features include:

  • Tool discovery: Uses hybrid search (semantic + keyword) 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: 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 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 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​

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-10-13T02:32:37Z

Tools:
  - find_tool
  - call_tool

Tags:
  mcp, proxy, gateway, intelligent

Example Command:
  thv run meta-mcp

Usage on local machine​

The meta-mcp server is specifically designed to work with ToolHive groups. The recommended setup is to run meta-mcp in its own dedicated group (e.g., "meta") and have other MCP servers in a separate group (e.g., "default"). This keeps client configurations clean and allows meta-mcp to discover and route to tools across all connected MCP servers.

Clients using meta-mcp should be configured to connect only to the meta group. The meta-mcp server discovers and routes requests to tools in the default group.

Prerequisites

You need both the ToolHive CLI and UI to use the meta-mcp server because it depends on the UI's API server for tool discovery and management.

  • ToolHive UI (version >= 0.6.0) must be running during setup and operation
  • 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 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

# Register your AI client with the meta group
thv client setup

# Verify the configuration
thv client list-registered
note

If your client was previously registered with the default group, unregister it. For example, to unregister Cursor:

thv client remove cursor --group default

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 fetch
thv run time

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

Deployment in Kubernetes​

Meta-mcp is supported in Kubernetes enviornment. Follow this guide for deployment.

Sample prompts​

Once meta-mcp is configured and running, you can use the same prompts you would normally use with individual MCP servers. The meta-mcp server automatically discovers and routes to appropriate tools.

Using the example MCP servers above, here are some sample prompts:

  • "Get the details of GitHub issue 1911 from the stacklok/toolhive repo"
  • "List recent PRs from the stacklok/toolhive repo"
  • "Fetch the latest news articles about AI"
  • "What is the current time in Tokyo?"

Available tools​

The meta-mcp server provides two tools of its own for tool discovery and execution.

find_tool​

Discovers available tools that match your requirements using hybrid search (semantic + keyword).

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

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)
  • 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.