---
title: "Mcp Compute"
method: POST
path: "/api/v1/mcp/compute"
tags: ["mcp"]
---

# Mcp Compute

`POST /api/v1/mcp/compute`

## Request

- Base URL: `https://api.civilquants.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.civilquants.com/api/v1/mcp/compute`
- Auth: none declared

Universal compute dispatcher per canonical schema § 1.

Looks up the requested assembly, applies tier-routing
(TIER_INSUFFICIENT envelope when a free caller targets a paid assembly),
runs the engine + the chosen standard's renderer, and wraps the result
in `MCPResponse[ComputeResult]`. A free caller requesting any standard
other than MMHW is HARD-REJECTED with INVALID_INPUT (56th-fire T1).

Free-tier callers consume daily quota per launch spec § 3.6 (10 calls/day
per IP, resets at UTC midnight). Paid callers bypass the limiter entirely.

Per-tool `@mcp.tool()` decorators with the canonical "CALL THIS WHENEVER"
descriptions from spec § 6.5.5 land in Track B-Infra; this generic route
is the FastAPI sidecar that the fastmcp wrapper will dispatch into.

## Headers

- `authorization` string, nullable

## Request body

- CivilquantsApiRoutesMcpComputeRequest: Request body for the universal /api/v1/mcp/compute entry point. Matches the schema § 1.5 example input pattern: caller specifies the tool name (with or without the `compute_` prefix) plus the arguments dict the engine expects. `standard` is optional (defaults to MMHW — the only standard free-tier callers can use).
  - `tool` string, required: e.g. 'compute_attenuation_tank' or 'attenuation_tank'
  - `arguments` object
  - `standard` 'CESMM4' | 'NRM2' | 'SMM7' | 'MMHW'
  - `freeboard` number, nullable: Optional clearance (m) of the wall top above the retained fill, for retaining walls only. The engine back-calculates the retained height as stem − freeboard. Supplying both freeboard and the retained-height field is rejected.

## Response `200`

Successful Response

