mage-agent

Phase 1 status

Implemented:

• Python package scaffold with mage-agent entrypoint
• MCP stdio runtime (mage-agent mcp)
• Shared core config/auth/http/error modules
• Tools layer (Python API wrappers) for pipeline CRUD, block operations, run trigger, and log retrieval

Local setup

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev]"

Configure credentials (recommended)

Use interactive login:

mage-agent login

Or provide values non-interactively:

mage-agent login \
  --cluster-url https://your-mage-url \
  --email YOUR_EMAIL \
  --password YOUR_PASSWORD \

login authenticates with the cluster URL using username/password, then writes ~/.mage-agent/config.json with your cluster_url and oauth_token. The agent uses a built-in default API key for requests.

Authentication gates runtime functionality: MCP tool calls require valid auth credentials.

Configure credentials (manual option)

Create ~/.mage-agent/config.json:

{
  "cluster_url": "https://your-mage-url",
  "oauth_token": "RAW_OAUTH_TOKEN"
}

Optional developer tooling

Dev tooling (flake8, pre-commit) is defined in pyproject.toml under optional dependency group dev. If you installed with pip install -e ".[dev]", run local checks with:

flake8 src
pre-commit run --all-files

Run MCP server

mage-agent mcp

Install and connect from IDEs

After installing mage-agent and running mage-agent login, configure your IDE/agent client to launch the MCP server with:

• command: mage-agent
• args: ["mcp"]

If mage-agent is not on PATH in the client runtime, use the absolute path to the executable.

Sync project to local files

mage-agent sync-project-to-local --local-project-dir .mage-agent/local_sync

If --local-project-dir is not provided, the CLI prompts for it.

Connect Cursor to MCP

1. Open Cursor settings and go to MCP servers.
2. Add a new server named mage-agent.
3. Use this command configuration:

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

If mage-agent is not on your PATH in Cursor, use the full executable path instead:

{
  "mcpServers": {
    "mage-agent": {
      "command": "/absolute/path/to/mage-agent",
      "args": ["mcp"]
    }
  }
}

After saving the config, reload Cursor and confirm the mage-agent MCP tools are available.

Connect Codex CLI to MCP

Add mage-agent to Codex MCP config (for example in your Codex config file):

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

Then restart Codex CLI and verify tools/resources are visible.

Connect Claude Code to MCP

Configure MCP servers in Claude Code with the same command:

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

Restart Claude Code after saving config, then run a simple MCP call (for example pipeline_list) to verify connectivity.