MCP Overview

Capsulate’s default MCP connection is the hosted server at https://capsulate.app/mcp. Capsulate MCP is not read-only. It now exposes a compact deterministic tool surface for:

• discovery
• structured retrieval
• entity analytics
• Radar attention review
• status checks
• canonical create and update flows

​

What it supports

• Search and fetch
  • Search across canvases, patterns, and structured entities
  • Fetch one structured object or bulk-fetch many
  • Inspect record-scoped source evidence without general mailbox access
• Entity analytics
  • Schema inspection
  • Grouped rollups
  • Time-series analysis
• Authoring workflows
  • Create a canvas and backing pattern together
  • Update pattern definitions deterministically
  • Update widget specs deterministically
  • Preview, apply, and undo logical-record updates and grouping changes
  • Manage operational memory and alerts with confirmation boundaries
• Attention review
  • Count and list the same actionable Radar items shown in Capsulate
  • Filter attention items by date, pattern, query, and timezone

​

Research with your own assistant

Your assistant can add a user-managed column, research selected records with its own tools, and save typed findings and sources using the contribution tools. Capsulate stores the result and connection attribution without running its own research. Sources are labeled agent-supplied and published evidence is visible in external findings panels in app record details. See MCP Tools for the preview, approval, save, and recovery sequence. Capsulate research is a separate optional workflow when you want Capsulate to perform the work. It uses the account’s feature access, billing, workers, and supported-value save rules.

​

Product boundaries

MCP supports record analysis, guarded edits and grouping, Canvas/pattern creation, layout updates, operational memory, and alerts. Radar is available for reading; dismiss and resolve remain in the app. Sharing, native exports, integration account/sync management, mailbox actions, and account administration also stay in the app. Filter/refinement previews alone do not save app state. Briefs and analyst insights can be read; MCP does not start a new analyst run or edit the brief. An MCP connection does not schedule proactive assistant work or deliver host notifications. The assistant host must provide that behavior and support OAuth and the server’s write confirmation.

​

Mental model

• Canvas: a user-facing workspace
• Pattern: the extraction definition behind a canvas
• Entity: extracted structured data from messages
• Record source: an extraction update and limited email metadata supporting a logical record

​

How they relate

• A canvas usually points at one pattern.
• A pattern defines what entity type to extract and which fields to populate.
• A pattern can produce many entities.
• Logical records can be supported by one or more source updates.

If you are using the MCP for the first time, think of the workflow as:

1. Find or inspect canvases and patterns
2. Inspect logical records and record-scoped provenance when needed
3. Create a canvas and pattern together when needed
4. Update pattern definitions or widget specs after creation

​

Hosted MCP

This is the recommended path for MCP clients that support remote HTTP servers.

• Endpoint: https://capsulate.app/mcp
• Auth: OAuth 2.1 with strict S256 PKCE through the normal Capsulate sign-in flow
• Protection: /mcp is behind the same billing and API limiting perimeter as the rest of the app

The assistant supplies the requested definitions and actions. Pattern updates may use a low-cost Capsulate model to classify missing badge tones; optional internal research also uses Capsulate models. External finding contributions do not.

​

Recommended workflow

1. Start with server_help and server_diagnostics
2. Select a Canvas, run records_schema, then use records_find, record_get, and the typed analysis tools
3. Use attention_count and attention_list when the user asks what needs attention
4. Use canvas_create_with_pattern when you want the in-app wizard equivalent
5. Use patterns_update_definition, patterns_status, and canvas_update_widget_spec for deterministic follow-up work

​

Quick decision guide

• If you want a quick inventory of canvases or patterns: use canvases_list or patterns_list
• If you want the evidence behind a known record: use record_sources
• If you want logical records for a Canvas: use records_find
• If you want one object by id: use fetch
• If you already have several ids: use bulk_fetch
• If you want the in-app wizard equivalent that creates a canvas and pattern together: use canvas_create_with_pattern
• If you want to inspect field coverage before grouping or charting: use records_schema
• If you want the actionable Radar feed: use attention_count or attention_list
• If you need the exact pattern contract: see Pattern Definitions
• If you need the exact canvas layout contract: see Canvas Widget Specs
• If you want to edit the saved widget layout later: use canvas_update_widget_spec