Topline Docs

Build MCP

Build MCP: Hosted tool reference

Generated hosted Build MCP reference with schemas, authorization, mutability, and recovery guidance.

Topline Build MCP Tool Reference

Generated from HOSTED_HARNESS_MCP_TOOL_DEFINITIONS for /mcp/build. Do not edit this file directly. Run npm run docs:generate.

Topline exposes these 14 hosted Topline Build MCP tools. A client only sees tools allowed by its connector token scopes and the user's current capabilities.

platform_connection_check

Complete a one-time Developer Access verification challenge and prove that this authenticated MCP client can call the selected Topline product.

  • MCP product: Build, Workspace
  • Required OAuth scope: build: harness:artifact:read, workspace: docs:read
  • Tool behavior: read-only: no; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {
    "verificationCode": {
      "type": "string",
      "minLength": 16,
      "maxLength": 80,
      "description": "One-time code shown in Topline Developer Access."
    }
  },
  "required": [
    "verificationCode"
  ]
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "verified": {
      "type": "boolean"
    },
    "product": {
      "type": "string",
      "enum": [
        "build",
        "workspace"
      ]
    },
    "verifiedAt": {
      "type": "string"
    }
  },
  "required": [
    "ok",
    "verified",
    "product",
    "verifiedAt"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_create_artifact_app

Validate an artifact-app manifest v2 and create or update a private Topline artifact draft.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:write
  • Tool behavior: read-only: no; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "manifest": {
      "type": "object"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "projectId": {
      "type": "string",
      "format": "uuid"
    },
    "clientRequestId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Stable retry key generated by the local Build MCP."
    },
    "bundleSha256": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}
quot;,
      "description": "Content identity used to replay a lost deployment response safely."
    }
  },
  "required": [
    "manifest"
  ]
}

Output schema

No output schema is currently declared by the runtime contract.

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_artifact_status

Read draft deployment status and readiness for a hosted artifact app.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:read
  • Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "limit": {
      "type": "number"
    }
  },
  "required": [
    "artifactId"
  ]
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "deployments": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId",
    "deployments"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_list_build_workspaces

List Topline workspaces available for artifact placement without exposing workspace chat or memory.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:read
  • Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {}
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "workspaces": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "ok",
    "workspaces"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_list_artifact_drafts

Discover private artifact drafts created by this Build MCP connection.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:read
  • Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "format": "uuid"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "drafts": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "ok",
    "drafts"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_deploy_operation

Read durable server-side progress for one artifact deployment operation.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:read
  • Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "operationId": {
      "type": "string",
      "format": "uuid"
    },
    "afterSeq": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "artifactId",
    "operationId"
  ]
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "operationId": {
      "type": "string"
    },
    "taskStatus": {
      "type": "string"
    },
    "progress": {
      "type": "number"
    },
    "terminal": {
      "type": "boolean"
    },
    "successful": {
      "type": "boolean"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId",
    "operationId",
    "taskStatus",
    "progress",
    "terminal",
    "successful",
    "events"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_run_artifact_smoke

Rerun the trusted draft smoke check and return fresh rendered-page evidence.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:deploy
  • Tool behavior: read-only: no; destructive: no; idempotent: not declared; open-world access: yes

Input schema

{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "deploymentRecordId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "artifactId"
  ]
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "deploymentRecordId": {
      "type": "string"
    },
    "smoke": {
      "type": "object"
    },
    "validation": {
      "type": "object"
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId",
    "deploymentRecordId",
    "smoke",
    "validation"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_plan_artifact_draft_delete

Preview the exact effects of deleting an eligible private draft and mint a short-lived state-bound plan token.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:delete
  • Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "artifactId"
  ]
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "eligible": {
      "type": "boolean"
    },
    "effects": {
      "type": "object"
    },
    "planToken": {
      "type": "string"
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId",
    "eligible",
    "effects",
    "planToken"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_validate_artifact

Read trusted smoke and rendered-page health evidence for a private artifact draft without requiring a browser session.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:read
  • Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "deploymentRecordId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "artifactId"
  ]
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "deploymentRecordId": {
      "type": "string"
    },
    "deploymentState": {
      "type": "string"
    },
    "healthy": {
      "type": "boolean"
    },
    "checkedAt": {
      "type": [
        "string",
        "null"
      ]
    },
    "draftUrl": {
      "type": [
        "string",
        "null"
      ]
    },
    "smoke": {
      "type": [
        "object",
        "null"
      ]
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId",
    "deploymentRecordId",
    "deploymentState",
    "healthy",
    "checkedAt",
    "draftUrl",
    "smoke"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_read_artifact_logs

Read bounded, redacted deployment logs for a hosted artifact app draft.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:read
  • Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "deploymentRecordId": {
      "type": "string",
      "format": "uuid"
    },
    "environment": {
      "type": "string",
      "enum": [
        "draft",
        "live"
      ]
    },
    "limit": {
      "type": "number"
    },
    "severity": {
      "type": "string"
    },
    "contains": {
      "type": "string"
    },
    "since": {
      "type": "string"
    },
    "windowMinutes": {
      "type": "number"
    },
    "trace": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    },
    "route": {
      "type": "string"
    }
  },
  "required": [
    "artifactId"
  ]
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "phase": {
      "type": "string"
    },
    "artifactId": {
      "type": "string"
    },
    "entries": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "ok",
    "phase",
    "artifactId"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_open_artifact

