Find and call tools

As your team registers more MCP servers, the catalog grows past what an agent can usefully read in one tools/list. Every tool definition an agent loads costs context and makes the right choice harder. MCP Gateway indexes every tool it serves, both Atlan platform tools and your servers’ tools, by name and by meaning. An agent describes the task in plain words, semantic search returns only the relevant tools, and the agent calls the one it needs.

Without search	With semantic search
The agent reads every tool from every server	The agent reads only the tools that match the task
Tool choice depends on scanning long lists	Results are ranked by how well they match the request
A new server adds to every agent’s context	A new server is found only when it is relevant

One tool call, end to end. Step 1: semantic search of the catalog returns only the relevant tools. Step 2: pick a tool by its wire name. Step 3: send tools/call with session_id and rationale. Step 4: the gateway checks access, forwards the call, and records it. Search with POST /mcp/v1/tools/search or the registry__search_artifacts tool.

Search the catalog by meaning

Each catalog entry holds a tool’s own name, its description, and the server or platform component that runs it. The gateway updates the catalog when a server is registered, tested, or refreshed, and checks every server for changes once an hour.

From an agent (MCP)
From an application (REST)

Call registry__search_artifacts with kind set to mcp_tool:

{
  "method": "tools/call",
  "params": {
    "name": "registry__search_artifacts",
    "arguments": {
      "query": "create a ticket",
      "kind": "mcp_tool",
      "semantic": true,
      "limit": 10,
      "session_id": "mcp_session_01K…",
      "rationale": "Find a tool that files a ticket for the user."
    }
  }
}

Argument	Required	Meaning
`query`	Yes	What the tool should do, in plain words.
`kind`	No	Set to `mcp_tool` to search only tools.
`semantic`	No	`true` matches by meaning instead of by keyword. Defaults to `false`.
`workspace_id`	No	Limit results to one workspace.
`limit`	No	Results to return. Defaults to 50, up to 500.

Call Search the tool catalog:

curl -X POST "https://api.atlan.com/mcp/v1/tools/search" \
  -H "Authorization: Bearer $ATLAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": "create a ticket", "strategy": "hybrid", "limit": 10 }'

Field	Meaning
`query`	What the tool should do.
`strategy`	`fts` for keyword, `vector` for meaning, or `hybrid` for both.
`workspace_id`	Limit results to one workspace.
`is_system_included`	Include Atlan platform tools. Defaults to `true`.
`limit`, `offset`, `cursor`	Page through results.

Turn a result into a wire name

A search result names the tool and where it runs. The name you call adds a namespace prefix:

The result has	Call it as
`owner: "registry"`	`registry__<tool_name>`
Another `owner`, such as `skill`	`extension__<owner>__<tool_name>`
A `server_id` and no `owner`	`remote__<server_id>__<tool_name>`

For example, a tool create_issue on server mcp_server_01k7… is called as remote__mcp_server_01k7…__create_issue.

The live tools/list result is the authority for exact wire names and input schemas on the deployment you are connected to. When in doubt, match the search result against tools/list before calling.

Call the tool

Send a standard MCP tools/call to https://api.atlan.com/mcp with the wire name, the tool’s arguments, your session_id, and a rationale. Before forwarding the call, the gateway:

Confirms that the tool is in the catalog. A tool the gateway has not discovered cannot be called.
Checks your permission. You can see the tools of any server in a workspace you can read. Running them requires permission to update that workspace.
Attaches the server’s credential, either the shared credential or your own connected account.
Forwards the call, relays progress and cancellation, and records the outcome in your session.

When to search first

Situation	Approach
A few servers, a focused agent	Read `tools/list` once and choose from it.
Many servers, or an agent that serves open-ended requests	Search the catalog, then call only the tools that match.
An application that picks tools for users	Use the REST search and show the results before calling.
An inventory or governance report	Use `POST /mcp/v1/tools/search` or `GET /mcp/v1/tools`.

GET /mcp/v1/tools and the search endpoints read the stored catalog. It can briefly trail a server that has just changed, so use the live tools/list when you must know exactly what is callable right now.

AI Gateway

MCP Gateway

Search the catalog by meaning

Turn a result into a wire name

Call the tool

When to search first

Next steps

Understand the tool catalog

Integrations

​Search the catalog by meaning

​Turn a result into a wire name

​Call the tool

​When to search first

​Next steps

Understand the tool catalog

Integrations

Search the catalog by meaning

Turn a result into a wire name

Call the tool

When to search first

Next steps