Semantic Tool Search

When hundreds of tools are registered, finding the right one by name becomes impractical. The proxy can build an in-process vector index using chromem-go so MCP clients can search tools by natural-language description.

How it works

At startup the proxy embeds each tool's name, description, and parameter descriptions into a vector index. When an MCP client calls the synthetic search_tools tool with a query, the proxy performs a cosine-similarity search and returns the most relevant tool definitions — not results, just the schemas so the client can decide which tool to call next.

Configuration

search:
  enabled: true
  embedding:
    provider: openai               # openai | local
    model: text-embedding-3-small  # OpenAI embedding model
    api_key: ${OPENAI_API_KEY}
  top_k: 5                         # number of results to return

Local embeddings (no external API)

Use the local provider to run embeddings in-process with no outbound calls. This uses a built-in lightweight model and is suitable for smaller tool sets.

search:
  enabled: true
  embedding:
    provider: local
  top_k: 10

The search_tools tool

When search is enabled a special tool named search_tools is registered at the group level. MCP clients call it like any other tool:

# MCP tool call (JSON-RPC)
{
  "name": "search_tools",
  "arguments": {
    "query": "get current price of a cryptocurrency",
    "top_k": 3
  }
}

The response is a list of matching tool schemas (name, description, inputSchema) ranked by similarity score. The client then calls the best match directly.

Index refresh

The index is rebuilt whenever the tool registry changes — on hot-reload or background spec refresh. Rebuilds are atomic: the old index serves requests until the new one is ready.

Groups

Each group gets its own index scoped to its tool set. A group with a read-only subset only finds read-only tools. See Tool Groups.