Skip to content

7.4.3 AI Tool Delivery

This page is an abstract guide for delivering MCP tools that expose Moonitoring product capabilities to agents. It describes the current platform boundaries and the difference between synchronous and asynchronous work.

Repository ownership, deployment commands, alerts, dashboards, and rollback procedures are future decisions. Once tool projects exist, those concrete procedures belong in project-specific runbooks.

Platform responsibilities

Component Responsibility
Product-owned MCP server Exposes a product capability and calls the owning system through an approved contract.
Agent Platform Registers metadata, evaluates capabilities and entitlements, applies confirmation and audit rules, and exposes eligible tools.
Cloud Run service Executes normal bounded tool work.
Cloud Run Job Executes heavyweight or batch work outside a request lifetime.
Cloud SQL PostgreSQL Stores durable job state and result metadata.
Pub/Sub Distributes accepted, progress, and completion events.
Cloud Tasks Controls delivery, rate limits, and retryable per-attempt work when needed.
Workflows Coordinates optional multi-step branching, polling, retries, or approval.
Cloud Storage / BigQuery Stores large artifacts or analytical outputs when required by the product contract.
MooChat WebSocket Notifies connected clients; it is not the source of truth for job state.

Synchronous and asynchronous tools

A synchronous tool completes within the request boundary and returns its result directly.

An asynchronous tool may outlive that boundary. It returns an accepted response containing a durable job_id and a state that the caller can query. The job state and result metadata remain available even if a client disconnects.

MCP progress notifications or task features may improve live protocol behavior, but they do not replace durable state in Cloud SQL or event delivery through Pub/Sub.

Delivery lifecycle

  1. Define the user-facing purpose, input/output contract, failure behavior, and whether the operation is synchronous or asynchronous.
  2. Register the tool with its namespaced name, MCP implementation, description, version, required capabilities, required entitlements, data class, and risk.
  3. Implement the MCP adapter in the product-owned boundary. It must use the owning system's contract rather than reading another system's database.
  4. Apply authorization, feature and entitlement checks, data policy, and required user confirmation at invocation time.
  5. Execute bounded work directly, or create an idempotent durable job record before publishing asynchronous work.
  6. Publish lifecycle events and process them with the appropriate Cloud Run service, Cloud Run Job, Cloud Tasks delivery, or Workflow orchestration.
  7. Persist status, errors, and result metadata. Place large outputs in the appropriate storage service.
  8. Notify MooChat clients over WebSocket when connected. On reconnect, clients query durable state rather than relying on a missed notification.
  9. Resume or refresh the waiting agent conversation according to the product contract, then audit and observe the completed operation.

Asynchronous reference flow

The WebSocket is notification transport only. Durable job state belongs in Cloud SQL or the result store, and completion can be recovered after a client reconnect.

flowchart LR chat[MooChat] --> mcp[Product MCP server] mcp --> job[Durable job record] job --> events[Pub/Sub] events --> worker[Cloud Run service or Job] worker --> state[(Cloud SQL or result storage<br/>durable source of truth)] state --> complete[Pub/Sub completion] complete --> notify[MooChat WebSocket<br/>notification only] complete --> resume[Conversation resumption]

Production principles

  • Design for at-least-once delivery and idempotent execution.
  • Persist acceptance before dispatching asynchronous work.
  • Authorize at execution time, not only when the tool is displayed.
  • Keep confirmation for write operations and dangerous operations.
  • Keep model keys and other provider credentials out of the Agent runtime.
  • Do not allow tools to bypass product contracts with direct database access.
  • Make cancellation semantics explicit; cancellation is not implied by a disconnected WebSocket.
  • Make retries, timeouts, result retention, and error states observable.
  • Return stable identifiers and queryable status for asynchronous work.

Errors and security

Authorization, entitlement, data-class, and risk rules are enforced before execution and rechecked for long-running work. Jobs expose explicit rejected, failed, timed-out, cancelled, and expired outcomes. Retries must not create silent success-shaped fallbacks.

WebSocket delivery is best-effort. Reconnect recovery comes from durable state, not from a notification that may have been missed. Pub/Sub and worker retries are at-least-once, so asynchronous work requires an idempotency key or equivalent deduplication.

Future decisions

The following decisions remain open until tool projects are established:

  • repository ownership and MCP server boundaries;
  • the canonical job state schema and event names;
  • whether MCP task or progress features are enabled for a given client;
  • cancellation and compensation behavior;
  • artifact retention and data residency;
  • dashboards, alerts, SLOs, and on-call ownership;
  • CI/CD, rollout, and rollback procedures.