Return operator and draft URLs for a hosted artifact app.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:read
  • Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "artifactId"
  ]
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "artifactId": {
      "type": "string"
    },
    "openUrl": {
      "type": "string"
    },
    "draftUrl": {
      "type": [
        "string",
        "null"
      ]
    },
    "liveUrl": {
      "type": [
        "string",
        "null"
      ]
    },
    "versionUrl": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ok",
    "artifactId",
    "openUrl",
    "draftUrl",
    "liveUrl",
    "versionUrl"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_delete_artifact_draft

Permanently remove an unpromoted private draft created by this MCP connection after exact-id confirmation.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:delete
  • Tool behavior: read-only: no; destructive: yes; idempotent: not declared; open-world access: yes

Input schema

{
  "type": "object",
  "properties": {
    "artifactId": {
      "type": "string",
      "format": "uuid"
    },
    "confirmArtifactId": {
      "type": "string",
      "format": "uuid",
      "description": "Must exactly match artifactId."
    },
    "planToken": {
      "type": "string",
      "description": "Must match the latest platform_plan_artifact_draft_delete result."
    }
  },
  "required": [
    "artifactId",
    "confirmArtifactId",
    "planToken"
  ]
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "deleted": {
      "type": "boolean"
    },
    "artifactId": {
      "type": "string"
    }
  },
  "required": [
    "ok",
    "deleted",
    "artifactId"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_storybook_access

Return the tenant Storybook preview URL and HTTP MCP server config.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:read
  • Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {}
}

Output schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "storybookUrl": {
      "type": "string"
    },
    "mcpUrl": {
      "type": "string"
    },
    "mcpServers": {
      "type": "object"
    }
  },
  "required": [
    "ok",
    "storybookUrl",
    "mcpUrl",
    "mcpServers"
  ]
}

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.

platform_bedrock_local_token_command

Return local shell commands that generate a short-term Amazon Bedrock bearer token from the user's customer-account AWS profile. Does not mint or return a token.

  • MCP product: Build
  • Required OAuth scope: harness:artifact:read
  • Tool behavior: read-only: yes; destructive: no; idempotent: not declared; open-world access: no

Input schema

{
  "type": "object",
  "properties": {
    "profile": {
      "type": "string"
    },
    "region": {
      "type": "string",
      "default": "us-west-2"
    },
    "expiresInSeconds": {
      "type": "number",
      "default": 3600,
      "maximum": 43200
    }
  }
}

Output schema

No output schema is currently declared by the runtime contract.

Errors and recovery

  • scope_required: reconnect or reauthorize the client with the required OAuth scope shown above.
  • Invalid arguments: correct the request so it matches the input schema before retrying.
  • mcp_tool_timeout: inspect whether the operation completed, then retry only when the operation is safe to repeat.