# 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](/docs/workspace-mcp-guide) 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

```toml
[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

```json
{
  "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](/docs/mcp-server-reference).