MCP Tools

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

In MCP clients that support rendered tool output, mage-agent returns compact resource widgets for supported resource actions. Widgets are currently available for pipelines, blocks, pipeline runs, block runs, block outputs, pipeline schedules, and pipeline triggers. They do not change the tool arguments or authentication flow; clients that do not support rendered output still receive the normal structured tool response.

The widget path is an additive MCP Apps enhancement for read-only resource tools. A widget-enabled tool descriptor includes both _meta.ui.resourceUri and _meta["openai/outputTemplate"] pointing at the registered HTML resource. When the tool succeeds, mage-agent returns:

structuredContent.kind = "mage_resource_widget"
structuredContent.schema_version for renderer compatibility
structuredContent.resource and structuredContent.action
structuredContent.state as ok, empty, loading, or error
sanitized records, summary, columns, filters, and pagination
optional sanitized mutation metadata for create, update, or delete results
optional sanitized graph data for pipeline-oriented detail widgets, using normalized nodes and edges instead of raw pipeline YAML
content[0].text as a JSON fallback for clients that do not render widgets
_meta["openai/widgetData"] with widget-only rendering hints

List and get widgets render the normal table or detail view. Mutating actions may render the returned record with a mutation summary banner and footer, such as Operation: Create; delete results without a returned record render a compact success state. The adapter must redact sensitive fields before they enter structuredContent, fallback content, widget _meta, or activity logs. Pipeline-oriented widgets may include a compact graph preview when Mage returns block dependency metadata. The graph shape is:

{
  "nodes": [
    {
      "id": "load_customers",
      "label": "Load customers",
      "type": "data_loader",
      "status": "completed",
      "selected": false
    }
  ],
  "edges": [
    {
      "source": "load_customers",
      "target": "segment_customers"
    }
  ],
  "totalNodes": 12,
  "truncated": false
}

Renderers should treat graph data as optional. If it is missing, malformed, or too large, the widget must fall back to the existing list/detail table without blocking the tool response. To add another Mage resource widget:

Add the resource/action pair to widget_contracts.py.
Add presentation columns, summary fields, empty/error copy, and guidance in widget_registry.py.
Add adapter tests that cover populated, empty, malformed, large-result, and secret-bearing payloads.
Add renderer coverage in widgets/resource_widget and the app-shell preview route under /apps/test/resource-widgets.
Run the MCP protocol tests and an EKS mocked app-shell visual check before calling the change QA-ready.

For normal Mage trigger inventory, active trigger counts, API/webhook trigger lists, run-once schedules, and next run dates, use pipeline_schedules. Use pipeline_triggers only when the user explicitly asks for the advanced PipelineTriggerResource config surface scoped to a pipeline.

Codex chat context

current_page_context

Read the visible non-chat text that Mage Pro AI Chat captured from the user’s current browser page for the active chat turn.This tool is only registered when Mage Pro AI Chat starts Codex with captured page context. Standard IDE MCP sessions do not expose it unless MAGE_AGENT_CURRENT_PAGE_CONTEXT_PATH points to a valid context sidecar file.

Parameter	Type	Required	Description
`include_text`	boolean	no	Return the captured page text. Set to `false` to return metadata only.

The context is scoped to the authenticated user and chat session, excludes the Codex chat UI, and should only be used for page-relative requests such as “explain this page” or “what am I looking at?”

Pipelines

pipeline_list

List all pipelines in the project.Arguments: noneExample prompt: “List all my Mage pipelines”

pipeline_get

Get details for a single pipeline.

Parameter	Type	Required	Description
`uuid`	string	yes	Pipeline UUID

pipeline_create

Create a new pipeline.

Parameter	Type	Required	Description
`name`	string	yes	Pipeline name
`type`	string	no	`python` (default), `streaming`, or `integration`

Example prompt: “Create a new streaming pipeline called realtime_events”

pipeline_update

Update fields on an existing pipeline.

Parameter	Type	Required	Description
`uuid`	string	yes	Pipeline UUID
`name`	string	no	New name
`description`	string	no	Updated description

pipeline_delete

Delete a pipeline by UUID.

Parameter	Type	Required	Description
`uuid`	string	yes	Pipeline UUID

Deletion is permanent and cannot be undone.

Blocks

block_list

List all blocks in a pipeline.

Parameter	Type	Required	Description
`pipeline_uuid`	string	yes	Pipeline UUID

