IDE Integration

Connect Cursor, Claude Code, or OpenAI Codex CLI to your Mage Pro cluster via MCP.

mage-agent exposes a Model Context Protocol (MCP) server over stdio. Any MCP-compatible AI client can connect by launching mage-agent mcp as a subprocess.

Prerequisites

Complete Installation and Authentication before setting up IDE integration.

---

Cursor

1. Open MCP settings

   In Cursor, go to Settings → MCP (or open the Command Palette and search for “MCP Servers”).

2. Add mage-agent

   Add the following server config:

   {
     "mcpServers": {
       "mage-agent": {
         "command": "mage-agent",
         "args": ["mcp"]
       }
     }
   }
   
3. Reload Cursor

   Save the config and reload the window. Confirm that mage-agent tools appear in the MCP tool list.

---

Claude Code

1. Add the MCP server via CLI

   claude mcp add mage-agent -- mage-agent mcp
   

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

   {
     "mcpServers": {
       "mage-agent": {
         "command": "mage-agent",
         "args": ["mcp"]
       }
     }
   }
   
2. Restart Claude Code

   Restart the Claude Code session. Run a quick sanity check:

   “Use the pipeline_list tool to list my Mage pipelines”

---

OpenAI Codex CLI

1. Edit your Codex config

   Add mage-agent to the mcpServers section of your Codex config file:

   {
     "mcpServers": {
       "mage-agent": {
         "command": "mage-agent",
         "args": ["mcp"]
       }
     }
   }
   
2. Restart Codex CLI

   Restart Codex CLI and verify tools and resources are visible.

---

PATH issues

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

which mage-agent
# e.g. /Users/you/.venv/bin/mage-agent

{
  "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).