Developer Platform

MCP tools for AI clients

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

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, Tasks extension and Skills specification. Extension support must be discovered, never inferred from the base protocol version.

Four identity surfaces, not four interchangeable credentials

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.

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.

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.

Capability review: 2026-09-14. For exact current technical availability, use the generated API Map and first-class module inventory.