Skip to main content

Set up OpenAI Codex with Atlan MCP

Connect docs via MCP

Connect OpenAI Codex—both the desktop app and the CLI—to the Atlan MCP server using the Atlan Codex Plugin. OAuth is handled automatically with mcp.atlan.com when you register the MCP server. No API key or environment variable is required.

Prerequisites​

Before you begin, make sure you have:

  • An Atlan tenant with Atlan MCP enabled.
  • OpenAI Codex installed—either the desktop app, the CLI, or both.

Set up Codex with Atlan MCP​

Choose the setup that fits how you use Codex. Plugin install is the recommended path. Use direct MCP install only if you need the Codex CLI alone and don't want the desktop-app plugin entry.

The Atlan Codex Plugin is published in the Atlan agent toolkit repository, which exposes a Codex marketplace.

  1. Register Atlan's marketplace with Codex:

    codex plugin marketplace add https://github.com/atlanhq/agent-toolkit

  2. Install the Atlan plugin from that marketplace:

    codex plugin add atlan@atlan

    The atlan@atlan slug uses Codex's <plugin-name>@<marketplace-name> convention. The first atlan is the plugin name; the second is the marketplace name (Atlan's). It's how Codex resolves which plugin from which marketplace—not an internal-only identifier.

  3. Register the MCP server. Codex CLI doesn't yet read the plugin's bundled MCP configuration, so this step performs the actual registration and launches the OAuth flow with mcp.atlan.com. Complete the sign-in in your browser. This step is no longer required once OpenAI's Plugin Directory is generally available and Codex CLI honors the plugin's bundled configuration:

    codex mcp add atlan --url https://mcp.atlan.com/mcp

  4. Quit and relaunch Codex so the new server loads into the session—Cmd+Q for the desktop app, or exit and re-run the CLI. The Atlan plugin appears under Plugins → Manage (enabled, with the MCP server registered).

  5. Inside a Codex session, run /mcp to inspect connected servers, then ask anything Atlan-related—for example:

    Find all tables in the snowflake connection and trace lineage upstream from orders_fact.

Verify connection​

Confirm the plugin is installed and the MCP server is reachable:

codex plugin list | grep atlan   # atlan@atlan installed, enabled
codex mcp list                   # atlan ✓

You can then ask Atlan-related questions inside a Codex session—for example:

  • Find all tables in the Snowflake connection.
  • Trace lineage upstream from the orders_fact table.
  • List glossary terms tagged as PII in my catalog.

For the full list of tools available, see MCP tools.

Uninstall​

To fully remove the Atlan plugin and MCP server, reverse each install step in the opposite order:

# 1. Sign out of the MCP server (clears the OAuth token from ~/.codex/auth.json)
codex mcp logout atlan

# 2. Remove the MCP server registration ([mcp_servers.atlan] in ~/.codex/config.toml)
codex mcp remove atlan

# 3. Remove the plugin from Plugins → Manage
codex plugin remove atlan@atlan

# 4. (Optional) Remove Atlan's marketplace itself
codex plugin marketplace remove atlan

Quit and relaunch Codex so the change takes effect in any open session. After all four steps, ~/.codex/config.toml has no [marketplaces.atlan] or [mcp_servers.atlan] sections, and ~/.codex/auth.json no longer carries an Atlan OAuth token. An empty ~/.codex/plugins/cache/atlan/ directory may remain—it's harmless, but you can rm -rf it for a fully clean wipe.

If you used the Direct MCP (CLI only) path, skip steps 3 and 4.

Need help?​

If you have any issues configuring the integration, contact Atlan Support for assistance.

See also​