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 By default, the gateway connects in search mode:
https://api.atlan.com/mcp to your client. The URL is the same for every client and every tool mode.- Claude Code
- Codex
- Cursor
- VS Code
- Other clients
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.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
- Claude Code
- Codex
- Cursor
- VS Code
- Other clients
- In a Claude Code session, run
/mcp. - Select
atlanfrom the server list. - Complete the Atlan OAuth sign-in in your browser.
- Claude Code stores the session — you do not need to sign in again for each project. No credential goes in your configuration.
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 requiredortool 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 athttps://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
- Client connection settings: complete reference for endpoint, tool mode, sign-in methods, and tool approval names.