Builds

Follow GitHub image builds, inspect builder output and trigger deployments.

Follow GitHub image builds, inspect builder output and trigger deployments.

These are action names. In default compact mode, call the indicated group tool with {"action":"<action-name>","params":{...}}; the arguments below go inside params. In ?mode=all, call the action name directly with those arguments. browse_github and read_docs are direct tools in both modes. Expand each schema for nested fields, enum values and validation constraints. Successful results are JSON in both text content and structuredContent; failures use isError and structuredContent.error.

list_builds

List the builds of a GitHub-sourced app, newest first

Group: apps · Behavior: Read

Compact tool: apps · Action: list_builds

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
apps.builds.list	GET /projects/{projectId}/apps/{appId}/builds	apps:read

Arguments

Argument	Type	Required	Description
projectId	string	Yes	Project id
appId	string	Yes	App id
limit	integer	No	Items per page, 1 to 200 (default 50)
cursor	string	No	nextCursor from the previous page; omit for the first page

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Items per page, 1 to 200 (default 50)"
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "description": "nextCursor from the previous page; omit for the first page"
    }
  },
  "required": [
    "projectId",
    "appId"
  ],
  "additionalProperties": false
}

Result

• builds (array<object>): See the complete response schema below.

• nextCursor (string or null): Pass as cursor to fetch the next page; null on the last page

Response schema: apps.builds.list

{
  "type": "object",
  "properties": {
    "builds": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Build id"
          },
          "appId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "succeeded",
              "failed",
              "cancelled"
            ],
            "description": "running until the image is built and the app deployed"
          },
          "step": {
            "type": "string",
            "enum": [
              "vcs_import",
              "image_build",
              "app_deploy",
              "completed"
            ],
            "description": "Pipeline step in progress, or completed"
          },
          "imageBuildStatus": {
            "description": "The image builder's own status (Created, Running, Completed, Failed, Canceled, TimedOut) once that step started",
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "repo": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "branch": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "commitSha": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "commitMessage": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "contextDir": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "dockerfilePath": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "repo",
                  "branch",
                  "commitSha",
                  "commitMessage",
                  "contextDir",
                  "dockerfilePath"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ],
            "description": "What was built; the commit is filled in once the build starts"
          },
          "error": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "step": {
                    "type": "string",
                    "description": "Step the build failed at"
                  },
                  "message": {
                    "type": "string"
                  },
                  "code": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "step",
                  "message",
                  "code"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp (UTC)"
          },
          "startedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          },
          "finishedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 timestamp (UTC)"
              },
              {
                "type": "null"
              }
            ]
          },
          "pollAfterSec": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Seconds to wait before reading the build again; null once it has finished"
          }
        },
        "required": [
          "id",
          "appId",
          "status",
          "step",
          "imageBuildStatus",
          "source",
          "error",
          "createdAt",
          "startedAt",
          "finishedAt",
          "pollAfterSec"
        ],
        "additionalProperties": false
      }
    },
    "nextCursor": {
      "description": "Pass as cursor to fetch the next page; null on the last page",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "builds",
    "nextCursor"
  ],
  "additionalProperties": false
}

get_build

Get one build: its status, pipeline step, source commit and error

Group: apps · Behavior: Read

Compact tool: apps · Action: get_build

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
apps.builds.get	GET /projects/{projectId}/apps/{appId}/builds/{buildId}	apps:read

Arguments

Argument	Type	Required	Description
projectId	string	Yes	Project id
appId	string	Yes	App id
buildId	string	Yes	Build id

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    },
    "buildId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Build id"
    }
  },
  "required": [
    "projectId",
    "appId",
    "buildId"
  ],
  "additionalProperties": false
}

Result

• id (string): Build id

• appId (string): See the complete response schema below.

• status ("pending" / "running" / "succeeded" / "failed" / "cancelled"): running until the image is built and the app deployed

• step ("vcs_import" / "image_build" / "app_deploy" / "completed"): Pipeline step in progress, or completed

• imageBuildStatus (string or null): The image builder's own status (Created, Running, Completed, Failed, Canceled, TimedOut) once that step started

• source (object or null): What was built; the commit is filled in once the build starts

• error (object or null): See the complete response schema below.

• createdAt (string): ISO 8601 timestamp (UTC)

• startedAt (string or null): See the complete response schema below.

• finishedAt (string or null): See the complete response schema below.

• pollAfterSec (integer or null): Seconds to wait before reading the build again; null once it has finished

Response schema: apps.builds.get

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Build id"
    },
    "appId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "succeeded",
        "failed",
        "cancelled"
      ],
      "description": "running until the image is built and the app deployed"
    },
    "step": {
      "type": "string",
      "enum": [
        "vcs_import",
        "image_build",
        "app_deploy",
        "completed"
      ],
      "description": "Pipeline step in progress, or completed"
    },
    "imageBuildStatus": {
      "description": "The image builder's own status (Created, Running, Completed, Failed, Canceled, TimedOut) once that step started",
      "type": [
        "string",
        "null"
      ]
    },
    "source": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "repo": {
              "type": [
                "string",
                "null"
              ]
            },
            "branch": {
              "type": [
                "string",
                "null"
              ]
            },
            "commitSha": {
              "type": [
                "string",
                "null"
              ]
            },
            "commitMessage": {
              "type": [
                "string",
                "null"
              ]
            },
            "contextDir": {
              "type": [
                "string",
                "null"
              ]
            },
            "dockerfilePath": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "repo",
            "branch",
            "commitSha",
            "commitMessage",
            "contextDir",
            "dockerfilePath"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "What was built; the commit is filled in once the build starts"
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "step": {
              "type": "string",
              "description": "Step the build failed at"
            },
            "message": {
              "type": "string"
            },
            "code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "step",
            "message",
            "code"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp (UTC)"
    },
    "startedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ]
    },
    "finishedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        {
          "type": "null"
        }
      ]
    },
    "pollAfterSec": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "description": "Seconds to wait before reading the build again; null once it has finished"
    }
  },
  "required": [
    "id",
    "appId",
    "status",
    "step",
    "imageBuildStatus",
    "source",
    "error",
    "createdAt",
    "startedAt",
    "finishedAt",
    "pollAfterSec"
  ],
  "additionalProperties": false
}