- union
  - MCPResponseComputeResult
    - `data` ComputeResult: Schema § 1.1 — the typed payload returned inside `MCPResponse[ComputeResult]`. Free-tier responses omit `drawings` (the downloadable CAD artefact pointers — the paid differentiator); the bridge enforces this. The `audit_trail` and the inline `drawing` preview are present on BOTH tiers (V1 ALIGN / 60th-fire D + C). `text_summary` is bounded to 2000 chars — keeps the LLM-facing summary token-cheap and forces longer narrative into BoQ row descriptions where it belongs. `warnings` is the non-fatal geometry advisory list (both tiers).
      - `assembly_slug` string, required
      - `standard` 'CESMM4' | 'NRM2' | 'SMM7' | 'MMHW', required
      - `parameters_used` ParametersUsed, required: Schema § 1.2 — the parameter snapshot the engine actually used. Splits user-supplied values from engine defaults so customers can see which numbers came from them and which the engine filled in. Every defaulted parameter SHOULD have a corresponding entry in `assumptions` — the bridge layer enforces this when wrapping engine output.
        - `user_supplied` object
        - `engine_defaults` object
        - `assumptions` string[]
      - `boq_rows` BoQRow[], required
        - `work_section` string, required
        - `description` string, required
        - `quantity` number, required
        - `unit` string, required
        - `rate` number, nullable
        - `amount` number, nullable
        - `attribution` string, required
        - `audit_id` string, nullable
      - `totals_summary` TotalsSummary, required: Schema § 1.4 — totals_summary as a typed wrapper around the free-form dict. Wire shape is a flat object (`{"concrete_m3": {...}, "rebar_t": {...}}`). We model it as `RootModel`-equivalent via `model_config(extra="allow")` + a single `__root__`-style `entries` dict. Pydantic v2 recommends `RootModel` for free-form roots; using a wrapper class keeps the import surface uniform with the rest of this module.
        - `entries` object
      - `text_summary` string, required
      - `drawing` DrawingPreview: Schema § 1.6a — inline server-rendered SVG preview of the geometry. The MCP mirror of the web ``/compute`` response's ``drawing`` field (``api.schemas.compute.DrawingRef``): the same on-screen dimensioned drawing both tiers see in the workspace, surfaced on the MCP compute response so a chat client can render it inline (60th-fire item C). This is the on-screen preview — present on BOTH tiers per the free/paid boundary; the downloadable CAD artefacts (DXF / dimensioned PDF) remain the paid differentiator via the export tools. Defined here rather than importing ``DrawingRef`` because the web ``schemas`` package imports back into this module (``schemas.render``), so reusing it would create an import cycle — the MCP wire contract keeps its own copy, the same pattern as ``BoQRow`` / ``DrawingReference``.
        - `svg_b64` string, required
        - `viewbox_x` number, required
        - `viewbox_y` number, required
        - `viewbox_width` number, required
        - `viewbox_height` number, required
        - `entity_count` integer, required
        - `unit_of_drawing` 'm'
      - `drawings` DrawingReference[], nullable
        - `drawing_type` 'section' | 'plan' | 'elevation' | 'isometric' | 'detail', required
        - `format` 'DXF' | 'PDF' | 'SVG', required
        - `url` string, required
        - `sheet_size` 'A1' | 'A2' | 'A3' | 'A4', required
        - `scale` string, required
        - `layers` string[], nullable
      - `audit_trail` AuditEntry[], nullable
        - `id` string, required
        - `boq_row_index` integer, required
        - `derivation` string, required
        - `formula` string, nullable
        - `parameters_referenced` string[]
      - `warnings` ComputeWarning[]
        - `code` string, required
        - `severity` 'info' | 'advisory' | 'caution', required
        - `message` string, required
        - `affected_params` string[]
        - `detail` object
    - `error` ErrorEnvelope: Canonical schema § 0.4 — error payload returned in `MCPResponse.error`.
      - `code` 'RATE_LIMIT_EXCEEDED' | 'TIER_INSUFFICIENT' | 'INVALID_INPUT' | 'SCHEMA_VERSION_MISMATCH' | 'SCHEMA_INVARIANT_VIOLATION' | 'UPSTREAM_TIMEOUT' | 'BACKEND_FAILURE' | 'IP_BLOCKED' | 'RESOURCE_NOT_FOUND' | 'RENDER_FAILURE' | 'OCR_LOW_CONFIDENCE' | 'MANUAL_REVIEW_REQUIRED' | 'ACCEPTANCE_REQUIRED' | 'INVALID_TOKEN', required: Canonical schema § 0.5 catalogue. Each member maps to a documented `recoverable` flag (see `IS_RECOVERABLE`) — clients use the flag to decide retry vs surface.
      - `message` string, required
      - `recoverable` boolean, required
      - `retry_after_seconds` integer, nullable
      - `details` object, nullable
    - `_meta` ResponseMeta, required: Canonical schema § 0.2 — present on every MCPResponse. Required fields: `schema_version`, `request_id`, `issued_at`, `tier`. The free-tier-only fields (`upgrade_hint`, `tos_url`, `warranty_disclaimer`, `tier_upgrade`, `rate_limit_remaining`) are populated by the middleware when `tier == "free"`; absent on paid-tier responses.
      - `schema_version` '1.0.0'
      - `request_id` string, required
      - `issued_at` string, required
      - `tier` 'free' | 'paid', required
      - `document_id` string, nullable
      - `deliverables` DeliverableURLs: Canonical schema § 0.3 — R2 signed URLs (24h TTL).
        - `pdf_url` string, nullable
        - `xlsx_url` string, nullable
        - `dxf_url` string, nullable
        - `docx_url` string, nullable
        - `expires_at` string, required
      - `rate_limit_remaining` integer, nullable
      - `upgrade_hint` string, nullable
      - `tos_url` string, nullable
      - `warranty_disclaimer` string, nullable
      - `scope_boundary` ScopeBoundary: Canonical schema § 0.6 — surfaces what this assembly produces vs not.
        - `produced` string[], required
        - `not_in_scope` string[], required
        - `recommended_companions` string[], nullable
      - `tier_upgrade` TierUpgrade: Canonical schema § 0.7 — present on free-tier responses only.
        - `current_tier` 'free'
        - `available_tiers` TierOption[], required
          - `tier_slug` '7_day_pass' | 'solo' | 'studio' | 'practice', required
          - `display_name` string, required
          - `price_local` number, required
          - `currency` 'GBP' | 'SGD' | 'EUR' | 'USD' | 'CAD' | 'AUD' | 'NZD' | 'MYR', required
          - `billing` 'one_off' | 'monthly' | 'annual', required
          - `unlock_summary` string, required
        - `pricing_url` string
        - `pass_credit` PassCreditOffer: Canonical schema § 0.7 — pass-credit upgrade hook.
          - `amount_local` number, required
          - `currency` string, required
          - `redeemable_until` string, required
          - `applies_to` 'solo_first_month'
      - `hint` string, nullable
      - `output_mode` OutputModeInfo: Surfaces what a trimmed ``output_mode`` withheld from ``data``. A trimmed mode (``summary`` / ``material_schedule`` / ``boq`` / ``boq_with_backup``) withholds already-computed fields to keep the chat payload small. The withheld value reads to a client agent as "capability missing" (the box-culvert "geometry builder isn't firing" scare) rather than "pared for size": ``drawing`` and ``audit_trail`` appear as ``null``, ``boq_rows`` as an empty list ``[]`` (its type forbids ``null``) — both indistinguishable from a genuine absent result. This names the withheld fields and the exact mode that brings each back, so the value is unambiguous. Absent on the default ``full_json`` mode — nothing is withheld, nothing to point at.
        - `mode` 'summary' | 'material_schedule' | 'boq' | 'boq_with_backup', required
        - `omitted_fields` string[], required
        - `retrieve_with` string, required
  - MCPResponseAny
    - `data` unknown
    - `error` ErrorEnvelope: Canonical schema § 0.4 — error payload returned in `MCPResponse.error`.
      - `code` 'RATE_LIMIT_EXCEEDED' | 'TIER_INSUFFICIENT' | 'INVALID_INPUT' | 'SCHEMA_VERSION_MISMATCH' | 'SCHEMA_INVARIANT_VIOLATION' | 'UPSTREAM_TIMEOUT' | 'BACKEND_FAILURE' | 'IP_BLOCKED' | 'RESOURCE_NOT_FOUND' | 'RENDER_FAILURE' | 'OCR_LOW_CONFIDENCE' | 'MANUAL_REVIEW_REQUIRED' | 'ACCEPTANCE_REQUIRED' | 'INVALID_TOKEN', required: Canonical schema § 0.5 catalogue. Each member maps to a documented `recoverable` flag (see `IS_RECOVERABLE`) — clients use the flag to decide retry vs surface.
      - `message` string, required
      - `recoverable` boolean, required
      - `retry_after_seconds` integer, nullable
      - `details` object, nullable
    - `_meta` ResponseMeta, required: Canonical schema § 0.2 — present on every MCPResponse. Required fields: `schema_version`, `request_id`, `issued_at`, `tier`. The free-tier-only fields (`upgrade_hint`, `tos_url`, `warranty_disclaimer`, `tier_upgrade`, `rate_limit_remaining`) are populated by the middleware when `tier == "free"`; absent on paid-tier responses.
      - `schema_version` '1.0.0'
      - `request_id` string, required
      - `issued_at` string, required
      - `tier` 'free' | 'paid', required
      - `document_id` string, nullable
      - `deliverables` DeliverableURLs: Canonical schema § 0.3 — R2 signed URLs (24h TTL).
        - `pdf_url` string, nullable
        - `xlsx_url` string, nullable
        - `dxf_url` string, nullable
        - `docx_url` string, nullable
        - `expires_at` string, required
      - `rate_limit_remaining` integer, nullable
      - `upgrade_hint` string, nullable
      - `tos_url` string, nullable
      - `warranty_disclaimer` string, nullable
      - `scope_boundary` ScopeBoundary: Canonical schema § 0.6 — surfaces what this assembly produces vs not.
        - `produced` string[], required
        - `not_in_scope` string[], required
        - `recommended_companions` string[], nullable
      - `tier_upgrade` TierUpgrade: Canonical schema § 0.7 — present on free-tier responses only.
        - `current_tier` 'free'
        - `available_tiers` TierOption[], required
          - `tier_slug` '7_day_pass' | 'solo' | 'studio' | 'practice', required
          - `display_name` string, required
          - `price_local` number, required
          - `currency` 'GBP' | 'SGD' | 'EUR' | 'USD' | 'CAD' | 'AUD' | 'NZD' | 'MYR', required
          - `billing` 'one_off' | 'monthly' | 'annual', required
          - `unlock_summary` string, required
        - `pricing_url` string
        - `pass_credit` PassCreditOffer: Canonical schema § 0.7 — pass-credit upgrade hook.
          - `amount_local` number, required
          - `currency` string, required
          - `redeemable_until` string, required
          - `applies_to` 'solo_first_month'
      - `hint` string, nullable
      - `output_mode` OutputModeInfo: Surfaces what a trimmed ``output_mode`` withheld from ``data``. A trimmed mode (``summary`` / ``material_schedule`` / ``boq`` / ``boq_with_backup``) withholds already-computed fields to keep the chat payload small. The withheld value reads to a client agent as "capability missing" (the box-culvert "geometry builder isn't firing" scare) rather than "pared for size": ``drawing`` and ``audit_trail`` appear as ``null``, ``boq_rows`` as an empty list ``[]`` (its type forbids ``null``) — both indistinguishable from a genuine absent result. This names the withheld fields and the exact mode that brings each back, so the value is unambiguous. Absent on the default ``full_json`` mode — nothing is withheld, nothing to point at.
        - `mode` 'summary' | 'material_schedule' | 'boq' | 'boq_with_backup', required
        - `omitted_fields` string[], required
        - `retrieve_with` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/civilquants/apis/civilquants-api.md) · [All operations](https://skmtc.dev/civilquants/apis/civilquants-api/llms.txt) · [OpenAPI document](https://skmtc.dev/civilquants/apis/civilquants-api/revisions/84569a3761e1?raw)