Connect a client to MCP Gateway

Connect any MCP client to one URL. Your client then sees Atlan’s platform tools and every MCP server your team has registered, with no server credentials in its config.

Before you begin

A client that supports the Streamable HTTP transport.
An Atlan account with access to the workspace you will work in.
The gateway endpoint:
https://api.atlan.com/mcp

Add the gateway to your client

Claude Code
Cursor
VS Code
Codex
Other clients

claude mcp add --transport http atlan https://api.atlan.com/mcp

Then run /mcp in a session and complete sign-in for atlan. For the Atlan plugin and its skills, see Claude Code.

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "atlan": { "url": "https://api.atlan.com/mcp" }
  }
}

Add the server to .vscode/mcp.json in your workspace:

{
  "servers": {
    "atlan": { "type": "http", "url": "https://api.atlan.com/mcp" }
  }
}

Most clients accept this shape:

{
  "mcpServers": {
    "atlan": { "type": "http", "url": "https://api.atlan.com/mcp" }
  }
}

For agent frameworks, see OpenAI Agents SDK, LangGraph, CrewAI, and Google ADK.

Choose how your client authenticates.

Method	Best for	How it works
OAuth sign-in	People using an IDE or desktop client	The client discovers Atlan’s sign-in automatically and opens a browser. No token goes in the config.
Bearer token	CI jobs, services, and headless agents	Send `Authorization: Bearer <token>` with each request. Load the token from a secret store, never from a committed file.

For OAuth, the gateway answers an unauthenticated request with 401 and points the client to https://api.atlan.com/.well-known/oauth-protected-resource/mcp (RFC 9728). MCP clients that support OAuth 2.1 follow it without extra configuration. For bearer tokens, see Authentication for the supported credential paths.

Open a session and make your first call

The gateway ties every tool call to a session, so the audit trail can show who did what and why.

List tools

Your client runs tools/list after sign-in. Confirm that you see registry__initialise and the other registry__ tools.

Open a session

Call registry__initialise once when work starts. It returns a session_id that starts with mcp_session_.

Call tools with the session

Pass session_id and a short rationale on every later call:

{
  "method": "tools/call",
  "params": {
    "name": "registry__search_artifacts",
    "arguments": {
      "query": "customer churn",
      "session_id": "mcp_session_01K…",
      "rationale": "The user asked which skills cover churn analysis."
    }
  }
}

Most agents do this without being told. The gateway adds session_id and rationale to every tool’s input schema, and the tool descriptions explain both fields.

Expected result

Your client lists Atlan platform tools plus the tools of every enabled server you can access. A read-only call such as registry__search_artifacts returns results, and the call appears in Tool calls in the MCP Gateway studio.

Troubleshooting

Symptom	Cause and fix
`session_id is required`	Call `registry__initialise` first, then pass its `session_id`.
`tool is unavailable; refresh tools/list`	The name is stale or mistyped. Run `tools/list` again and copy the exact name.
A registered server’s tools are missing	The server needs your sign-in, is disabled, or is unreachable. The gateway names it in the `tools/list` result’s `_meta`. Connect your account or ask the server’s owner to test it.
A call is refused with error `-32003`	You lack permission or a rate limit applies. Check `data.reason`, and wait for `retry_after_seconds` when it is present.

AI Gateway

MCP Gateway

Before you begin

Add the gateway to your client

Open a session and make your first call

Expected result

Troubleshooting

Next steps

Integrations

Track usage and audit

​Before you begin

​Add the gateway to your client

​Sign in

​Open a session and make your first call

​Expected result

​Troubleshooting

​Next steps

Integrations

Track usage and audit

Before you begin

Add the gateway to your client

Sign in

Open a session and make your first call

Expected result

Troubleshooting

Next steps