block_get

Get block details including source code.

Parameter	Type	Required	Description
`pipeline_uuid`	string	yes	Pipeline UUID
`uuid`	string	yes	Block UUID

block_create

Create a new block in a pipeline.

Parameter	Type	Required	Description
`pipeline_uuid`	string	yes	Pipeline UUID
`name`	string	yes	Block name
`type`	string	yes	Block type (see below)
`language`	string	no	`python` (default), `sql`, `r`, `yaml`, `markdown`
`content`	string	no	Initial source code
`upstream_blocks`	array	no	UUIDs of upstream blocks
`config`	object	no	Additional 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”

block_update

Update a block’s code or configuration.

Parameter	Type	Required	Description
`pipeline_uuid`	string	yes	Pipeline UUID
`uuid`	string	yes	Block UUID
`content`	string	no	New source code
`name`	string	no	New name
`upstream_blocks`	array	no	Updated upstream block UUIDs

block_templates_list

List available block templates.

Parameter	Type	Required	Description
`force_refresh`	boolean	no	Bypass the daily cache and re-fetch from cluster

Templates are cached for 24 hours at ~/.mage-agent/cache/block_templates.json.

Runs & Logs

run_pipeline

Trigger a pipeline run.

Parameter	Type	Required	Description
`pipeline_uuid`	string	yes	Pipeline UUID
`payload`	object	no	Optional run payload (variables, etc.)

Example prompt: “Run the daily_refresh pipeline”

run_logs

Fetch logs for a specific pipeline run.

Parameter	Type	Required	Description
`pipeline_run_id`	string	yes	Pipeline run ID (returned by `run_pipeline`)

Example prompt: “Show me the logs for the last run”

Sync

sync_project_to_local

Pull all remote project files to a local directory.

Parameter	Type	Required	Description
`local_project_dir`	string	no	Local directory path (default: `.mage-agent/local_sync`)

sync_status

Show what has changed between local and remote.

Parameter	Type	Required	Description
`local_project_dir`	string	no	Local directory path

sync_local_to_remote

Push locally changed files to the cluster.

Parameter	Type	Required	Description
`local_project_dir`	string	no	Local directory path

Mage Cloud Backend

Mage Cloud Backend tools are exposed only for installed-agent sessions that have Cloud handoff credentials. These tools are generated from the Cloud Backend resource inventory, so call mage_tool_contract before invoking a Cloud tool when payload or query shape matters.

Cloud Backend contracts

Cloud Backend create and update requests use the same resource-root envelope that the backend API expects. Do not send flat mutation payloads.

Tool	Mutation payload root
`teams`	`team`
`cloud_users`	`user`
`team_memberships`	`team_membership`
`invitations`	`invitation`

Role fields use Cloud Backend integer values: owner 0, admin 1, editor 2, viewer 3.For example, creating a team invitation uses:

{
  "action": "create",
  "identifiers": {
    "team_id": "42"
  },
  "payload": {
    "invitation": {
      "invitee_email": "user@example.com",
      "role": 3
    }
  }
}

cluster_stats requires query.cluster_uuid; cluster_uuid is not a path identifier for that tool.cloud_users supports list, get, and update. It does not expose create, because Cloud Backend treats users.create as the public signup path rather than a private team-admin user creation API.

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 code	Cause
`CONFIG_INVALID`	Missing or malformed `~/.mage-agent/config.json`
`AUTH_REQUIRED`	No credentials found
`AUTH_EXPIRED`	401/403 from cluster — run `mage-agent login`
`API_ERROR`	Cluster API returned an error
`TOOL_NOT_FOUND`	Requested tool name is not registered
`INTERNAL_ERROR`	Unexpected internal failure

Adventure starts here

Deployment architecture

Getting started

Mage Agent

CI/CD

Pro only features

Infrastructure

Migration guides

Global hooks

Mage Pro API

Resource Widget Contract

Adding Widget Support

Codex chat context

Pipelines

Blocks

Runs & Logs

Sync

Mage Cloud Backend

Error responses

​Resource Widget Contract

​Adding Widget Support

​Codex chat context

​Pipelines

​Blocks

​Runs & Logs

​Sync

​Mage Cloud Backend

​Error responses

Resource Widget Contract

Adding Widget Support

Codex chat context

Pipelines

Blocks

Runs & Logs

Sync

Mage Cloud Backend

Error responses