Skip to main content
Once mage-agent is connected to your IDE, your AI assistant has access to the following tools. All tools require valid authentication.

​
Pipelines

List all pipelines in the project.Arguments: noneExample prompt: “List all my Mage pipelines”
Get details for a single pipeline.
ParameterTypeRequiredDescription
uuidstringyesPipeline UUID
Create a new pipeline.
ParameterTypeRequiredDescription
namestringyesPipeline name
typestringnopython (default), streaming, or integration
Example prompt: “Create a new streaming pipeline called realtime_events”
Update fields on an existing pipeline.
ParameterTypeRequiredDescription
uuidstringyesPipeline UUID
namestringnoNew name
descriptionstringnoUpdated description
Delete a pipeline by UUID.
ParameterTypeRequiredDescription
uuidstringyesPipeline UUID
Deletion is permanent and cannot be undone.

​
Blocks

List all blocks in a pipeline.
ParameterTypeRequiredDescription
pipeline_uuidstringyesPipeline UUID
Get block details including source code.
ParameterTypeRequiredDescription
pipeline_uuidstringyesPipeline UUID
uuidstringyesBlock UUID
Create a new block in a pipeline.
ParameterTypeRequiredDescription
pipeline_uuidstringyesPipeline UUID
namestringyesBlock name
typestringyesBlock type (see below)
languagestringnopython (default), sql, r, yaml, markdown
contentstringnoInitial source code
upstream_blocksarraynoUUIDs of upstream blocks
configobjectnoAdditional block configuration
Supported block types: data_loader, transformer, data_exporter, sensor, callback, chart, conditional, custom, dbt, extension, global_data_product, markdown, scratchpad
If no config is provided, mage-agent automatically matches a block template for you. For integration pipelines, it also auto-detects available sources and destinations.
Example prompt: “Add a SQL transformer block to the customer_etl pipeline that filters rows where revenue > 1000”
Update a block’s code or configuration.
ParameterTypeRequiredDescription
pipeline_uuidstringyesPipeline UUID
uuidstringyesBlock UUID
contentstringnoNew source code
namestringnoNew name
upstream_blocksarraynoUpdated upstream block UUIDs
List available block templates.
ParameterTypeRequiredDescription
force_refreshbooleannoBypass the daily cache and re-fetch from cluster
Templates are cached for 24 hours at ~/.mage-agent/cache/block_templates.json.

​
Runs & Logs

Trigger a pipeline run.
ParameterTypeRequiredDescription
pipeline_uuidstringyesPipeline UUID
payloadobjectnoOptional run payload (variables, etc.)
Example prompt: “Run the daily_refresh pipeline”
Fetch logs for a specific pipeline run.
ParameterTypeRequiredDescription
pipeline_run_idstringyesPipeline run ID (returned by run_pipeline)
Example prompt: “Show me the logs for the last run”

​
Sync

Pull all remote project files to a local directory.
ParameterTypeRequiredDescription
local_project_dirstringnoLocal directory path (default: .mage-agent/local_sync)
Show what has changed between local and remote.
ParameterTypeRequiredDescription
local_project_dirstringnoLocal directory path
Push locally changed files to the cluster.
ParameterTypeRequiredDescription
local_project_dirstringnoLocal directory path

​
Error responses

All tool errors return a structured envelope: 
{
  "status": "error",
  "error": {
    "code": "AUTH_EXPIRED",
    "message": "Session token expired. Run `mage-agent login` to re-authenticate."
  }
}
Error codeCause
CONFIG_INVALIDMissing or malformed ~/.mage-agent/config.json
AUTH_REQUIREDNo credentials found
AUTH_EXPIRED401/403 from cluster — run mage-agent login
API_ERRORCluster API returned an error
TOOL_NOT_FOUNDRequested tool name is not registered
INTERNAL_ERRORUnexpected internal failure