Skip to main content
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 URIContent
skill://pipelinePipeline CRUD patterns and conventions
skill://blocksBlock inspection and editing guidance
skill://executionsRun triggers and log retrieval
skill://syncSync operations and conflict handling
These are loaded automatically from your cluster at login time (with bundled fallbacks if the cluster is unreachable).