> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools

> Full reference for every tool your AI assistant can call via mage-agent.

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

<Note>
  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.
</Note>

## Resource Widget Contract

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:

```json theme={"system"}
{
  "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.

## Adding Widget Support

To add another Mage resource widget:

1. Add the resource/action pair to `widget_contracts.py`.
2. Add presentation columns, summary fields, empty/error copy, and guidance in
   `widget_registry.py`.
3. Add adapter tests that cover populated, empty, malformed, large-result, and
   secret-bearing payloads.
4. Add renderer coverage in `widgets/resource_widget` and the app-shell preview
   route under `/apps/test/resource-widgets`.
5. 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

<AccordionGroup>
  <Accordion title="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. |

    <Note>
      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?"
    </Note>
  </Accordion>
</AccordionGroup>

***

## Pipelines

<AccordionGroup>
  <Accordion title="pipeline_list">
    List all pipelines in the project.

    **Arguments:** none

    **Example prompt:** *"List all my Mage pipelines"*
  </Accordion>

  <Accordion title="pipeline_get">
    Get details for a single pipeline.

    | Parameter | Type   | Required | Description   |
    | --------- | ------ | -------- | ------------- |
    | `uuid`    | string | yes      | Pipeline UUID |
  </Accordion>

  <Accordion title="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`"*
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="pipeline_delete">
    Delete a pipeline by UUID.

    | Parameter | Type   | Required | Description   |
    | --------- | ------ | -------- | ------------- |
    | `uuid`    | string | yes      | Pipeline UUID |

    <Warning>Deletion is permanent and cannot be undone.</Warning>
  </Accordion>
</AccordionGroup>

***

## Blocks

<AccordionGroup>
  <Accordion title="block_list">
    List all blocks in a pipeline.

    | Parameter       | Type   | Required | Description   |
    | --------------- | ------ | -------- | ------------- |
    | `pipeline_uuid` | string | yes      | Pipeline UUID |
  </Accordion>

  <Accordion title="block_get">
    Get block details including source code.

    | Parameter       | Type   | Required | Description   |
    | --------------- | ------ | -------- | ------------- |
    | `pipeline_uuid` | string | yes      | Pipeline UUID |
    | `uuid`          | string | yes      | Block UUID    |
  </Accordion>

  <Accordion title="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`

    <Note>
      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.
    </Note>

    **Example prompt:** *"Add a SQL transformer block to the `customer_etl` pipeline that filters rows where revenue > 1000"*
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="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`.
  </Accordion>
</AccordionGroup>

***

## Runs & Logs

<AccordionGroup>
  <Accordion title="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"*
  </Accordion>

  <Accordion title="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"*
  </Accordion>
</AccordionGroup>

***

## Sync

<AccordionGroup>
  <Accordion title="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`) |
  </Accordion>

  <Accordion title="sync_status">
    Show what has changed between local and remote.

    | Parameter           | Type   | Required | Description          |
    | ------------------- | ------ | -------- | -------------------- |
    | `local_project_dir` | string | no       | Local directory path |
  </Accordion>

  <Accordion title="sync_local_to_remote">
    Push locally changed files to the cluster.

    | Parameter           | Type   | Required | Description          |
    | ------------------- | ------ | -------- | -------------------- |
    | `local_project_dir` | string | no       | Local directory path |
  </Accordion>
</AccordionGroup>

***

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

<AccordionGroup>
  <Accordion title="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:

    ```json theme={"system"}
    {
      "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.
  </Accordion>
</AccordionGroup>

***

## Error responses

All tool errors return a structured envelope:

```json theme={"system"}
{
  "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                      |