> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mage Agent Plugin

> Install the Mage Agent Plugin and connect it to a Mage cluster.

export const ProOnly = ({button = 'Get started for free', description = 'Try our fully managed solution to access this advanced feature.', source = 'documentation', title = 'Only in Mage Pro.'}) => <a href={`https://cloud.mage.ai/sign-up?source=${source}`} className="block my-4 px-5 py-4 overflow-hidden rounded-xl flex gap-3 border border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10" target="_blank">
    <div style={{
  display: 'flex',
  alignItems: 'center',
  width: '100%'
}}>
      <div className="text-sm prose min-w-0 text-emerald-900 dark:text-emerald-200" style={{
  flex: 1
}}>
        {title}
        <p className="normal">{description}</p>
      </div>

      <div> </div>

      <div>
        <ProButton label={button} href={`https://cloud.mage.ai/sign-up?source=${source}`} />
      </div>
    </div>
  </a>;

export const ProButton = ({href, label = 'Get started with Mage Pro for free', source = 'documentation'}) => <div style={{
  height: 32,
  position: 'relative'
}}>
    <a target="_blank" className="group px-4 py-1.5 relative inline-flex items-center text-sm font-medium rounded-full" href={href ?? `https://cloud.mage.ai/sign-up?source=${source}`}>
      <span className="absolute inset-0 bg-primary-dark dark:bg-primary-light/10 border-primary-light/30 rounded-full dark:border group-hover:opacity-[0.9] dark:group-hover:border-primary-light/60">
      </span>

      <div className="mr-0.5 space-x-2.5 flex items-center">
        <span class="z-10 text-white dark:text-primary-light">
          {label}
        </span>

        <svg width="3" height="24" viewBox="0 -9 3 24" class="h-5 rotate-0 overflow-visible text-white/90 dark:text-primary-light">
          <path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path>
        </svg>
      </div>
    </a>
  </div>;

# Mage Agent Plugin Installation Guide

<ProOnly source="mage-agent-plugin" />

## What It Is

The Mage Agent Plugin connects an AI agent client to Mage so the agent can work
with the Mage clusters you authorize. After installation and sign-in, the agent
can help inspect and operate Mage workflows, including pipelines, blocks,
schedules, runs, logs, outputs, files, and other Mage project resources.

## Where To Download It

Download the installer from the public Mage Agent Plugin releases repository:

```text theme={"system"}
https://github.com/mage-ai/agent-plugin/releases
```

The `mage-ai/agent-plugin` repository is the public release-asset repository.
The plugin source and release automation are maintained in the Mage plugin
source under:

```text theme={"system"}
mage-pro/plugins/mage-agent-plugin
```

## Choose The Correct Installer

Use the package that matches your agent client and operating system.

macOS:

```text theme={"system"}
Mage-Agent-MacOS-Codex.pkg
Mage-Agent-MacOS-Claude.pkg
```

Windows:

```text theme={"system"}
Mage-Agent-Windows-Codex.zip
Mage-Agent-Windows-Claude.zip
```

Use the Codex package if you are installing the plugin for Codex. Use the
Claude package if you are installing it for Claude Code.

## Prerequisites

Before installing, make sure you have:

* Access to the Mage cluster you want the agent to use.
* The cluster name or cluster URL.
* The correct agent client installed, such as Codex or Claude Code.
* For Claude Code, the Claude Code CLI must be installed and support plugins.

For Claude Code, verify:

```bash theme={"system"}
claude plugin --help
```

## Install On macOS

1. Open the GitHub Releases page:

```text theme={"system"}
https://github.com/mage-ai/agent-plugin/releases
```

2. Download the correct `.pkg` file:

```text theme={"system"}
Mage-Agent-MacOS-Codex.pkg
Mage-Agent-MacOS-Claude.pkg
```

3. Open the downloaded package.
4. Follow the installer prompts.
5. When the installer finishes, the Mage plugin is installed for the selected
   agent client.

The macOS installer starts the Mage OAuth sign-in helper after installing the
plugin.

## Install On Windows

1. Open the GitHub Releases page:

```text theme={"system"}
https://github.com/mage-ai/agent-plugin/releases
```

2. Download the correct `.zip` file:

```text theme={"system"}
Mage-Agent-Windows-Codex.zip
Mage-Agent-Windows-Claude.zip
```

3. Extract the zip file.
4. Run the installer command inside the extracted folder.

For Codex:

```powershell theme={"system"}
.\Install-Codex.cmd
```

For Claude Code:

```powershell theme={"system"}
.\Install-Claude-Code.cmd
```

## Sign In To Mage

After installing, sign in to Mage and connect the plugin to a cluster.

If the installer opens the sign-in flow automatically, complete the browser
login and select or provide the Mage cluster.

If you need to sign in manually from the plugin source checkout, run:

```bash theme={"system"}
./plugins/mage-agent-plugin/scripts/mage-login <cluster-name-or-url>
```

Example:

```bash theme={"system"}
./plugins/mage-agent-plugin/scripts/mage-login mageai-1-tutorials
```

You can also use a full cluster URL:

```bash theme={"system"}
./plugins/mage-agent-plugin/scripts/mage-login https://your-mage-cluster-url
```

## Switch Clusters

To connect the plugin to a different Mage cluster, run:

```bash theme={"system"}
./plugins/mage-agent-plugin/scripts/mage-switch-cluster
```

To skip the cluster selection screen, pass the cluster name or URL directly:

```bash theme={"system"}
./plugins/mage-agent-plugin/scripts/mage-switch-cluster <cluster-name-or-url>
```

Example:

```bash theme={"system"}
./plugins/mage-agent-plugin/scripts/mage-switch-cluster mageai-1-tutorials
```

## Verify The Active Cluster

Check which Mage cluster is currently connected:

```bash theme={"system"}
./plugins/mage-agent-plugin/scripts/mage-current-cluster
```

List saved local cluster state:

```bash theme={"system"}
./plugins/mage-agent-plugin/scripts/mage-list-clusters
```

## What Gets Saved Locally

After sign-in, the plugin stores the active Mage connection locally at:

```text theme={"system"}
~/.mage/agent/config.json
```

That file stores the selected `cluster_url` and the token needed for the plugin
to call Mage on your behalf.

OAuth helper logs are written to:

```text theme={"system"}
~/.mage/agent/codex-oauth.log
```

## Confirm It Works

After installation and sign-in:

1. Open your agent client.
2. Ask the agent to use Mage.
3. Try a read-only request first, such as listing available Mage pipelines or
   checking the current cluster.
4. If the agent asks you to authenticate, complete the browser sign-in and retry
   the request.

## Quick Checklist

* Download installer from `https://github.com/mage-ai/agent-plugin/releases`.
* Pick Codex or Claude package.
* Pick macOS `.pkg` or Windows `.zip`.
* Install the package.
* Sign in to Mage.
* Provide or select the Mage cluster name or URL.
* Verify the active cluster.
* Ask the agent to run a simple Mage read-only request.