Skip to navigation

Tool Search plugin

The Tool Search plugin keeps a large tool catalog out of the client’s context. On a route with Tool Search, tools/list returns three gateway tools instead of the route’s real tools:

  • search_tool ranks the real tools by meaning against a query.
  • get_tool returns one tool’s input schema.
  • execute_tool calls a real tool by name.

The gateway ranks tools with embeddings from an OpenAI-compatible embedding service that you configure.

Where it runs

ProtocolsMCP routes
Scope kindsroute only
PhaseRequest. The MCP handling does the work.

Set up the plugin

Add a Tool Search instance to an MCP route in the console.

Prerequisites

  • An MCP route that serves the tools to search.
  • On a data plane that you manage, an embedding service that implements the OpenAI /embeddings API. You need its base URL, the model name, and the model’s vector dimension. If the service needs a key, store the key in a vault that the data plane can read. For more information, see Manage credentials and vaults.
  • On a Postman-hosted data plane, nothing else. The console uses the managed embedder.

Steps

  1. In the console sidebar, select Plugins, then open the All tab.
  2. Find tool-search and select Use.
  3. In Instance name, enter a name, for example tool-search-production.
  4. In Routes, select the MCP route. If you select several routes, the console creates one instance for each and Instance name becomes Base name.
  5. Under Configuration and Embedder, the Type is Managed on a Postman-hosted data plane, and you don’t enter anything else. On a data plane that you manage, the Type is Custom. Set the following values:
    • URL: The embedding service’s base URL, for example https://embeddings.example.com/v1. Don’t end it with / or /embeddings.
    • Model: The model name, for example text-embedding-3-small.
    • Vector dimension: The size of the model’s vectors, for example 1536.
    • (Optional) API key secret: A secret reference that your data plane can read, such as an AWS Secrets Manager ARN. env://, file://, and vault:// references aren’t supported.
  6. (Optional) Expand Search results to set Default results, Maximum results, and Maximum description length. The defaults are 10, 25, and 120 characters.
  7. Make sure Enabled is selected, then select Create instance.

Verify it works

Connect an MCP client to the route, as in Connect an MCP client, and list the tools. The list contains only search_tool, get_tool, and execute_tool. Then call search_tool with a query, such as create an issue. The result lists the best-matching real tools, each with a name, a summary, and a score.

Fix common problems

  • search_tool returns an error result that says the embedder is unavailable. The gateway can’t get vectors from the embedding service. Check URL, Model, and API key secret, and check that Vector dimension matches the model. A vector of any other length counts as a failure.
  • tools/list still shows the real tools. The route has no enabled Tool Search instance. Check the route and the Enabled setting.
  • A tool search error says tool search isn’t initialized. The data plane couldn’t build the search from the first Tool Search configuration that it received. Correct that configuration, and then restart the data plane. Changes to the embedder settings take effect only after a restart.
  • The console says to remove a trailing slash or /embeddings. The gateway appends /embeddings to URL. Remove that part from the URL.
  • The console says default results can’t exceed the maximum. Set Default results to a value at or below Maximum results, which is 25 unless you change it.

Configuration

result_limit_default
integerDefaults to 10

Results returned when the client doesn’t give a usable limit. At least 1, and not above result_limit_max.

result_limit_max
integerDefaults to 25

The maximum number of results.

summary_max_len
integerDefaults to 120

The maximum characters in each tool summary.

embedder
objectRequired

The embedding service.

embedder.base_url
string

The service’s base URL. The gateway calls POST <base_url>/embeddings with input and model, in the OpenAI format, so the URL can’t end with / or /embeddings. The console requires it.

embedder.model
string

The embedding model. The console requires it.

embedder.dimension
integerRequired

The vector length the model returns, at least 1. Vectors of any other length count as a failure.

embedder.api_key_ref
string

A secret reference that the data plane can read, such as an AWS Secrets Manager ARN, for the service’s API key. The gateway sends the key as Authorization: Bearer. The console refuses env://, file://, and vault:// references.

embedder.timeout
durationDefaults to 5s

The time limit for each call to the embedding service.

embedder.cold_start_timeout
durationDefaults to 60s

The total time to embed tools that don’t have a vector yet.

embedder.provider
string

Optional. With quantize and cache_scope, it only labels the vector index.

embedder.max_batch
integerDefaults to 256

Tools per embedding call. The console starts a new instance at 32, because Fabric’s own embedder accepts at most 32 inputs per request.

Example

{
"name": "tool-search",
"plugin_id": "tool-search",
"scope": { "kind": "route", "name": "workspace-mcp" },
"config": {
"result_limit_default": 5,
"embedder": {
"base_url": "https://embeddings.example.com/v1",
"model": "text-embedding-3-small",
"dimension": 1536,
"api_key_ref": "embedder-api-key"
}
}
}

On an Enterprise data plane, the Helm chart also deploys an embedding service, fabric-gateway-embedder, that serves the BAAI/bge-small-en-v1.5 model with 384 dimensions. For the embedder settings that use it, see Run the tool-search embedder.

The embedder.api_key_ref setting accepts a name from global.secrets.refs or an entry in a remote secret store, such as an AWS Secrets Manager ARN. It doesn’t accept env:// or file:// references.

⌂ 换网址