---
title: "MCP tools for AI clients"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/mcp-tools.html"
reviewed_at: "2026-09-14"
authority: Official
---

# MCP tools for AI clients

Expose approved API-backed application capabilities to MCP-compatible AI clients under the same permission envelope.

## In brief

- **Transport:** Stateless Streamable HTTP
- **Catalog:** 43 permission-filtered tools
- **Scopes:** mcp.use + tool scope

Model Context Protocol (MCP) gives AI clients a standard way to discover and call tools. BuildWithHQ's opportunity is to generate those tools from the application capabilities that already exist instead of maintaining a separate AI-only integration layer.

## What becomes a tool

An application's MCP catalog can be assembled from approved capabilities such as:

- permission-aware record search and retrieval;
- safe record actions and registered data operations;
- published workflows that are allowed to be started by the caller;
- approved container/appliance endpoints with declared schemas; and
- AI-specific actions that are explicitly enabled for the user's role.

## Generated, not privileged

MCP is a protocol adapter over the same application service layer used by REST. Tool discovery itself is filtered: if an identity cannot invoke a capability, that capability is not offered.

## Current endpoint

### Protocol compatibility and evidence

The current Release implementation uses the reviewed official ModelContextProtocol.AspNetCore 2.2.0 package in explicit stateless mode. On September 22, 2026, public release `1.20.14-task34l-mcp-conformance-20260922-v1` passed authenticated HTTPS probes for `2026-07-28` discovery and listing without initialization/session IDs, required-header mismatch rejection, legacy `2025-06-18` initialization, wrong-app and missing-scope catalog isolation, continuation rejection, and credential revocation. Public release `1.20.15-task34n-governed-skills-20260922-v2` added governed Skills. Release `1.20.16-task34m-mcp-tasks-20260922-v2` advertises the reviewed Tasks extension and passed a 12-check public journey covering capability discovery, REST and MCP reads, effective and requested cancellation, stale-revision rejection, worker-boundary cancellation, read-only denial, cross-task/cross-app rejection, cleanup, and exact release identity. These are bounded interoperability results rather than a claim that every client or optional extension is certified.

**Advertised extensions:** governed Skills and durable installed-service Tasks. Skills are available through negotiated `skills/list`, `skills/get`, and digest-bound `resources/read`. Tasks are available through negotiated `tasks/get`, `tasks/update`, and `tasks/cancel`; every call reauthorizes, and installed-service `tasks/update` cannot invent an unsupported `input_required` state. These are protocol methods, not entries in the curated MCP tool-name map. BuildWithHQ tools do not currently accept MRTR continuations: payloads containing `requestState` or `inputResponses` fail closed and cannot approve or replay a mutation. Permission-filtered catalogs return `cacheScope: private`, `ttlMs: 0`, and `Cache-Control: private, no-store`; clients must not reuse a catalog across an app, organization, user, scope set, or approval revision.

**Authentication boundary:** the MCP endpoint accepts the Developer API's app-scoped bearer credential or a short-lived delegated-user credential. BuildWithHQ does not currently claim MCP authorization-server metadata, dynamic client registration, CIMD, or OAuth interoperability certification. The `oauth_connections.*` tools configure external provider connections; they are not MCP client authorization.

