Skip to main content

​
Mage Agent Plugin Installation Guide

​
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:
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:

​
Choose The Correct Installer

Use the package that matches your agent client and operating system. Claude Code and Claude Desktop use different packages. macOS:
Windows:
Use the Codex package if you are installing the plugin for Codex. Use the Claude package if you are installing it for Claude Code. For Claude Desktop, use the separate .mcpb extension described below.

​
Claude Desktop

The Claude Desktop extension bundles the standalone Mage Agent executable; it does not require Python or the Claude Code CLI. Choose the file for your computer: It exposes the same shared API-backed tools and bundled skill guidance through MCP. Claude Desktop decides how to display and load that guidance. Use a Desktop extension supplied with the release or test build you are installing. The .pkg and .zip files named for Claude Code install into Claude Code and do not register a Claude Desktop extension.
  1. In Claude Desktop, open Settings > Extensions > Advanced settings > Install Extension, select the .mcpb file, and follow the installation prompts.
  2. Enable the Mage extension, then start a conversation.
  3. Ask: “Connect Mage to my cluster” and provide the cluster name or URL.
  4. Complete the Mage sign-in in your browser when prompted, then return to Claude Desktop.
  5. Ask: “What Mage tools are available?” or “List my Mage pipelines.”
The extension starts the bundled executable directly. You do not need to enter a token into extension settings. The first tool that needs authentication can also start browser sign-in automatically. If Mage Cloud tools are missing after your first sign-in, restart the extension to refresh its tool list. Claude Desktop reuses the Mage connection stored in ~/.mage/agent/config.json. The selected cluster is shared with other Mage Agent clients on the same computer. To change it, ask “Connect Mage to https://your-mage-cluster-url”; this updates the shared connection. If a tool fails, check the active cluster, your access, and the server’s feature configuration before retrying.

​
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, Claude Code, or Claude Desktop with desktop extension support.
  • For Claude Code, the Claude Code CLI must be installed and support plugins.
For Claude Code, verify:

​
Install On macOS

  1. Open the GitHub Releases page:
  1. Download the correct .pkg file:
  1. Open the downloaded package.
  2. Follow the installer prompts.
  3. 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:
  1. Download the correct .zip file:
  1. Extract the zip file.
  2. Run the installer command inside the extracted folder.
For Codex:
For Claude Code:

​
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:
Example:
You can also use a full cluster URL:

​
Switch Clusters

To connect the plugin to a different Mage cluster, run:
To skip the cluster selection screen, pass the cluster name or URL directly:
Example:

​
Verify The Active Cluster

Check which Mage cluster is currently connected:
List saved local cluster state:

​
What Gets Saved Locally

After sign-in, the plugin stores the active Mage connection locally at:
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:

​
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, Claude Code, or Claude Desktop.
  • Pick the matching macOS .pkg, Windows .zip, or Desktop .mcpb file.
  • 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.