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

# MCP cookbook

> Connect a supported client, open an auditable session, and use Atlan MCP tools.

Use this cookbook to connect a coding harness or agent framework to Atlan MCP,
open an auditable session, and use the tools available to your identity.

## Before you begin

You need access to the workspace where you will use the tools. Your client
authenticates through its OAuth sign-in flow. Follow the client-specific guide
for the appropriate setup.

## Choose your client

Open the integration guide for the client that runs your agent. Each guide
explains its connection settings, authentication, verification, and known
limits.

<CardGroup cols={2}>
  <Card title="Claude Code" icon="https://mintcdn.com/atlan-602e2b74/pPcK1s6Qs7BTlBW2/assets/integrations/claude.svg?fit=max&auto=format&n=pPcK1s6Qs7BTlBW2&q=85&s=3d6e920914e126cf26cf379859af5dfb" href="/plugins/references/claude-code" width="32" height="32" data-path="assets/integrations/claude.svg">
    Make Atlan MCP tools available in a Claude Code session.
  </Card>

  <Card title="Codex" icon="https://mintcdn.com/atlan-602e2b74/pPcK1s6Qs7BTlBW2/assets/integrations/openai.svg?fit=max&auto=format&n=pPcK1s6Qs7BTlBW2&q=85&s=cb2b7173992862e45da3113c20014e5c" href="/clients/openai/how-tos/codex" width="24" height="24" data-path="assets/integrations/openai.svg">
    Give Codex access to the tools available to your identity and workspace.
  </Card>

  <Card title="OpenAI Agents SDK" icon="https://mintcdn.com/atlan-602e2b74/pPcK1s6Qs7BTlBW2/assets/integrations/openai.svg?fit=max&auto=format&n=pPcK1s6Qs7BTlBW2&q=85&s=cb2b7173992862e45da3113c20014e5c" href="/frameworks/openai-agents-sdk/how-tos/openai-agents-sdk" width="24" height="24" data-path="assets/integrations/openai.svg">
    Load Atlan MCP tools in an OpenAI SDK agent.
  </Card>

  <Card title="LangGraph" icon="https://mintcdn.com/atlan-602e2b74/pPcK1s6Qs7BTlBW2/assets/integrations/langgraph.svg?fit=max&auto=format&n=pPcK1s6Qs7BTlBW2&q=85&s=c895ab5aab631cbc6be58cc562eeb969" href="/frameworks/langgraph/how-tos/langgraph" width="63" height="63" data-path="assets/integrations/langgraph.svg">
    Add Atlan MCP tools to a graph or agent node.
  </Card>

  <Card title="CrewAI" icon="https://mintcdn.com/atlan-602e2b74/pPcK1s6Qs7BTlBW2/assets/integrations/crewai.svg?fit=max&auto=format&n=pPcK1s6Qs7BTlBW2&q=85&s=84cc0210decf8030d0eabcd0f7ffeaca" href="/frameworks/crewai/how-tos/crewai" width="48" height="48" data-path="assets/integrations/crewai.svg">
    Connect a CrewAI agent to Atlan MCP tools.
  </Card>

  <Card title="Google ADK" icon="https://mintcdn.com/atlan-602e2b74/pPcK1s6Qs7BTlBW2/assets/integrations/google.svg?fit=max&auto=format&n=pPcK1s6Qs7BTlBW2&q=85&s=16fac321f7e3207c93f65cb041d9de20" href="/frameworks/google-adk/how-tos/google-adk" width="118" height="120" data-path="assets/integrations/google.svg">
    Make Atlan MCP tools available through `McpToolset`.
  </Card>
</CardGroup>

## Connect and discover tools

Configure the client to use Streamable HTTP at
[`https://api.atlan.com/mcp`](https://api.atlan.com/mcp),
then complete its OAuth sign-in flow. A successful connection initializes the
MCP session and lets the client list the tools available to the authenticated
identity and workspace.

Find `registry__initialise` in the live `tools/list` result and call it once
when work starts. Pass its
returned `session_id` on later calls so reviewers can follow the work as one
session. The session ID is optional, but Gateway rejects one that is malformed
or not visible to the caller.

The `/mcp` endpoint advertises tools as `<server>__<tool>`. Agent Gateway
The pinned contract currently declares 32 first-party tools:

| Provider | Tools | Scope |
| - | -: | - |
| Registry | 16 | Artifact reads and writes, relationships, account traces, and session initialization |
| Agent | 6 | Bulk Agent creation and Agent, harness, or session trace reads |
| Skill | 5 | Skill creation and Skill trace reads |
| File | 1 | Upload staging |
| Ontology | 4 | Bounded release context, versioned interchange, and SPARQL metadata planning |

Use the names returned by authenticated `tools/list` when constructing a call.
They are the wire contract for the deployment and account you connected to.
Downstream server names also vary by account.

See [Understand the tool catalog](/tools/mcp/references/tool-catalog) for every current
first-party tool, the extensions that declare zero tools, and the difference
between live and projected tool lists. Registered downstream MCP servers can
add more tools for a specific account.

Read each tool's description and input schema before using it. Select only the
tools your workflow needs. A smaller tool set makes an agent easier to review
and reduces the chance of an unintended change.

Platform-provided tools can be owned by Registry or by an installed extension.
Tools from registered downstream servers are discovered from their server. Your
client's live `tools/list` result is authoritative for callable names and input
schemas, so inspect it before constructing a call.

## Common call fields

Gateway adds a required `rationale` string to tool schemas by default. Write a
short explanation of why the call advances the user's task. An operator can
disable rationale collection.

After initialization, pass the optional `session_id` to connect later calls to
the same session. Gateway checks that the value has the `mcp_session_...` shape
and resolves to a session the caller can read. A downstream tool that already
defines its own `session_id` keeps that field instead.

## What Gateway records

Initialization creates an `mcp_session` in the account's organisation root.
Gateway records the objective and available client metadata for audit, but does
not use those fields for authorization.

Calls made with a verified `session_id` can create an ordered
`mcp_session_message` containing the tool name, server namespace, rationale,
outcome, duration, protocol metadata, and trace context. Recording is
best-effort: a recording failure does not fail the tool call. Gateway does not
store the call arguments or tool output in the session message.

## Verify with a read-only task

Confirm that the client lists the expected tools, then use a read-only task
before allowing a workflow to make changes. For example, search for an
existing item or inspect an item the agent has already found. If the expected
tools are missing, confirm the selected workspace and the client's
authentication before changing the workflow.

## Manage servers and inspect the catalog

Use the **MCP** category in the [API reference](/api/references/api-reference) to
list registered servers, inspect one server, test its availability, and browse
the tool catalog. Use that reference when an application needs to manage a
server or verify its tools outside an MCP client.

## Use the tool reference

The tool pages in this tab describe Registry and every extension that currently
declares tools. Read a write tool's retry and partial-success rules before
calling it.

For a tool from a registered downstream server, inspect the server record and
your live `tools/list` result before granting it to an agent.