Tools mode

Tools mode (tools_mode: {}) is the conventional way the MCP gateway serves its registry: every tool is an MCP tool, and an agent calls one per model turn with tools/call. Use it for simple tasks, and for clients that expect a classic tool list. The alternative for multi-step work is code mode, which serves the same registry as a single execute tool.

How an agent discovers tools

Discovery in tools mode is a short, stateless conversation:

1. initialize opens the session, as with any MCP server.
2. tools/list returns the caller's eager tools — the handful most tasks need. When the caller also has progressive tools (the default disclosure mode, which keeps the long tail out of the list), the list includes one more tool: tool_search.
3. tool_search takes a query and returns the best-matching progressive tools as full MCP definitions — name, description, inputSchema and outputSchema — ranked with BM25 or an embeddings model. The description of tool_search itself names up to 256 progressive tools the caller may use, so a model can often pick a name without searching at all.
4. tools/call invokes any permitted tool by its qualified name, listed or not.

Listing is stateless: a search does not change later tools/list results, and there is no list-changed notification to handle. Non-MCP clients can search the same index over plain HTTP with POST /mcp/search.

What a call does

A tools/call is dispatched to the tool's backend — a templated HTTP request against a REST backend's cluster, or a forwarded call to an upstream MCP server — with the arguments validated against the input schema on the way in and, when an output_schema is declared, the response validated on the way out. Per-tool authorization decides from JWT claims which tools a caller can see, search and call.

Filling the registry

The registry the mode serves is configured the same way in both modes: static tools over REST backends, OpenAPI documents, federated MCP servers, and tool discovery over xDS.

Next

• Tool search — configuring disclosure modes and ranking.
• Build an MCP gateway — a complete tools-mode configuration with JWT and per-tool RBAC.
• Code mode — the same registry as one execute tool.