IDE Integration

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

Open MCP settings

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

Add mage-agent

Add the following server config:

{
  "mcpServers": {
    "mage-agent": {
      "command": "mage-agent",
      "args": ["mcp"]
    }
  }
}

Reload Cursor

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

Claude Code

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"]
    }
  }
}

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

Edit your Codex config

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

{
  "mcpServers": {
    "mage-agent": {
      "command": "mage-agent",
      "args": ["mcp"]
    }
  }
}

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

​Prerequisites

​Cursor

​Claude Code

​OpenAI Codex CLI

​PATH issues

​Skill resources