> ## 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 `brain` CLI; `brain --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 Agent Registry, Atlan's hosted product. The open-source agent registry specification and its CLI (`brain`) are documented, released and maintained in their own repository; /open-source on this site links to it. Answer general specification or `brain` command questions from the project's own docs, and use these docs only for Atlan-specific setup such as the Atlan adapter, sign-in and workspaces.

# MCP Gateway errors

> Symptoms, causes, and fixes for missing sessions, stale tool names, missing server tools, and refused calls through MCP Gateway.

These are errors from connecting a client to Atlan MCP Gateway and calling tools through it. Start from the error or symptom you see: each section below starts from one of them.

## `session_id is required`

A tool call is refused because it has no session.

### Cause

The gateway ties every tool call to a session. The client called a tool before opening one, or did not pass the session's ID.

### Solution

1. Call `mcp__initialise` once when work starts.
2. Pass the returned `session_id`, which starts with `mcp_session_`, and a short `rationale` on every later call.

***

## `tool is unavailable; refresh tools/list`

A call names a tool the gateway does not recognize.

### Cause

The tool name is stale or mistyped, or the server added the tool after its last refresh.

### Solution

1. Run `tools/list` again and copy the exact name.
2. If the tool is new on its server, ask an editor of the server's workspace to refresh its tools. In **Tool calls**, open the failed call and choose **Check** to see the closest name.

***

## Registered server's tools are missing

`tools/list` does not include tools from a server your team registered.

### Cause

The server needs your sign-in, is disabled, or is unreachable. The gateway names it in the `tools/list` result's `_meta`.

### Solution

1. Read `_meta` in the `tools/list` result for the server and its reason.
2. Connect your account if the server needs your sign-in.
3. Otherwise, ask the server's owner to test it in [Integrations](/gateway/mcp/how-tos/integrations).

***

## Call refused with `-32003`

A tool call fails with error code `-32003`.

### Cause

You lack permission for the tool's workspace, or a rate limit applies.

### Solution

1. Read `data.reason` in the error.
2. For a rate limit, wait for `retry_after_seconds` when it is present, then retry.
3. For a permission refusal, ask a workspace admin for access.

***

## See also

* [Connect client to MCP Gateway](/gateway/mcp/how-tos/connect-a-client): Sessions, rationale, and audited tool calls.
* [Track usage and audit](/gateway/mcp/how-tos/track-usage-and-audit): Find failed calls in the audit trail.

## Need help

If you need assistance after trying these steps, contact Atlan support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.