Skip to main content
Connecting a client to MCP Gateway gives it access to Atlan’s tools and every MCP server your team has added, with your identity, your permissions, and a record of every call. You add one URL, sign in once, and the client is ready for every task that uses those tools. You can connect a coding tool you use yourself, an agent you are building, or a CI pipeline that runs headlessly.

Before you begin

Before you start, make sure you have:
  • MCP client: must support Streamable HTTP transport. stdio and legacy HTTP+SSE are not supported. See Supported features and limits if you are unsure whether your client qualifies.
  • Atlan account: access to the workspace whose tools and servers you expect to reach.

Connect your client

1

Add gateway

Add https://api.atlan.com/mcp to your client. The URL is the same for every client and every tool mode.
Run:
This adds a server named atlan, private to you in the current project. Add --scope user to use it across all your projects, or --scope project to share it through the project’s .mcp.json. Keep credentials out of project files — sign-in happens in the next step. To verify: claude mcp list.
By default, the gateway connects in search mode: tools/list returns five tools that find, describe, and run every other tool in the catalog. Your client’s context stays small regardless of how many servers your team adds. You choose which tools to let run without asking using those five tool names, not hundreds of individual tool names.
2

Sign in

  1. In a Claude Code session, run /mcp.
  2. Select atlan from the server list.
  3. Complete the Atlan OAuth sign-in in your browser.
  4. Claude Code stores the session — you do not need to sign in again for each project. No credential goes in your configuration.
For CI jobs, services, and headless agents with no browser, send a bearer token with every request instead of completing OAuth:
Retrieve the token from a secret store or environment variable — never from a committed file. For which credential types work, see Authentication.
An Atlan API key sent as a bearer token acts as the key, not as you: it reaches what the organization shares at its top level and the workspaces the key is added to, not your own full access.
3

Verify connection

Ask your agent a read-only task to confirm the connection is working and tools are reachable. For example:
The agent searches for the right tool, calls it with your credentials, and returns results. Open Tool calls in MCP Studio and confirm the call appears there with your name, the tool name, the rationale the agent gave, and the outcome.If nothing comes back, check that the server is listed as connected (claude mcp list in Claude Code; MCP: List Servers in VS Code), confirm OAuth sign-in completed, and check that your account has access to at least one workspace. For specific errors, see Troubleshooting.

Troubleshooting

  • Call says session_id is required or tool is unavailable, or is refused with -32003: see MCP Gateway errors.
  • A server’s tools are missing from the list: see MCP Gateway errors.
  • Connected to the wrong Atlan MCP server? If the agent’s Atlan tools are about search, lineage, and glossaries and there is no mcp__search_tools, it is using the Agentic Data Catalog’s server at https://mcp.atlan.com/mcp, a different product. See MCP servers and plugins.
  • Sign-in repeats or never completes: see Atlan sign-in repeats or never completes.

Next steps

How search mode works: How sessions open, how the agent finds and calls tools, and how the audit trail is built.

See also