MCP Tools

Capsulate MCP now includes deterministic retrieval, aggregation, status, and selected write workflows.

​

IDs

Search/fetch object references use prefixes:

• entity:<uuid>
• canvas:<uuid>
• pattern:<uuid>

Other tools use bare UUIDs for records, proposals, jobs, and contributions.

​

Dates

For tools that accept date filters, use:

• YYYY-MM-DD
• ISO 8601 datetime

​

Server tools

​

server_help

Returns the major Capsulate MCP workflows and tool groups.

​

server_diagnostics

Returns:

• server name/version
• server mode
• a sanitized authenticated user summary from the canonical auth endpoint

​

External research contributions

These tools let your assistant do the research and use Capsulate to store its findings. They do not call a Capsulate model or start automatic research. Start with records_schema and records_find / record_get. Preview and apply the new column, then use finding_context to read the exact version before researching and submitting a finding. External columns support text, number, currency, boolean, date, datetime, email, and url; nested objects, arrays, and enum columns are not supported by this workflow. Each finding addresses one record and field, with up to ten sources. There is no bulk contribution or record creation tool. Use the current record version. Generate one request ID per finding and reuse it with identical content on retries. A found outcome needs a typed value and sources; uncertain and not_found publish evidence without changing a cell. Sources remain labeled agent-supplied, not verified by Capsulate. Check evidenceSaved and valueApplied independently, and read the record for its current value. Column previews may affect multiple Canvases sharing the same pattern. Published external findings are visible in record details in the app, with sources, uncertainty, checked time, and connection attribution. Drafts remain unpublished. A historical finding can differ from the current value; the panel marks that difference.

​

Optional Capsulate research

research_tasks_list, research_task, and research_records read durable research progress. research_assignment_preview / research_assignment_apply configure internal research; research_enqueue reuses matching jobs or retries saving supported findings; research_refresh starts a deliberate new generation with a reusable UUID v4 request ID and fetches current source pages instead of reusing the six-hour cache. research_answer supplies missing information, research_pause controls an assignment, and research_cancel stops one pending/running job. Internal research uses Capsulate’s normal feature, billing, and save rules. Prefer external contributions when your assistant is doing the research itself. Assignment previews use camelCase inputs (canvasId, fieldId, recordIds) and select 1–25 records. Other research tools use the snake_case names shown by server discovery. Assignment Optional publicSearchInputs selects up to eight mapped public product/vendor input keys; it defaults to none. Before applying, show which field values will be sent to public search. Private record context is not implicitly approved for outbound search. Assignment apply requires the saved preview’s proposal_kind; if it reports existingTask, inspect that task. research_task pages findings with nextOffset. Research tools retain complete structured IDs, versions, evidence and cursors even when the text preview is truncated. Keep job IDs for cancellation and Canvas/field IDs for assignments. The app retains full settings and batch finding review. Public-web assignments save supported sourced insights into blank cells automatically and preserve user corrections. New tools offer only auto_supported; legacy review_all configuration remains readable but is not a review-only save permission. Selecting that obsolete mode is rejected. Legacy calculated return deadlines still require explicit review/apply. Investigation completion and source retrieval timestamps are displayed separately. A completed investigation is not proof that a value was saved; inspect its save outcome.

​

Retrieval tools

​

canvases_list

List available canvases in compact form, up to 25 per page. Pass offset (default 0) and follow metadata.next_offset until it is null. metadata.has_more identifies partial results. Canvas URLs open the web app at /canvas/<id>.

​

patterns_list

List available extraction patterns in compact form, up to 25 per page. Pass offset (default 0) and follow metadata.next_offset until it is null.

​

search

Search canvases, patterns, and structured entities. General mailbox search is intentionally not exposed. Canvas and pattern searches return metadata.has_more and metadata.next_offset; follow every page before claiming discovery is complete. Pagination uses a stable ID tie breaker when names or update times match. Changes to the underlying collection between calls can shift offset pages, so enumerate again if the collection changes during discovery. Important inputs:

