Skip to main content
Search mode gives your agent three tools instead of every tool in your catalog. The agent searches for the tools it needs, reads only their schemas, and runs one at a time. Its context stays small however many MCP servers your team adds. Search mode is the default. A client connected to the gateway URL is in search mode:
?tools=search on the URL also selects search mode. To list every tool you can reach instead, add ?tools=full for full mode, as described in Use full mode. Full mode will be deprecated later, so plan to move your clients to search mode.

​
Search mode and full mode compared

​
Why search mode is the default

Search mode helps most when:
  • Your catalog is large. Many servers mean many tool schemas. In full mode, the agent loads all of them on every turn. In search mode, it loads three small tools and then only what it looks up.
  • Your client cannot filter tools. Some clients show the agent every tool a server lists. Search mode keeps that list fixed at three.
  • Per-tool approval slows your work. Some clients, such as Claude Code, ask you to approve each tool by name. In search mode they ask once, for mcp__call_tool.
Use full mode, ?tools=full, when you must see and approve each tool by name, or when your client’s permission rules or hooks match tool names. In search mode, every call goes through mcp__call_tool, so a rule for a specific tool name no longer matches.

​
If your client used full mode before

Search mode became the default on the plain URL. A client that connected to https://api.atlan.com/mcp before now sees three tools instead of every tool. What changes for it:
  • Approvals and rules. Per-tool approvals, and permission rules or hooks keyed on tool names, no longer match, because tools run through mcp__call_tool. Add ?tools=full to keep them working until you move.
  • Sessions. The first search opens the session. A session_id you pass must be one you opened.
  • Direct calls. A call to a tool by its own name still works, with a session_id, though tools/list does not show it. So does mcp__initialise, which opens a session the same way, for a client that already calls it.
If your client still shows its old tool list, reconnect it, for example with /mcp in Claude Code, so it lists tools again.

​
How a task runs

  1. Search. The agent calls mcp__search_tools with a query: one sentence about what it needs, naming the app if it knows it. The first search also sends an objective: one sentence about what the whole session is for. The result lists matching tools with their names and input schemas, and a session_id.
  2. Describe, if needed. When the agent already knows a tool’s name, for example from a prompt, mcp__describe_tools returns that tool’s schema. It can also list every tool on the servers you name. A describe does not open a session, so search first even when you know the tool’s name.
  3. Call. The agent calls mcp__call_tool with the tool’s name, its arguments, the session_id, and a short rationale. The gateway runs the tool with the same checks as a direct call and returns the tool’s result unchanged.
For each tool’s arguments and an example, see Search mode tools.

​
Sessions

The gateway ties every tool call to a session, so the audit trail can show who did what and why. In search mode:
  • The first mcp__search_tools call opens the session. It must send an objective, written for the person who will read the audit trail later. The gateway stores it once.
  • That search returns a session_id that starts with mcp_session_. Pass it on every later search, describe, and call.
  • mcp__call_tool refuses a call without a session_id. A describe still answers without one. A search without one opens a new session, so it must send an objective.
  • The session_id goes at the top level of the mcp__call_tool arguments, beside name and arguments. Never put it inside the tool’s own arguments.
  • A session belongs to the person or agent that opened it. Another caller’s session_id is refused.
Some clients, such as VS Code, send their own conversation ID with each call. The gateway then keeps one session for that conversation. A session’s objective, each search’s query, and each call’s rationale are stored permanently, and anyone who can read the session’s workspace can read them. Keep credentials and customer data out of them. Tool arguments and results are not stored. See Track usage and audit tool calls.

​
Scope a search to some servers

Pass servers to keep a search, or a describe, within those servers. Name each server the way its tools are named: the part of the tool name before the last __. Each search result shows this as server. Case and spaces are folded, so Linear also names linear. You can list up to 20 servers. servers only narrows a search. It never gives access to a tool you could not otherwise call.

​
Servers you have not connected

Some servers use each person’s own account. If a search matches such a server and you have not connected your account, the server comes back under connect instead of as tools:
To connect, open Connect a client in MCP Studio and choose Connect next to the account. Then search again.

​
Permissions and approvals

Search mode reaches exactly the tools full mode lists for you, and mcp__call_tool runs each one with the same permission check, credential, rate limit, and audit record as a direct call. A call you could not make in full mode is refused in search mode too. See MCP permissions. Because the client sees only mcp__call_tool, it cannot tell which tool runs underneath. mcp__call_tool is marked as a tool that can change data. If you choose always allow for mcp__call_tool in your client, that approval covers every tool you can reach through the gateway. If your client keeps a per-agent allowlist, check arguments.name before letting a call through.

​
How search ranks tools

Search matches your query against each tool’s name, description, and server name. It uses full-text search, not a language model, so it matches words, not meaning. A query that names the app, such as “create a Linear issue”, ranks that server’s tools first. If a search misses, rephrase it with words the tool’s description is likely to use, or describe the server’s tools with mcp__describe_tools. This is a different search from How tool search works, which an agent or application runs over the stored catalog in either mode.

​
Limits

  • A search returns up to 20 tools, 5 by default. A describe returns up to 20 named tools, or up to 100 tools for servers alone.
  • Each search and each describe counts as one call against your rate limits. A tool run through mcp__call_tool costs the same as a direct call, so a search followed by a call costs one more call than a direct call.
  • Search mode does not change what MCP Gateway supports. Prompts and resources work as in full mode.

​
See also