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

# IDE Integration

> Connect Cursor, Claude Code, OpenAI Codex CLI, or another MCP-compatible AI client to your Mage Pro cluster via MCP.

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.'}) => <div 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">
    <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
}}>
        <span className="font-semibold">{title}</span>
        <p className="normal">{description}</p>
      </div>

      <div> </div>

      <div style={{
  height: 32,
  position: 'relative'
}}>
        <a target="_blank" rel="noopener noreferrer" className="group px-4 py-1.5 relative inline-flex items-center text-sm font-medium rounded-full" 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 className="z-10 text-white dark:text-primary-light">
              {button}
            </span>

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

<ProOnly source="mage-agent-ide-integration" />

mage-agent exposes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server over stdio. Any MCP-compatible AI client can connect by launching `mage-agent mcp` as a subprocess.

## Prerequisites

Complete [Installation](/agent/installation) and [Authentication](/agent/authentication) before setting up IDE integration.

***

## Cursor

<Steps>
  <Step title="Open MCP settings">
    In Cursor, go to **Settings → MCP** (or open the Command Palette and search for "MCP Servers").
  </Step>

  <Step title="Add mage-agent">
    Add the following server config:

    ```json theme={"system"}
    {
      "mcpServers": {
        "mage-agent": {
          "command": "mage-agent",
          "args": ["mcp"]
        }
      }
    }
    ```
  </Step>

  <Step title="Reload Cursor">
    Save the config and reload the window. Confirm that `mage-agent` tools appear in the MCP tool list.
  </Step>
</Steps>

***

## Claude Code

<Steps>
  <Step title="Add the MCP server via CLI">
    ```bash theme={"system"}
    claude mcp add mage-agent -- mage-agent mcp
    ```

    Or add it manually to `.claude/settings.json` in your project (or `~/.claude/settings.json` globally):

    ```json theme={"system"}
    {
      "mcpServers": {
        "mage-agent": {
          "command": "mage-agent",
          "args": ["mcp"]
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Code">
    Restart the Claude Code session. Run a quick sanity check:

    > "Use the `pipeline_list` tool to list my Mage pipelines"
  </Step>
</Steps>

***

## OpenAI Codex CLI

<Steps>
  <Step title="Edit your Codex config">
    Add `mage-agent` to the `mcpServers` section of your Codex config file:

    ```json theme={"system"}
    {
      "mcpServers": {
        "mage-agent": {
          "command": "mage-agent",
          "args": ["mcp"]
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Codex CLI">
    Restart Codex CLI and verify tools and resources are visible.
  </Step>
</Steps>

## PATH issues

If `mage-agent` is not found when the IDE launches the MCP server, use the absolute path to the executable:

```bash theme={"system"}
which mage-agent
# e.g. /Users/you/.venv/bin/mage-agent
```

```json theme={"system"}
{
  "mcpServers": {
    "mage-agent": {
      "command": "/Users/you/.venv/bin/mage-agent",
      "args": ["mcp"]
    }
  }
}
```

***

## Skill resources

When connected, your AI assistant can also read four Markdown guidance resources that describe how to interact with Mage:

| Resource URI | Content |
| - | - |
| `skill://pipeline` | Pipeline CRUD patterns and conventions |
| `skill://blocks` | Block inspection and editing guidance |
| `skill://executions` | Run triggers and log retrieval |
| `skill://sync` | Sync operations and conflict handling |

These are loaded automatically from your cluster at login time (with bundled fallbacks if the cluster is unreachable).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.