> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `aireg` CLI; `aireg --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
> These docs cover Atlan AI Registry, Atlan's hosted product. The AI registry specification and aireg CLI are maintained separately. /open-source lists publicly reachable signed installers and explains that the source repository and hosted CLI reference currently require GitHub access. Do not claim the repository or its reference docs are publicly accessible. Use these docs for Atlan-specific setup such as the adapter, sign-in and workspaces.
# How search mode works
> Give an agent three tools that find, describe, and run every other MCP Gateway tool, so its context stays small as your catalog grows.
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:
```text theme={null}
https://api.atlan.com/mcp
```
`?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](https://platform.atlan.com/gateway/mcp/how-tos/connect-a-client.md#use-full-mode). Full mode will be deprecated later, so plan to move your clients to search mode.
## Search mode and full mode compared
| | Search mode (default) | Full mode |
| - | - | - |
| URL | `https://api.atlan.com/mcp`, or with `?tools=search` | `https://api.atlan.com/mcp?tools=full` |
| `tools/list` | `mcp__search_tools`, `mcp__describe_tools`, and `mcp__call_tool` | Every tool you can reach, plus `mcp__initialise` |
| Session opens with | The first `mcp__search_tools` call, which sends an `objective` | `mcp__initialise` |
| Tool context grows with | What each search returns, 5 tools by default | Every tool's schema, on every turn |
| Calls to run a new tool | A search, then a call | One call |
| Approval in clients that ask per tool | One approval, for `mcp__call_tool` | One approval per tool name |
| Tools you can reach | The same as full mode | The same as search mode |
## 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](https://platform.atlan.com/tools/mcp/references/search-mode-tools.md).
## 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](https://platform.atlan.com/gateway/mcp/how-tos/track-usage-and-audit.md).
## 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`.
| Tool name | Server name to pass |
| - | - |
| `linear__save_issue` | `linear` |
| `registry__search_artifacts` | `registry` |
| `extension__skill__create` | `extension__skill`, or `skill` |
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:
```json theme={null}
"connect": [
{
"server": "github",
"provider": "github",
"reason": "never_connected",
"note": "Ask the user to connect their account for this server, then search again."
}
]
```
| `reason` | What to do |
| - | - |
| `never_connected` | Connect your account for this server. |
| `needs_reconnect` | Reconnect your account. The service no longer accepts your earlier sign-in. |
| `audience_mismatch`, `token_rejected` | The connected account does not match the server. Reconnect, or ask the server's owner to check its sign-in settings. |
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](https://platform.atlan.com/gateway/mcp/concepts/permissions.md).
A call passes two separate checks: your client's approval, then the gateway's permission check.
```mermaid theme={null}
sequenceDiagram
participant A as Agent
participant C as Your client
participant G as MCP Gateway
participant S as Tool's server
A->>C: mcp__call_tool (name, arguments)
Note over C: Approval: sees only mcp__call_tool,
marked as able to change data
C->>G: Call, once approved
Note over G: Your permissions, credential,
rate limit, audit record
G->>S: Run the named tool
S-->>G: Result
G-->>C: The tool's result, unchanged
C-->>A: The result
```
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.
A client that asks before any tool marked as able to change data asks before every `mcp__call_tool` call, including reads. Codex does, and refuses the call in `codex exec`; see [Connect Codex](https://platform.atlan.com/clients/openai/how-tos/codex.md#decide-how-codex-approves-tool-calls).
A script or CI job that allows tools by name must allow all three search mode tools under the client's full names for them, or the search or the call is denied. For Claude Code with a server named `atlan`:
```bash theme={null}
claude -p "" --allowedTools "mcp__atlan__mcp__search_tools,mcp__atlan__mcp__describe_tools,mcp__atlan__mcp__call_tool"
```
Allowing `mcp__atlan__mcp__call_tool` allows every tool you can reach through the gateway, as **always allow** does.
## 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](https://platform.atlan.com/gateway/mcp/concepts/find-and-call-tools.md), 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](https://platform.atlan.com/gateway/mcp/references/supported-features.md#governance). 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
* [Connect client to MCP Gateway](https://platform.atlan.com/gateway/mcp/how-tos/connect-a-client.md): Connect a client, or use full mode.
* [Search mode tools](https://platform.atlan.com/tools/mcp/references/search-mode-tools.md): Arguments, results, and examples for the three tools.
* [MCP Gateway errors](https://platform.atlan.com/gateway/mcp/troubleshooting.md#search-mode-errors): Fix search-mode refusals.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.