See the official [2026-07-28 release](https://blog.modelcontextprotocol.io/posts/2026-07-28/), [Tasks extension](https://tasks.extensions.modelcontextprotocol.io/specification/draft/tasks)  and [Skills specification](https://github.com/modelcontextprotocol/ext-skills/blob/main/specification/stable/skills.mdx). Extension support must be discovered, never inferred from the base protocol version.

### Four identity surfaces, not four interchangeable credentials

| Surface | Authority and current status |
| --- | --- |
| Builder Account MCP | Planned builder-management adapter. Builder-owned apps, templates and releases need builder authorization; an app key cannot substitute for it. |
| Developer VM MCP | Planned workspace adapter. Repository, build and sandbox permissions remain separate from production tenant permissions; deployment requires explicit policy. |
| SaaS Application MCP | Available app-bound endpoint with server-held app credentials, tool scopes and per-app sensitive-tool approval. |
| End-Customer MCP | The same app endpoint accepts short-lived delegated TenantUser credentials; DataRole, location and record authorization remain server-derived. No independent end-customer endpoint is claimed. |

### Durable Tasks and governed Skills

Durable Tasks currently project installed-service invocation state through REST and MCP without creating a second execution queue. The invocation ID is the task ID. Status requires `appliances.read`; cancellation requires `appliances.invoke` and can report `requested`, `effective`, or `too_late`. An optional revision fence rejects stale cancellation, and committed native effects are never described as undone. Workflow and AI-job projections remain future mappings. Governed Skills serve exact-version, digest-verified resources at builder, SaaS application, tenant organization, user, and GoClaw scopes. A delegated active tenant owner can assign an existing immutable Skill version to that organization’s GoClaw through the REST API. Skill instructions and dependency declarations never grant permissions, tools, records, or approval authority.

The stateless Streamable HTTP endpoint is `/v1/apps/{saasAppId}/mcp`. The API credential must carry `mcp.use` plus the ordinary scope required by each discovered tool, such as `records.read`, `webhooks.write`, or `appliances.invoke`.

The generated OpenAPI contract publishes the transport as POST operation `developerMcpInvoke` with an opaque JSON-RPC request/response envelope. `catalog/operations.json` publishes `requiredScopes: ["mcp.use"]`; the generated 43-tool name map supplies each tool's additional operation scope.

[Connect DeepSeek Harness](deepseek-harness.html) [Download the tested patch](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.59.zip)

## Tool contracts

`mcp/deepseek-harness-tool-names.json` schema version 2 publishes every tool's stable name, DSH-visible name, required arguments, scopes, side-effect class, and tested client version. Sensitive mutations additionally publish an `approval` object containing the exact capability key, required Builder permission, and management surface. The two concurrency-fenced module writes include complete JSON input schemas.

| Tool | Required arguments | Per-app approval |
| --- | --- | --- |
| `buildwithhq.checklists.toggle_item` | `checklistRunItemId`, `expectedRevision`, `nextChecked` | `checklists.toggle_item`; approver needs `CanManageApiKeys` |
| `buildwithhq.work_orders.update_status` | `recordId`, `expectedUpdatedUtc`, `status` | `work_orders.update_status`; approver needs `CanManageApiKeys` |

Each tool has a stable name, description, JSON input schema, output schema, required permission, side-effect classification, and — for sensitive mutations — an app-specific approval policy. Read tools and write tools are visibly distinguishable to both AI clients and users.

## Approve sensitive tools for one app

1. Open the Builder Console and select the SaaS app.
2. Open **Manage API clients**.
3. Under **MCP sensitive tools**, review the tool name, effect, and required API scope.
4. Select **Approve**. Revoke it from the same screen when the agent no longer needs it.

Approval applies only to the selected SaaS app. A credential must still carry `mcp.use` and the tool's exact required scope. Approved tools become discoverable on the next stateless MCP request; revoked tools disappear on the next request. Every approve and revoke action writes a correlated builder audit row.

## Auditability

Every mutation performed through MCP should carry correlation and actor context into the normal application audit path. For container-backed tools, the platform can also record the resolved endpoint identity and invocation outcome so an administrator can explain what code actually ran.

## First-class module tools

Nine curated reads expose Universal Inbox, Work Orders, Checklists & Signoffs, Global Search, and AI Insights directly. Two sensitive writes, `buildwithhq.checklists.toggle_item` and `buildwithhq.work_orders.update_status`, call the same secured application services and stored procedures as their REST routes. They require the exact module write scope, preserve optimistic-concurrency tokens, and remain hidden until a permitted builder approves them for that SaaS app.

Note

The current catalog contains 43 tools mapped to shared capability adapters. buildwithhq.services.list dynamically returns installed endpoint schemas under appliances.read; invocation remains separately protected. Read, mutating, and sensitive side effects are classified; sensitive capabilities are default-deny until a permitted builder approves each capability for that SaaS app.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/mcp-tools.html).