Developer Platform

Use BuildWithHQ with DeepSeek Harness

Connect DeepSeek Harness to the curated BuildWithHQ MCP surface with a tested Streamable HTTP patch, app or delegated-user identity, and exact tool-name mapping.

DeepSeek Harness can use BuildWithHQ as a governed application backend through MCP. The same endpoint works for BuildWithHQ builders and API43 headless applications: DSH discovers only the tools allowed by the credential, and every call still passes through app binding, scopes, DataRoles, Locations, record permissions, rate limits, and audit.

1. Install the tested DSH release

DeepSeek Harness is moving quickly, so this guide pins the versions exercised by BuildWithHQ. Install DSH, then add the MCP client to the profile you plan to run.

Re-run initialization, discovery, delegated call, revocation, reconnection, schema, and name-map tests before changing a tested version.

Windows PowerShell

npm install --global [email protected] @deepseek-ai/[email protected]
dsh plugin --profile web add @deepseek-ai/[email protected]

Linux or macOS

npm install --global [email protected] @deepseek-ai/[email protected]
dsh plugin --profile web add @deepseek-ai/[email protected]

2. Copy the Cordis patch

Developer Kit 1.9.2 contains this file at mcp/deepseek-harness.cordis.patch.yml. It contains environment references, not credentials, so the same checked-in patch can be used in development and deployment.

- insert:
    - id: mcp-buildwithhq
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: buildwithhq
        transport: streamable-http
        url: !!js '`https://api.buildwithhq.com/v1/apps/${process.env.BWHQ_SAAS_APP_ID}/mcp`'
        headers:
          Authorization: !!js '`Bearer ${process.env.BWHQ_API_CREDENTIAL}`'
        toolCallTimeoutMs: 60000
        failOnStartupError: true
        reconnect:
          enabled: true
          initialDelayMs: 500
          maxDelayMs: 30000
          maxAttempts: 10

3. Supply the app and credential

$env:BWHQ_SAAS_APP_ID = "<your-saas-app-id>"
$env:BWHQ_API_CREDENTIAL = "<server-held-bwk-or-short-lived-bwu>"
dsh --profile web --patch .\mcp\deepseek-harness.cordis.patch.yml --no-open

Linux or macOS:

export BWHQ_SAAS_APP_ID="<your-saas-app-id>"
export BWHQ_API_CREDENTIAL="<server-held-bwk-or-short-lived-bwu>"
dsh --profile web --patch ./mcp/deepseek-harness.cordis.patch.yml --no-open

The endpoint assembled by the patch is https://api.buildwithhq.com/v1/apps/{saasAppId}/mcp. An app-bound bwk_live_ credential is appropriate only in a trusted server environment. Never place it in browser JavaScript, a page document, a prompt, source control, or a downloadable configuration.

4. Act as the signed-in end user

For a headless browser or user-specific agent, your trusted backend authenticates the person first and exchanges its app credential for a 2-15 minute bwu_live_ delegated token. Request mcp.use plus only the operation scopes that session needs. DSH then calls MCP as that TenantUser; it does not receive an app-wide master key.

{
  "providerKey": "your-auth-provider",
  "externalAccountId": "organization-42",
  "externalSubject": "user-1837",
  "scopes": ["mcp.use", "records.read"],
  "lifetimeMinutes": 10
}

Revocation, expiry, user deactivation, role changes, and location changes are enforced by the server. Because the patch creates a fixed Authorization header when the profile starts, restart the DSH profile after replacing an expired or revoked token.

5. Understand the tool names

BuildWithHQ keeps readable dotted raw names, such as buildwithhq.records.objects.list. DSH permits only letters, digits, underscores, and hyphens and limits public tool names to 64 characters. The tested client therefore exposes that example as:

mcp__buildwithhq__buildwithhq_records_objects_list_46db665ef811

Do not reproduce the normalization algorithm in application code. Use mcp/deepseek-harness-tool-names.json from the kit; it records the exact raw name, DSH-visible name, required scopes, side-effect class, and tested DSH client version for all 40 tools.

First-class module tools

The catalog includes direct secured reads for Universal Inbox, Work Orders, Checklists & Signoffs, Global Search, and AI Insights. Grant the corresponding modules.<slug>.read scope to discover names such as buildwithhq.work_orders.search and buildwithhq.inbox.list. These execute the same application service and stored procedure as the matching REST route.

Why 40 tools instead of all 237 REST operations?

Every registered tool schema consumes model context on every request. Publishing hundreds of nearly adjacent CRUD operations makes tool choice worse and spends tokens before the user asks a question. BuildWithHQ keeps the complete REST surface in OpenAPI and the typed SDK, while MCP presents 40 stable intent-level tools for key modules, records, connectors, inbound endpoints, webhooks, and appliances.

Forty is the registered ceiling, not a promise that every identity sees 40. Discovery is permission-filtered. A Work Orders reader sees its module tools but not Inbox or connector writes; sensitive mutations are hidden unless server policy explicitly approves them.

Connection and recovery behavior

The patch enables fail-fast startup and bounded reconnect settings. With Streamable HTTP, a temporary server or network failure rejects the affected call; a later call can recover without rebuilding the application process. Credential expiry is different: provide a newly exchanged credential and restart the DSH profile so it rebuilds its Authorization header.

Production checklist

• Keep app credentials in a server-side secret store and give end-user agents short-lived delegated credentials.
• Grant mcp.use and the narrow read/write scopes required by the task.
• Confirm tool discovery before asking a model to act; missing tools normally mean missing scope or sensitive-action policy.
• Preserve correlation IDs and review security/audit events for rejected and mutating calls.
• Pin the tested DSH packages. Re-run initialize, discovery, authorized call, delegated call, revocation, and reconnect tests before upgrading DSH.