get_build_logs

Read the image builder's log for a build. The whole log once the build has finished, a snapshot of what has been written so far while it runs (empty until the builder starts writing).

Group: apps · Behavior: Read

Compact tool: apps · Action: get_build_logs

MCP annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Permissions and REST equivalents

Operation	REST	Required scopes
apps.builds.logs	GET /projects/{projectId}/apps/{appId}/builds/{buildId}/logs	monitoring:read

Arguments

Argument	Type	Required	Description
projectId	string	Yes	Project id
appId	string	Yes	App id
buildId	string	Yes	Build id

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    },
    "buildId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Build id"
    }
  },
  "required": [
    "projectId",
    "appId",
    "buildId"
  ],
  "additionalProperties": false
}

Result

• id (string): Build id

• status ("pending" / "running" / "succeeded" / "failed" / "cancelled"): See the complete response schema below.

• imageBuildStatus (string or null): See the complete response schema below.

• lines (array<string>): Builder output, oldest first

• complete (boolean): The image build has finished, so the log is final

• truncated (boolean): Older lines were dropped to keep the last 2000

Response schema: apps.builds.logs

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Build id"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "running",
        "succeeded",
        "failed",
        "cancelled"
      ]
    },
    "imageBuildStatus": {
      "type": [
        "string",
        "null"
      ]
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Builder output, oldest first"
    },
    "complete": {
      "type": "boolean",
      "description": "The image build has finished, so the log is final"
    },
    "truncated": {
      "type": "boolean",
      "description": "Older lines were dropped to keep the last 2000"
    }
  },
  "required": [
    "id",
    "status",
    "imageBuildStatus",
    "lines",
    "complete",
    "truncated"
  ],
  "additionalProperties": false
}

trigger_build

Rebuild a GitHub-sourced app and redeploy it when the build succeeds. From its branch head or one commit; a build still running is cancelled first. Poll get_build to follow it.

Group: apps · Behavior: Write

Compact tool: apps_write · Action: trigger_build

MCP annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: false · openWorldHint: true

Permissions and REST equivalents

Operation	REST	Required scopes
apps.builds.create	POST /projects/{projectId}/apps/{appId}/builds	apps:write, compute:spend

Arguments

Argument	Type	Required	Description
commitSha	string	No	Commit to build instead of the branch head
projectId	string	Yes	Project id
appId	string	Yes	App id

Complete input schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "commitSha": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$",
      "description": "Commit to build instead of the branch head"
    },
    "projectId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "Project id"
    },
    "appId": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{24}$",
      "description": "App id"
    }
  },
  "required": [
    "projectId",
    "appId"
  ],
  "additionalProperties": false
}

Result

• build (object): See the complete response schema below.

• cancelledBuilds (integer): Builds that were still running and were cancelled

Response schema: apps.builds.create

{
  "type": "object",
  "properties": {
    "build": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Build id"
        },
        "appId": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "running",
            "succeeded",
            "failed",
            "cancelled"
          ],
          "description": "running until the image is built and the app deployed"
        },
        "step": {
          "type": "string",
          "enum": [
            "vcs_import",
            "image_build",
            "app_deploy",
            "completed"
          ],
          "description": "Pipeline step in progress, or completed"
        },
        "imageBuildStatus": {
          "description": "The image builder's own status (Created, Running, Completed, Failed, Canceled, TimedOut) once that step started",
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "repo": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "branch": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "commitSha": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "commitMessage": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "contextDir": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "dockerfilePath": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "repo",
                "branch",
                "commitSha",
                "commitMessage",
                "contextDir",
                "dockerfilePath"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ],
          "description": "What was built; the commit is filled in once the build starts"
        },
        "error": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "step": {
                  "type": "string",
                  "description": "Step the build failed at"
                },
                "message": {
                  "type": "string"
                },
                "code": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "step",
                "message",
                "code"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp (UTC)"
        },
        "startedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "description": "ISO 8601 timestamp (UTC)"
            },
            {
              "type": "null"
            }
          ]
        },
        "finishedAt": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "description": "ISO 8601 timestamp (UTC)"
            },
            {
              "type": "null"
            }
          ]
        },
        "pollAfterSec": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "description": "Seconds to wait before reading the build again; null once it has finished"
        }
      },
      "required": [
        "id",
        "appId",
        "status",
        "step",
        "imageBuildStatus",
        "source",
        "error",
        "createdAt",
        "startedAt",
        "finishedAt",
        "pollAfterSec"
      ],
      "additionalProperties": false
    },
    "cancelledBuilds": {
      "type": "integer",
      "description": "Builds that were still running and were cancelled"
    }
  },
  "required": [
    "build",
    "cancelledBuilds"
  ],
  "additionalProperties": false
}

Operation-specific errors: 409 app_source_unsupported, 403 serverless_disabled, 503 github_not_configured, 404 github_installation_not_found, 404 github_repo_not_found, 502 upstream_github, 404 github_commit_not_found.