• query
• type
• limit (1–25)
• offset (0–1,000,000; Canvas and pattern searches only)
• date_from, date_to
• canvas_id, pattern_id

​

fetch

Fetch one Canvas, pattern, or structured entity by id in compact form.

​

bulk_fetch

Fetch many objects in one call.

​

records_schema

Inspect canonical logical-record fields, coverage, type hints, and distinct-key definitions for a Canvas or pattern. field_definitions also expands structured scalar paths such as merchant.name. Use its exact field IDs in the other structured record tools.

​

records_find

Find logical records using typed field filters, selected fields, sorting, and a bounded limit. Each row includes stable record_id; eligible result sets include the server-issued cohort token needed for a safe record_update_preview with latest_results scope.

​

record_get

Fetch one logical record by canvas_id and stable record_id.

​

record_sources

Fetch source extraction fields and limited email metadata attached to one known logical record. This tool does not search unrelated mail or return raw message bodies.

​

records_compare

Compare two to ten logical records side by side with an optional field selection.

​

records_distinct_values

Return the most common values and logical-record counts for one structured field. Optional typed filters narrow the cohort.

​

records_aggregate

Group logical records using the same calculation service as app charts, including saved Canvas display filters, nested scalar fields, reporting currency and bounded-cohort diagnostics. Prefer canvas_id; pattern_id alone must resolve to exactly one owned active Canvas. Both IDs must match when supplied. Explicit date filters/timezone override the corresponding saved filters. Inspect calculation_scope and calculation diagnostics before assuming the cohort is complete.

​

records_timeseries

Compute day, week, or month rollups using the shared Canvas chart calculation service. Set date_field to a declared date/datetime field, or use the default date_received. Canvas/pattern scope, saved filters, reporting currency, timezone, and calculation diagnostics follow the same rules as records_aggregate. All typed record results include record_contract.grain: "logical_record". Source extraction rows are evidence updates and are never silently counted as additional records.

​

canvas_context

Read authoritative Canvas configuration and presentation context, including record grain, extraction guidance, current filters, reporting currency, and widget layout. Large object/array sections are paginated by path, offset, and limit.

​

canvas_conversations_list

List saved Canvas Assistant conversation sessions for one Canvas.

​

canvas_conversation_history

Read an exact page of one saved Assistant conversation. Persisted action artifacts can be traversed with message_id, artifact_path, artifact_offset, and artifact_limit.

​

records_query

Run bounded read-only SQL against the Canvas records table. Each row is one canonical logical record. Include record_id for row-level lists and omit identifiers for aggregate results.

​

source_entities_query

Run bounded read-only SQL against individual source extraction updates for explicit record_ids. Use this for advanced provenance investigation; source-row counts are not logical-record counts.

​

consolidation_history

Fetch tenant-scoped source and change history for a consolidation key or anchor entity.

​

entities_compare

Compare up to five source entities and their extracted fields side by side.

​

canvas_filter_preview

Validate and return a complete proposed display-filter state without silently changing the app UI.

​

canvas_refinement_preview

Prepare a user-visible Canvas field/layout refinement request. Persist an exact confirmed widget specification with canvas_update_widget_spec.

​

canvas_brief

Read the maintained evidence-backed Canvas brief when the feature is available for the account.

​

canvas_memory_list

List evidence-backed operational memory for a Canvas, optionally limited to attention items.

​

analyst_latest

Read the latest cached Canvas analyst insights without starting a new analysis run.

​

attention_count

Count active Radar items across alerts, Canvas occurrences, and operational memory. Optionally set the attention horizon and timezone. The horizon bounds scheduled items; undated operational-memory review work remains included.

​

attention_list

List the actionable Radar feed for “what needs my attention?” requests. Filter by date range or relative date mode, extraction pattern, query, horizon, and timezone. This tool is read-only; date filters bound scheduled items while undated operational-memory review work remains included. Dismiss and resolve actions remain in Capsulate.

​

Logical record tools

​

record_update_preview

