MCP cookbook

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.

​

Connect and discover tools

Configure the client to use Streamable HTTP at 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: 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 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 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.