Skip to main content
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.

​
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

​
Need help

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