Date-qualified targeting uses the account timezone, then the Canvas timezone, then UTC. Supply an optional valid IANA timezone to deliberately override this. Validate field changes and return a version-bound proposal using one explicit scope: record_ids, latest_results, filtered_canvas, all_canvas, latest_limit, or needs_clarification. Include the original user_query and declare whether it contains source filters so Capsulate can independently verify the target cohort. latest_results requires the short-lived server-issued cohort token returned by records_find or records_query; caller-supplied ids cannot claim to be a complete previous result. Host-side selections use record_ids. Always show the proposal to the user before applying it.

​

record_update_apply

Apply the unchanged proposal returned by record_update_preview. Capsulate atomically verifies the record versions, current field values, Canvas field definitions, and source membership. If anything changed after preview, the operation fails without partially updating the cohort.

​

record_update_undo

Undo a successful record_update_apply using its original proposal and returned appliedRecords. Undo fails closed when a newer edit owns one of the affected fields.

​

record_activity

Inspect the current provenance and activity history for one logical record.

​

record_grouping_preview

Perform authoritative membership review and prepare one merge, full unmerge, or partial source unmerge proposal. Nothing is mutated.

​

record_organization_preview

Prepare up to eight independent duplicate-record merge proposals. Confidence controls default selection but never bypasses confirmation.

​

record_grouping_apply

Apply unchanged grouping proposals after confirmation. Capsulate validates current source membership atomically and rejects stale previews.

​

record_grouping_undo

Undo applied grouping actions using their original and applied membership snapshots. Undo fails closed if membership changed again.

​

canvas_memory_update

Confirm, correct, dismiss, or expire one operational-memory item after the exact update is shown to the user.

​

Alert and reminder tools

​

alerts_list

List alerts across the account or for one canvas_id. Filter by lifecycle status, date window, text query, and whether untriggered rules should be included.

​

alert_preview

Validate a condition alert without creating it and return its current baseline. Supported condition types are entity_match, entity_due, and aggregate. Phrase searches use an entity_match condition with query/fallback_query. Use Canvas field ids from records_schema rather than display labels.

​

alert_create

Create one confirmed time or condition alert. Condition alerts should be previewed first. Time alerts use RFC 3339 values in due_at or trigger_at, or calendar dates in due_date or trigger_date. The tool requires confirmed: true and records the source as the assistant.

​

alert_update

Update editable fields on an existing alert. Show the exact patch first; confirmed: true is required. Preview a replacement condition_spec first. The canonical alert service revalidates timing and condition contracts. Recurring alerts are not currently supported.

​

alert_pause

Pause an alert without deleting it. List the alert and receive explicit confirmation first. Paused alerts remain visible with alerts_list using status disabled and can still be resumed in Capsulate.

​

Authoring tools

​

patterns_update_definition

Existing records are preserved, matching the app editor. Validate, normalize, and persist caller-supplied pattern definitions. Eligible state values missing semantic badge tones may be classified with Capsulate’s low-cost model. See Pattern Definitions for the field shape, normalization rules, and validation behavior.

​

patterns_status

Fetch extraction status and recent run history.

​

canvas_create_with_pattern

Create a canvas and its backing extraction pattern together in one call. Supply the definition directly. Template discovery and interactive wizard steps are not exposed. Reuse the optional UUID id on retries to avoid duplicate Canvas creation.

​

canvas_update_widget_spec

Validate, normalize, and persist a widget spec through the canonical save path. Pass expected_updated_at from the Canvas snapshot you reviewed; on conflict, fetch and review again. See Canvas Widget Specs for the canonical shape, supported component families, and validation rules.

​

Response behavior

• Large MCP responses may be truncated to protect the transport.
• Deterministic write tools use canonical backend routes instead of ad hoc save paths.
• Record field and grouping updates require previews and use version/membership-bound atomic apply/undo operations.
• MCP authorization stays in the browser and never exposes provider tokens or credentials.
• Record, Canvas, pattern, memory, and alert mutations require mcp:write; mutation tools require previews or explicit confirmation where applicable.
• Hosted MCP requests emit server-side logs for status and latency.
• List-style tools default to compact responses so AI clients can inspect the data model without blowing up context.