Topline Docs

Build MCP

Build MCP: Get started

Connect a coding client, inspect a local artifact app, deploy a private draft, validate it, and troubleshoot failures.

Topline Build MCP

External coding harnesses can deploy artifact app drafts through Topline without sending the app directory through model tokens. The local MCP server reads the app from disk, creates or updates the artifact draft, packs a tar.gz bundle, uploads it to the hosted API, and lets Topline run the trusted build, deploy, smoke checks, logs, audit, and cost gates.

Build MCP is for developers using Codex or Claude Code to build an artifact app. Success means the client creates a private draft, Topline validates the rendered app, and an operator receives a review link. Live promotion stays in the Topline artifact UI after that review.

The configured Topline API URL must use HTTPS. Plain HTTP is accepted only for loopback development.

Who this guide is for

Use this guide when the app source is in a local directory and the client needs to package and upload it without placing the source bundle in a model prompt. You need access to Account > Developer Access and a directory where the MCP client can read and write files.

For conversations, documentation, preferences, and company context, use Workspace MCP instead.

Connect your client

  1. Open Developer Access in Topline.
  2. Under Build artifacts, choose Codex or Claude Code.
  3. Copy the no-secret Build setup snippet into the coding harness.
  4. The harness opens the browser. Sign in and approve the requested scopes.
  5. Put an artifact-app.json manifest in the app directory.
  6. Ask the client to call platform_inspect_artifact_app with appDir and review the local package summary without changing Topline.
  7. Call platform_deploy_artifact_app with the same appDir and pass the inspected bundle.sha256 as expectedBundleSha256 so changed source fails locally before a remote draft is created.
  8. Call platform_validate_artifact to inspect Topline's trusted rendered-page smoke evidence before handing the draft to an operator.

The setup snippet is generated for your Topline origin. Copy it from Developer Access instead of typing the origin or protocol version from memory.

Codex

[mcp_servers.topline-build]
command = "npx"
args = ["-y", "@topline-build/harness-mcp"]

[mcp_servers.topline-build.env]
TOPLINE_API_URL = "https://topline.example.com"
TOPLINE_MCP_SURFACE = "build"
TOPLINE_MCP_PROTOCOL_VERSION = "2025-11-25"

Claude Code

{
  "mcpServers": {
    "topline-build": {
      "command": "npx",
      "args": ["-y", "@topline-build/harness-mcp"],
      "env": {
        "TOPLINE_API_URL": "https://topline.example.com",
        "TOPLINE_MCP_SURFACE": "build",
        "TOPLINE_MCP_PROTOCOL_VERSION": "2025-11-25"
      }
    }
  }
}

Complete a first draft workflow

  1. If the directory is empty, call platform_init_artifact_app to create the dependency-free starter. Otherwise add a valid artifact-app.json.
  2. Call platform_inspect_artifact_app and review the files, manifest summary, exclusions, and returned bundle SHA-256.
  3. Call platform_deploy_artifact_app with the same appDir and pass that hash as expectedBundleSha256.
  4. If deployment continues asynchronously, call platform_wait_artifact_deploy with the returned operation details.
  5. Call platform_validate_artifact and review the trusted smoke evidence.
  6. Call platform_open_artifact and send the returned draft or Topline review link to the operator.

If local files change after inspection, inspect again. The expected bundle hash is designed to fail closed rather than upload a different source tree.

Tool guide

  • platform_init_artifact_app: creates a dependency-free starter in an empty local directory.
  • platform_inspect_artifact_app: checks local paths and package boundaries without authentication, upload, or remote draft creation; pass its bundle hash to deploy as expectedBundleSha256, while full manifest validation remains server-side. Keep artifact-app.json below 512 KiB so it fits safely inside the remote create request.
  • platform_deploy_artifact_app: reads artifact-app.json, packs appDir, uploads the bundle, and returns draft deployment status.
  • platform_wait_artifact_deploy: resumes a durable deployment operation and streams server-derived progress.
  • platform_connection_check: completes the one-time Build verification shown in Developer Access.
  • platform_artifact_status: reads recent deployment state for an artifact app.
  • platform_validate_artifact: returns bounded trusted smoke and rendered-page health evidence without a browser session.
  • platform_read_artifact_logs: reads bounded redacted deployment logs.
  • platform_open_artifact: returns Topline, draft, version, promotion, source, and schedule handoff URLs.
  • platform_delete_artifact_draft: permanently removes only an unpromoted private draft created by the same MCP connection, after exact-id confirmation.

Safety boundaries

  • Live promotion is intentionally not an MCP tool in v1. Promote from the Topline artifact UI after review.
  • Manual ovmcp_... connector tokens remain an advanced fallback, but the primary setup path is OAuth with PKCE and browser approval.
  • OAuth approval is audience-bound to /mcp/build; it cannot be reused on the Workspace endpoint.
  • Marketplace/plugin publishing, direct source-query tools, and schedule mutation are separate Topline surfaces. MCP only returns source and schedule handoff URLs. The reserved future scopes are harness:artifact:promote, harness:sources:read, and harness:schedules:write.
  • Uploaded bundles must be tar.gz; symlinks, absolute paths, .. paths, .env*, .git, node_modules, build caches, and oversized bundles are rejected.
  • Local apps may live anywhere under TOPLINE_WORKSPACE_ROOT. The stdio MCP maps ordinary folders to artifact-apps/<manifest-id> for trusted source tracking while preserving existing artifact-apps/... and workspace-root identities.

Troubleshooting

The client cannot start Build MCP

  1. Copy the Build snippet again from Developer Access.
  2. Confirm Node.js and npx are available to the client.
  3. Restart the client so it reloads MCP configuration.
  4. Complete browser OAuth approval when prompted.
  5. Run Verify connection from Developer Access to prove that the intended client, product, and authorization are connected end to end.

Inspection rejects the directory

Use the exact appDir that contains artifact-app.json. Remove symlinks, parent traversal, secret files such as .env*, dependency directories, build caches, and oversized files from the bundle. Keep the manifest below 512 KiB.

Deploy reports a bundle hash mismatch

The source changed after inspection. Do not bypass the check. Inspect the directory again, review the new summary and hash, then deploy with the new expectedBundleSha256.

Authentication or authorization fails

  • 401 means authentication is missing, expired, revoked, or invalid. Complete OAuth again or replace the advanced manual connector token.
  • 403 means the connection lacks a required scope, capability, tenant, or artifact grant. Confirm the intended authorization; do not switch to a broader credential merely to bypass the denial.
  • 404 often means the wrong Topline origin, MCP product, or artifact owner.

Deployment stops or the rendered app is unhealthy

Resume with platform_wait_artifact_deploy, then use platform_artifact_status, platform_validate_artifact, and platform_read_artifact_logs. Keep the deployment ID, timestamp, request ID, and redacted error summary for support. Never include tokens, cookies, .env contents, customer rows, or raw PII.

The draft works but cannot be promoted

That is expected. Call platform_open_artifact, open the Topline review link, and have an operator complete live promotion in the product.

For the complete server comparison and protocol behavior, see the MCP server reference.