> ## 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 atlanai CLI; `atlanai --map json` prints its command map. 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.

# Connect a client to MCP Gateway

> Add Atlan MCP Gateway to Claude Code, Cursor, VS Code, or any MCP client, sign in, and make your first audited call.

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:

  ```text theme={null}
  https://api.atlan.com/mcp
  ```

## Add the gateway to your client

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    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](/plugins/references/claude-code).
  </Tab>

  <Tab title="Cursor">
    Add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a
    project:

    ```json theme={null}
    {
      "mcpServers": {
        "atlan": { "url": "https://api.atlan.com/mcp" }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    Add the server to `.vscode/mcp.json` in your workspace:

    ```json theme={null}
    {
      "servers": {
        "atlan": { "type": "http", "url": "https://api.atlan.com/mcp" }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    Follow [Codex](/clients/openai/how-tos/codex) to add the endpoint to your
    Codex configuration.
  </Tab>

  <Tab title="Other clients">
    Most clients accept this shape:

    ```json theme={null}
    {
      "mcpServers": {
        "atlan": { "type": "http", "url": "https://api.atlan.com/mcp" }
      }
    }
    ```

    For agent frameworks, see
    [OpenAI Agents SDK](/frameworks/openai-agents-sdk/how-tos/openai-agents-sdk),
    [LangGraph](/frameworks/langgraph/how-tos/langgraph),
    [CrewAI](/frameworks/crewai/how-tos/crewai), and
    [Google ADK](/frameworks/google-adk/how-tos/google-adk).
  </Tab>
</Tabs>

## Sign in

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](https://www.rfc-editor.org/rfc/rfc9728)). MCP clients that
support OAuth 2.1 follow it without extra configuration.

For bearer tokens, see [Authentication](/api/how-tos/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.

<Steps>
  <Step title="List tools">
    Your client runs `tools/list` after sign-in. Confirm that you see
    `registry__initialise` and the other `registry__` tools.
  </Step>

  <Step title="Open a session">
    Call `registry__initialise` once when work starts. It returns a
    `session_id` that starts with `mcp_session_`.
  </Step>

  <Step title="Call tools with the session">
    Pass `session_id` and a short `rationale` on every later call:

    ```json theme={null}
    {
      "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."
        }
      }
    }
    ```
  </Step>
</Steps>

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. |

## Next steps

<CardGroup cols={2}>
  <Card title="Integrations" icon="puzzle-piece" href="/gateway/mcp/how-tos/integrations">
    Put your own MCP servers behind the same endpoint.
  </Card>

  <Card title="Track usage and audit" icon="chart-line" href="/gateway/mcp/how-tos/track-usage-and-audit">
    See every call across every server.
  </Card>
</CardGroup>


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