Skip to main content
Glama
Sign In
zackscriven

ghl-mcp-server-v2

by zackscriven
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ghl_clientportal_submit_agent_run

Submits a prompt to start an AI agent run that builds or edits project code in the background. Returns a runId for polling progress.

Instructions

CLIENT PORTAL AI BUILDER API (/ai-builder-api) — side-effecting: opens/edits sandboxes and starts builds. Edit a sandbox only once sandbox.status is ready; checkpoint after edits and before starting the run that builds them; 409 means a cloud build owns the sandbox or it is not running. Submit a prompt; the agent runs in the background. Returns runId immediately. A sub-account token builds with its own agent: it writes the code with POST .../sandbox/edit (and registers a React Native app's screens with POST .../sandbox/extension-routes), saves the files with POST .../sandbox/checkpoint, then starts the run with externalAgent: true, which checks, builds and deploys them. Poll GET .../runs/{runId}: problems a passing build still has are in checkProblems.

The builder's own agent executes asynchronously: attempt workspace restore from project's prior run → materialise scaffold (only if no prior workspace) → loop tool calls → preflight pnpm build → flush workspace to GCS → deploy via Cloud Build → managed runtime revision replace → mark ready with a preview URL.

Per-project runtime services receive a stable public app hostname so the iframe URL works without platform-session auth.

Idempotency: callers SHOULD send an Idempotency-Key header on every retry. The server stores (locationId, projectId, key) → runId for 24 h. Same key + same body → the original runId is replayed. Same key + different body → 409 idempotency_conflict. Modeled after standard idempotent POST contracts; safe for browser retries, network blips, and double-click submits.

Attachment scope: when attachmentIds are present, each id is verified against the caller's tenant + project. Cross-project or cross-tenant reuse is rejected with 403 attachment_not_owned. Endpoint: POST /ai-builder-api/projects/{projectId}/runs (Version header: v3; source: v3/clientportal-ai-v3.json) OAuth scopes: clientportal-ai.write

Input Schema

NameRequiredDescriptionDefault
bodyYesRequest body (schema carried verbatim from the official OpenAPI spec).
projectIdYesThe project's id.
Idempotency-KeyNoCaller-generated key (UUID-v4 recommended) that makes this POST safe to retry. Must match the prior request body byte-for-byte on replay. Reused with a different body → `409`.
X-Correlation-IdNoOptional caller-supplied trace id. When omitted, the API mints `cid_<uuid>` and echoes it back via the response `X-Correlation-Id` header. Threaded through audit rows + logs.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.1.0

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations, it discloses side effects ('opens/edits sandboxes and starts builds'), async execution flow, polling behavior via `GET .../runs/{runId}`, idempotency semantics, and cross-tenant attachment rejection (`403`). This is rich behavioral context that an agent needs before invoking a background mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, but it runs long and includes internal pipeline details ('materialise scaffold', 'pnpm build', 'GCS', 'Cloud Build') that are not necessary for selecting or invoking the tool. Useful content is mixed with implementation-level over-detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, nested request body, and lack of an output schema, the description is complete enough: it explains the return value (`runId`), how to poll, idempotency, attachment ownership, and the external-agent workflow. An agent can call it correctly without missing critical context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter in detail. The description reinforces some semantics, such as `externalAgent: true` and idempotency-key behavior, but adds only marginal meaning beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Submit a prompt; the agent runs in the background' and 'Returns `runId` immediately.' It distinguishes this from sibling read tools by making clear this starts a run rather than retrieving one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives concrete usage conditions: edit a sandbox only once `sandbox.status` is `ready`, checkpoint before starting a build, and interpret `409` as a build conflict. It also explains when to set `externalAgent: true`. It does not explicitly name sibling alternatives such as `get_agent_run`, but the workflow context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools