# Well (remote · api.wellapp.ai)

Connect your AI to your Well financial data - invoices, companies, contacts.

- Trust score: 79/100 (medium)
- Change this week: +9
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `api.wellapp.ai`: 79/100 (this document), [markdown](https://verifymcp.io/servers/wellapp-ai-well-mcp/v1-mcp.md), [page](https://verifymcp.io/servers/wellapp-ai-well-mcp/v1-mcp)

## Channel facts

- Endpoint: `https://api.wellapp.ai/v1/mcp`
- Transports: `streamable-http`
- Auth: `none`
- Version: `0.2.1`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Endpoint Security**: 89/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - Authorisation is enforced on tool calls, but the challenge carries no valid RFC 9728 metadata, so a client cannot discover where to get a token.
  - HTTPS is enforced; there's no plaintext access path.
  - The HSTS (Strict-Transport-Security) header is present.
  - DNSSEC check failed: this domain isn't protected by DNSSEC.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 75/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 9239 tokens (~355/item across 26 items; 25 tools + 1 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 98/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 93% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.
  - Supports UI / widget rendering.

## Install

### Claude

```bash
claude mcp add --transport http wellapp-ai-well-mcp https://api.wellapp.ai/v1/mcp
```

### Codex

```toml
[mcp_servers.wellapp-ai-well-mcp]
url = "https://api.wellapp.ai/v1/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "wellapp-ai-well-mcp": {
      "type": "remote",
      "url": "https://api.wellapp.ai/v1/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add wellapp-ai-well-mcp --url https://api.wellapp.ai/v1/mcp --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  wellapp-ai-well-mcp:
    url: "https://api.wellapp.ai/v1/mcp"
```

### Other

```json
{
  "mcpServers": {
    "wellapp-ai-well-mcp": {
      "type": "http",
      "url": "https://api.wellapp.ai/v1/mcp"
    }
  }
}
```

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 79, +1)

No change was recorded against any check on this day. Stability & Change Management went from 20 to 23. That category is still filling its 30-day observation window: 6 days of observed history at the previous scan, 7 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-31 (score 78, +6)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 72, +1)

No change was recorded against any check on this day. Stability & Change Management went from 10 to 13. That category is still filling its 30-day observation window: 3 days of observed history at the previous scan, 4 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-29 (score 71, 0)

- [security] Resource “Well” now points somewhere else: ui://well/widget/d34ccf63 → ui://well/widget/87d83ec7
- [functional regression] Schema quality: 6935 → 8721
- [functional] New tool “well_get_cost_structure”
- [functional] New tool “well_get_runway”
- [functional] New tool “well_resolve_register_diff_gap”
- [functional] New tool “well_run_register_diff”
- [functional] New tool “well_resolve_reconciliation_task”
- [functional] New tool “well_get_cash_position”

### 2026-07-28 (score 71, +1)

No change was recorded against any check on this day. Stability & Change Management went from 3 to 7. That category is still filling its 30-day observation window: 1 days of observed history at the previous scan, 2 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-27 (score 70, +1)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-26 (score 69)

First indexed and scored.

## MCP tools (25)

### `well_get_schema` (~526 tokens)

Get Schema

Discover available data types and fields.

USAGE:
\- well_get_schema() → List ALL available roots, including the accounting graph (ledger_accounts, journals, journal_entries) plus account_balances, tax_rates, exchange_rates — query these for real financial statements (compte de résultat / balance sheet) instead of reconstructing them from raw invoices
\- well_get_schema({ root: "invoices" }) → List all available fields for invoices

WORKFLOW:
1\. Call well_get_schema(root) to see available fields
2\. Pick the fields you need for your task (typically 5-15)
3\. Call well_query_records with those specific fields

Returns fields with path, type, and (when documented) semantic context:
\- { path: "invoices.grand_total", type: "numeric", context: "Total invoice amount incl. tax in the document currency...", enrichment: "AI extraction" } → use _eq, _gt, _lt, etc.
\- { path: "invoices.local_currency", type: "enum" } → use ONLY _eq, _neq, _in, _nin, _is_null
\- { path: "invoices.issuer.name", type: "text" } → use _eq, _like, _ilike, etc.

\- "context" (when present) explains what the field MEANS in the domain and how it's used — read it to pick the right field and write correct filters.
\- "enrichment" (when present) is the value's provenance (e.g. "Bank sync", "AI extraction", "System generated", "Derived", "Manual").
Use the type to choose the right whereClause operators in well_query_records.
To use in well_query_records, convert path to array:
"invoices.issuer.name" → ["invoices", "issuer", "name"]

Input parameters:

- `depth` (number): Relationship depth: 0=scalars only, 1=direct relations (default), 2=nested, 3=level-3 graph
- `root` (string): Entity root to inspect. Omit to list every available root (call well_get_schema() with no argument first). Includes the accounting graph (ledger_accounts, journals, journal_entries) alongside compani…
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `error` (string)
- `fields` (array)
- `root` (string)
- `roots` (array)
- `success` (boolean)
- `total` (number)

### `well_query_records` (~1433 tokens)

Query Records

Query records from Well's database.

⚠️ WORKFLOW:
1\. To SHOW the user a table of a record type, omit `fields` — you get the root's
   display view in the Well web app's column order, trimmed on the widest roots to
   the columns that fit a chat-width table. Prefer this whenever the user asks to
   see/list/browse records rather than to answer a question about one specific
   attribute. Ask for `fields` explicitly when you need a column it omits.
2\. To answer a targeted question, call well_get_schema(root) FIRST to discover
   available fields, then select ONLY the fields you need (5-15 typically).

ROOTS (read-only — all 32): companies, people, connectors, invoices, documents, transactions, accounts, payment_means, workspace_connectors, memberships, cards, checks, ledger_accounts, journals, journal_entries, tax_rates, exchange_rates, invoice_transactions, categories, account_balances, tasks, workspaces, invoice_payment_means, chat_conversations, blueprint_runs, workspace_connector_sync_logs, media, emails, phones, web_links, locations, invoice_items
(The accounting graph — ledger_accounts, journals, journal_entries — and balances/rates are read-only projections owned by the sync/posting pipelines; query them for financial context, you cannot create/update them here. Sub-resources like emails/phones/locations are usually richer when read via their parent company/person.)

CONNECTED TOOLS: do NOT use this tool to show the user what they have connected — call well_list_connectors instead. It owns that job: connection status, and an install link for anything not connected yet. Query root "workspace_connectors" here only for genuine RECORD-level needs — reading sync timestamps, filtering connections, joining them with other roots. ("connectors" is the installable catalog; "workspace_connector_sync_logs" is per-sync history.)

Well already syncs the providers' data into the roots above — invoices, transactions, accounts, the accounting graph. ALWAYS read it from here. we…

Input parameters:

- `allFields` (boolean): If true, automatically fetches all scalar fields from schema. No need to specify fields.
- `cursor` (string): Opaque cursor for the next page. Omit for the first page, then pass nextCursor from the previous response.
- `fields` (array): Array of field paths. Each path is an array starting with root name. Omit to get the root's default view (the columns the Well web app shows) — the right choice when displaying records to the user.
- `limit` (number): Max records to return (default 50, max 500)
- `orderBy` (object): Sort results by a field. Example: { field: "grand_total", direction: "desc" }
- `root` (string, required): The entity type to query — any of the 32 read-only roots (companies, people, connectors, invoices, documents, transactions, accounts, payment_means, workspace_connectors, memberships, cards, checks,…
- `whereClause` (object): Hasura-style filter object. Operators: _eq, _neq, _gt, _gte, _lt, _lte, _like, _ilike, _in, _nin, _is_null. Example: { "status": { "_eq": "unpaid" } }
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `columnMeta` (object): Per-column field meaning, keyed by the same column paths as the rows. `context` = what the field means; `enrichment` = how the value is sourced (e.g. Bank sync, AI extraction). Only documented column…
- `columns` (array): The materialized columns in display order, with each composite substituted in place of the source fields it consumed. A row object's key order does not preserve this — the flattener appends reconstru…
- `error` (string)
- `nextCursor`: Cursor for the next page. null means last page.
- `records_url`: Login-gated deep link to the FULL web-app records table for this root (real DataTable: composites, inline editing, resize/pin). Hand to the user to open the records view in one click. Null when no wo…
- `returned` (number): Number of rows returned
- `rows` (array): Query results
- `success` (boolean)
- `totalCount` (number): Total matching records

### `well_create_company` (~234 tokens)

Create Company

Create a new company in the current workspace.

Use this tool when the user asks to create, add, or register a new company.

REQUIRED: name
OPTIONAL: description

After creation, enrichment (logo, domain, industry, tax ID, description fill-in)
runs asynchronously in the background. The new company is available immediately
for follow-up actions, but enriched fields may take a few seconds to populate —
re-query after a brief delay to see them.

Returns { success: true, company_id, name } on success, or { success: false, error } on failure.

Input parameters:

- `description` (string): Brief company description
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `name` (string, required): Company name (required)
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `company_id` (string)
- `error` (string)
- `name` (string)
- `success` (boolean)

### `well_create_person` (~227 tokens)

Create Person

Create a new person (contact) in the current workspace.

Use this tool when the user asks to add, create, or register a new contact,
employee, or person.

REQUIRED: first_name
OPTIONAL: last_name, job_title

After creation, enrichment runs asynchronously in the background.

Returns { success: true, person_id, full_name } on success, or
{ success: false, error } on failure.

Input parameters:

- `email` (string)
- `first_name` (string, required): First name (required)
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `job_title` (string): Job title
- `last_name`: Last name (optional)
- `phone` (string)
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `error` (string)
- `full_name` (string)
- `person_id` (string)
- `success` (boolean)

### `well_update_company` (~472 tokens)

Update Company

Update an existing company in the current workspace.

Use this tool when the user asks to change, fix, rename, or edit a company's
fields.

REQUIRED: company_id
OPTIONAL (only include fields the user wants changed): name, description,
  domain, registered_name, trade_name, tax_id_value, tax_id_type,
  registry_country (ISO 3166-1 alpha-2, e.g. "FR"), business_type,
  registered_value, registry_name, locale (ISO 639-1 two-letter language
  code, e.g. "en", "fr" — not "en_US").

NOT CHANGEABLE via this tool: emails, phones, locations, linked people, media.
Those require dedicated tools (not yet available).

Returns { success: true, company_id, name } on success, or
{ success: false, error } on failure.

Input parameters:

- `business_type`: Business type / legal form
- `company_id` (string, required): The UUID of the company to update (required)
- `description`: Brief company description; pass null to clear
- `domain`: Primary website domain (e.g. acme.com)
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `locale`: Preferred language as an ISO 639-1 two-letter code (e.g. en, fr, de). Pass null to clear.
- `name` (string): Company name
- `registered_name`: Official registered legal name
- `registered_value`: Registry identifier value
- `registry_country`: ISO 3166-1 alpha-2 country code of the registry (e.g. FR, US)
- `registry_name`: Registry name
- `tax_id_type`: Tax identifier type (VAT, SIRET, EIN, ...)
- `tax_id_value`: Tax identifier value (VAT, SIRET, EIN, ...)
- `trade_name`: Trading name / DBA
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `company_id` (string)
- `error` (string)
- `name` (string)
- `success` (boolean)

### `well_update_person` (~258 tokens)

Update Person

Update an existing person (contact) in the current workspace.

Use this tool when the user asks to change, fix, rename, or edit a person's
fields.

REQUIRED: person_id
OPTIONAL (only include fields the user wants changed): first_name, last_name,
  job_title.

NOT CHANGEABLE via this tool: emails, phones, locations, linked companies,
media. Those require dedicated tools (not yet available).

Returns { success: true, person_id, full_name } on success, or
{ success: false, error } on failure.

Input parameters:

- `first_name` (string): First name
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `job_title`: Job title; pass null to clear
- `last_name` (string): Last name
- `person_id` (string, required): The UUID of the person to update (required)
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `error` (string)
- `full_name` (string)
- `person_id` (string)
- `success` (boolean)

### `well_delete_company` (~201 tokens)

Delete Company

Delete a company from the current workspace (soft delete).

Use this tool when the user asks to delete, remove, or archive a company.

REQUIRED: company_id

This soft-deletes the company and its company_person relationships.
Linked people records themselves are NOT deleted. Invoices and documents
referencing the company are preserved.

Returns { success: true, company_id } on success, or
{ success: false, error } on failure.

Input parameters:

- `company_id` (string, required): The UUID of the company to delete (required)
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `company_id` (string)
- `error` (string)
- `success` (boolean)

### `well_delete_person` (~202 tokens)

Delete Person

Delete a person (contact) from the current workspace (soft delete).

Use this tool when the user asks to delete, remove, or archive a contact.

REQUIRED: person_id

This soft-deletes the person and its company_person relationships.
Linked companies themselves are NOT deleted. The authenticated user cannot
delete their own person record.

Returns { success: true, person_id } on success, or
{ success: false, error } on failure.

Input parameters:

- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `person_id` (string, required): The UUID of the person to delete (required)
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `error` (string)
- `person_id` (string)
- `success` (boolean)

### `well_update_invoice` (~609 tokens)

Update Invoice

Update an existing invoice in Well.

Call well_get_schema("invoices") to discover all available fields.

REQUIRED: invoice_id
OPTIONAL (only pass fields you want changed):
  \- reference_number, issue_date (ISO date), due_date (ISO date)
  \- status (draft | issued | paid | canceled)
  \- terms, description
  \- grand_total, items_total, tax_total (numbers)
  \- local_currency (ISO 4217 three-letter code, e.g. "EUR", "USD")
  \- document_type_code (UN/CEFACT 1001 code, e.g. "380")
  \- billing_context (e.g. subscription, one_time, project, ...)
  \- issuer_company_id / receiver_company_id (uuid to set, null to clear,
    omit to leave unchanged)

Cannot change line items, payment_means, or document attachment via this tool.

Input parameters:

- `billing_context`: Billing context / business model; pass null to clear
- `description`: Free-form description; pass null to clear
- `document_type_code`: UN/CEFACT 1001 document type code (e.g. 380 for commercial invoice); pass null to clear
- `due_date`: Payment due date (ISO 8601); pass null to clear
- `grand_total`: Total invoice amount including tax; pass null to clear
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `invoice_id` (string, required): The UUID of the invoice to update
- `issue_date`: Issue date (ISO 8601, e.g. 2026-04-27); pass null to clear
- `issuer_company_id`: Issuer company UUID. Omit = no change, null = clear, uuid = set.
- `items_total`: Sum of line items before tax; pass null to clear
- `local_currency`: ISO 4217 three-letter currency code (e.g. EUR, USD); pass null to clear
- `override_version` (integer): Required when payment_status is present — current override_version for CAS
- `payment_status` (string): User-driven payment_status override — requires override_version (CAS)
- `receiver_company_id`: Receiver company UUID. Omit = no change, null = clear, uuid = set.
- `reference_number`: Invoice reference number (e.g. INV-2026-001); pass null to clear
- `status` (string): Invoice lifecycle status
- `tax_total`: Total tax amount; pass null to clear
- `terms`: Payment terms text; pass null to clear
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `error` (string)
- `invoice_id` (string)
- `reference_number`
- `success` (boolean)

### `well_delete_invoice` (~166 tokens)

Delete Invoice

Delete an invoice from Well (soft delete).

REQUIRED: invoice_id

Soft-deletes the invoice. Linked line items and payment_means rows are NOT
cascade-deleted — they remain in the database, orphaned. The delete is
reversible only at the database level.

Input parameters:

- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `invoice_id` (string, required): The UUID of the invoice to delete
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `error` (string)
- `invoice_id` (string)
- `success` (boolean)

### `well_add_contact_channel` (~342 tokens)

Add Contact Channel

Add a contact channel to a company or person.

Wraps the resource-scoped REST endpoints (POST /v1/{companies,people}/:id/{emails,phones,web-links,locations}).

channel + the matching value field:
  \- email     → value.email
  \- phone     → value.e164_number   (E.164; a leading "+" is added if missing)
  \- web_link  → value.url           (+ optional value.platform, default "website")
  \- location  → value.city, value.country (+ optional address_line1/2, region, postal_code)
value.label is optional (defaults to "work").

NOTE: adding a phone is supported on a PERSON but NOT on a company (no endpoint) —
that combination returns a clear error. To READ existing channels, use
well_query_records on the parent (companies/people) or the channel root.

Input parameters:

- `channel` (string, required): Channel to add: email | phone | web_link | location
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `parent` (string, required): Parent record type: company or person
- `parent_id` (string, required): UUID of the parent company or person
- `value` (object, required): Channel value — fill the field(s) for the chosen channel
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `channel` (string)
- `error` (string)
- `parent` (string)
- `success` (boolean)

### `well_remove_contact_channel` (~239 tokens)

Remove Contact Channel

Remove a contact channel from a company or person.

Wraps the resource-scoped DELETE endpoints (DELETE /v1/{companies,people}/:id/{emails,phones,web-links,locations}/:channelId).

Pass channel_id = the UUID of the specific channel row to remove (NOT the parent).
Find it by reading the parent with well_query_records and selecting the channel's id field.

Input parameters:

- `channel` (string, required): Channel to remove: email | phone | web_link | location
- `channel_id` (string, required): UUID of the specific channel row to remove
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `parent` (string, required): Parent record type: company or person
- `parent_id` (string, required): UUID of the parent company or person
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `channel` (string)
- `error` (string)
- `parent` (string)
- `success` (boolean)

### `well_get_entity` (~289 tokens)

Get Entity (with sub-resources)

Read ONE entity with its sub-resources nested in a single call.

Convenience over well_get_schema + well_query_records: resolves the field paths
for you and returns the single record with its related data expanded.

depth (relation-nesting BOUNDARY, 1-3, default 1):
  1 = the entity + its direct sub-resources (emails, phones, locations, …)
  2 = + the sub-resources' related scalars
  3 = the full level-3 graph (LARGER payload — use when you need the whole picture)
Stops at depth 3. Aggregates are excluded. Each child collection is
capped at 50 rows; for a full list or to page a large child
collection, use well_query_records on that child root instead.

Input parameters:

- `depth` (integer): Relation-nesting boundary 1-3 (default 1).
- `id` (string, required): The entity's public UUID (the value of its *_id field, e.g. company_id)
- `root` (string, required): Entity type, e.g. companies | people | invoices | transactions
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `columnMeta` (object): Per-column field meaning ({context, enrichment}) for documented columns — read this to interpret the entity's values.
- `depth` (number)
- `entity`
- `error` (string)
- `fields_selected` (number)
- `found` (boolean)
- `success` (boolean)

### `well_list_connector_tools` (~283 tokens)

List Connector Tools

Discover the actions a connected provider exposes (e.g. "what can I do with Attio?").

WORKFLOW:
1\. well_list_connectors() → pick the ENABLED provider (connection_status: "enabled") and read its workspace_connector_id directly off the row.
2\. well_list_connector_tools({ workspace_connector_id }) → the actions that provider offers (name + description + input schema).
3\. well_invoke_connector_tool({ workspace_connector_id, tool, args }) → run one, shaping args from the input schema returned here.

Use this whenever you don't already know a connector's tool names — never guess them.

Every response also carries reconnect_url: a deep link to the connector's setup page in the web app. When success is false or status is "need_reconnect" (the provider's token is stale/revoked, so no tools come back), give the user reconnect_url so they can re-authenticate the connector. Surface it as a clickable link; never invent connector URLs.

Input parameters:

- `workspace_connector_id` (string, required): The connected provider's workspace_connector_id (from well_list_connectors).
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `connector_slug` (string)
- `error` (string)
- `reconnect_url` (string)
- `status` (string)
- `success` (boolean)
- `tools` (array)
- `total` (number)

### `well_invoke_connector_tool` (~395 tokens)

Invoke Connector Tool

Run one tool on a connected provider's own MCP server (e.g. create a record in Attio), on behalf of this workspace's connection.

Use this ONLY for an action the user explicitly asked to take on that provider. It is NOT a way to read financial data: Well already syncs invoices, transactions, accounts and the accounting graph from every connected provider — read those with well_query_records instead of calling a provider's own list/read tools.

WORKFLOW:
1\. well_list_connectors() → pick the ENABLED provider (connection_status: "enabled") and read its workspace_connector_id directly off the row.
2\. well_list_connector_tools({ workspace_connector_id }) → the live tool names + input schemas that connection actually exposes right now.
3\. well_invoke_connector_tool({ workspace_connector_id, tool: "<one of the names from step 2>", args: { ... } }).

Only works on connectors that expose an MCP server (e.g. Attio, Notion, Linear) and whose connection is enabled. Returns the provider's tool result, or { success: false, error } if the tool failed / is not granted.

Input parameters:

- `args` (object): Arguments object passed straight to the provider tool. Omit if the tool takes none.
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `tool` (string, required): The provider tool name to run (one of the connector's available_tools).
- `workspace_connector_id` (string, required): The connected provider's workspace_connector_id (from well_list_connectors).
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `error` (string)
- `error_code` (string)
- `result`
- `success` (boolean)
- `tool` (string)

### `well_create_invoice_from_data` (~335 tokens)

Create Invoice From Data

Create an invoice in Well from data you extracted by reading an invoice (your own OCR) — you send the structured fields, not the file.

Well persists the invoice + its line items + payment means using the same pipeline as uploaded documents. Fill every field you can read from the document:
\- issuer / receiver: { name (required), domain?, tax_id? }
\- reference_number, issue_date (YYYY-MM-DD), due_date? (YYYY-MM-DD), currency (ISO 4217)
\- totals?: { items_total?, tax_total?, grand_total }
\- line_items[]: { name, quantity?, unit_price, currency?, tax_rate? }
\- payment_means?[]: { type, iban?, bic?, scheme? }

Input parameters:

- `currency` (string, required): ISO 4217 (3 letters).
- `due_date` (string): ISO 8601 YYYY-MM-DD.
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `issue_date` (string, required): ISO 8601 YYYY-MM-DD.
- `issuer` (object, required)
- `line_items` (array, required)
- `payment_means` (array)
- `receiver` (object, required)
- `reference_number` (string, required)
- `totals` (object)
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `document_id` (string)
- `error` (string)
- `invoice_id` (string)
- `invoice_item_count` (number)
- `payment_means` (number)
- `reference_number`
- `success` (boolean)

### `well_list_workspaces` (~246 tokens)

List Workspaces

List the workspaces this connection is authorized to access.

Use this FIRST when a single token may cover more than one workspace. Each entry has:
\- workspace_id: pass this as the workspace_id argument on other tools to target one workspace.
\- workspace_name: human-readable name (null if it can't be resolved).
\- is_primary: true for the token's default workspace (used when you omit workspace_id on a write).
\- identity: the company behind the workspace (registered name, trade name, registry number, country, website, currency, fiscal year start), so two similarly-named workspaces can be told apart. Every field is null when the workspace has no accounting settings yet. Tax identifiers are deliberately not included.

When the token authorizes a single workspace you can omit workspace_id everywhere; when it authorizes several, read tools fan out across all of them unless you pass a workspace_id, and write tools require one.

Input parameters:

- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `error` (string)
- `success` (boolean)
- `workspaces` (array)

### `well_list_connectors` (~597 tokens)

List Connectors

List the connectors a workspace can install, each with a one-click install deep link.

Use this to answer "what can I connect to Well?" or "how do I connect <provider>?". Each entry has:
\- service_id: the connector's stable catalog id (e.g. "stripe"), used in the install link.
\- name, category_id, direction: what the connector is.
\- status: "available" connectors are connectable now; "coming_soon"/"unavailable"/"maintenance" are not.
\- is_matched / is_selected: whether this workspace's detected tools matched this connector / already picked it.
\- match_score: 0..1 confidence of that match; null when unmatched. A high score is a tool Well is confident the workspace already uses.
\- is_connected: this workspace already holds a live connection for the connector — offer a reconnect, not a first install.
\- connection_status: that live connection's state, or null when not connected. "enabled" is connected and syncing; "processing" means the grant is in and the FIRST sync is still running (connected — do not ask the user to connect it again); "error" is authenticated but its last real sync failed, which warrants a reconnect.
\- workspace_connector_id: the connected instance's id, or null when not connected. This is the id well_invoke_connector_tool and well_list_connector_tools need — resolve it HERE, never via well_query_records on workspace_connectors.
\- is_preselected: Well recommends connecting this one now (a high-confidence match that is not yet connected). The interactive picker pre-checks exactly these.
\- install_url: the connector's public page on wellapp.ai, where the user can read about the integration and start connecting it; null for a bank (banks connect from their own hub, not a first-party page) or any slug the marketing site builds no page for. Hand this to the user to get started in one click.

The default view returns the curated, matched-first connectors; pass q to name-search the full catalog (e.g. a specific bank). This is ALSO the tool that answers "wh…

Input parameters:

- `limit` (integer): Max connectors to return (1-100, default 50).
- `offset` (integer): Number of connectors to skip, for paging (default 0).
- `q` (string): Name search across the full catalog (e.g. a specific bank). Omit for the curated, matched-first view.
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `connectors` (array)
- `error` (string)
- `limit` (number)
- `offset` (number)
- `success` (boolean)
- `total` (number)

### `well_run_register_diff` (~467 tokens)

Run Register Diff

Diff a workspace's bank transactions against its accounting-register transactions (e.g. QuickBooks), and persist the result.

\- Every match — hard evidence (structured reference, IBAN, tax ID) or inference-only (memo/payee reading) — is raised as a review task with the candidate already attached (raised_for_review). Nothing links automatically; resolve with well_resolve_reconciliation_task once a human decides.
\- Bank transactions with no register counterpart come back as missing_in_register_ids, each also minted as a gap review task (gaps_proposed) — resolve one with well_resolve_register_diff_gap once a human names the two ledger accounts. gaps_already_proposed counts gaps re-surfaced from an earlier run that already have an open, unresolved proposal.
\- Bank transactions NOT confirmed absent from the register come back as contended_in_register_ids — never minted as a gap. Two cases land here: (1) a plausible match lost to a higher-confidence sibling transaction this run, so the register-side movement is already accounted for by the winner; (2) the matcher couldn't produce a trustworthy answer (an invalid model response or a provider failure), so absence was never confirmed. Re-run the diff later; a genuine gap or duplicate should resolve itself once the winner's review task is handled or the matcher succeeds.
\- Register entries no bank transaction explains come back as unexplained_in_register_ids.

Returns { enabled: false, ... } with all counts 0 if the workspace's register-diff feature is off.

Input parameters:

- `bank_workspace_connector_id` (string, required): The bank connector's workspace_connector_id (e.g. Plaid).
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `register_workspace_connector_id` (string, required): The accounting connector's workspace_connector_id (e.g. QuickBooks).
- `since_date` (string): Only diff bank transactions on/after this date (YYYY-MM-DD).
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `already_linked` (number)
- `contended_in_register` (number)
- `contended_in_register_ids` (array)
- `enabled` (boolean)
- `error` (string)
- `gaps_already_proposed` (number)
- `gaps_proposed` (number)
- `matched` (number)
- `missing_in_register` (number)
- `missing_in_register_ids` (array)
- `raised_for_review` (number)
- `success` (boolean)
- `unexplained_in_register` (number)
- `unexplained_in_register_ids` (array)

### `well_resolve_reconciliation_task` (~204 tokens)

Resolve Reconciliation Task

Approve or reject one or more reconciliation review tasks (from well_run_register_diff or the in-app review queue).

\- approve: confirms the match — the link is flipped to active.
\- reject: dismisses the match — the candidate does not silently re-surface.

Each task_id resolves independently; a failure on one (already resolved, not found) is returned in errors and does not block the rest of the batch.

Input parameters:

- `action` (string, required)
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `task_ids` (array, required): The review tasks' task_id values.
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `error` (string)
- `errors` (array)
- `resolved` (array)
- `success` (boolean)

### `well_resolve_register_diff_gap` (~315 tokens)

Resolve Register Diff Gap

Post a well_run_register_diff gap (one of missing_in_register_ids' review tasks) into QuickBooks as a Purchase or Deposit.

Requires the exact ledger_account_id (a UUID, not a name) for both:
\- bank_ledger_account_id: the bank/cash account the money moved through (e.g. Checking).
\- category_ledger_account_id: the expense or income category the gap books against.

Look these up first with well_query_records({ root: "ledger_accounts", filters: [...] }) scoped to the register connector — never guess an id or match an account by substring/fuzzy name.

Fails with an error (not a silent no-op) if gap posting is disabled for this workspace, if either account doesn't belong to this gap's register connector, or if either account no longer resolves in QuickBooks.

Input parameters:

- `bank_ledger_account_id` (string, required): ledger_account_id of the bank/cash account.
- `category_ledger_account_id` (string, required): ledger_account_id of the category account.
- `idempotency_key` (string): Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation.
- `task_id` (string, required): The gap review task's task_id.
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `already_posted` (boolean)
- `error` (string)
- `external_id` (string)
- `success` (boolean)
- `task_id` (string)

### `well_get_investment_holdings` (~256 tokens)

Get Investment Holdings

Get the live holdings/positions (what's currently held and its value) for a connected Plaid investment account — brokerage, IRA, 401k, etc.

WORKFLOW:
1\. well_list_connectors() → pick the ENABLED Plaid connector (connection_status: "enabled") and read its workspace_connector_id directly off the row.
2\. well_get_investment_holdings({ workspace_connector_id }) → the current holdings, fetched fresh from Plaid on every call (never stored/stale data).

Only works on Plaid connectors that support the investments product — not the MCP-transport connector-tool-passthrough tools (well_list_connector_tools / well_invoke_connector_tool), and not for investment transactions (buy/sell/dividend/fee), which are queryable as ordinary rows via well_query_records on the transactions root instead.

Input parameters:

- `workspace_connector_id` (string, required): The connected Plaid provider's workspace_connector_id (from well_list_connectors).
- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `error` (string)
- `holdings` (array)
- `success` (boolean)

### `well_get_runway` (~320 tokens)

Get Runway

Get the workspace's current cash runway — cash on hand, trailing-3-month average burn, and months of cash left — the exact same computation and numbers the Well app's canvas KPI cards show. Use this instead of computing runway yourself from raw account/transaction reads.

Returns `cash` (amount + currency), `avg_burn` (amount + currency + trailing_months), `months`, and a `status` discriminator:
\- "ok" — a finite months figure.
\- "capped" — runway exceeds 36 months; report as ">36 months", not the raw number.
\- "infinite" — cash is positive and the workspace isn't burning (net inflow); there is no meaningful "months" figure.
\- "insufficient_data" — not enough connected cash/transaction data to compute; tell the user to connect a bank/accounting connector (well_list_connectors) instead of guessing.

\`partial: true` means some accounts or transactions were excluded from the computation (e.g. missing FX rate) — mention the exclusion counts and any `hints` if present rather than presenting the number as unconditionally complete.

Call this directly — no other tool call is needed first (workspace is resolved from the caller's authorized token, same as every other well_* tool).

Input parameters:

- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `as_of` (string)
- `avg_burn` (object)
- `cash` (object)
- `error` (string)
- `excluded` (object)
- `hints` (array)
- `months` (number)
- `partial` (boolean)
- `status` (string)
- `success` (boolean)

### `well_get_cash_position` (~309 tokens)

Get Cash Position

Get the workspace's current cash position: total cash on hand right now, converted to the workspace base currency, plus a per-account breakdown — the exact same computation and numbers the Well app's canvas KPI card shows. Use this instead of summing account balances yourself.

Returns `amount`/`currency` (the converted total), `accounts` (per-account contributions: native amount/currency, converted amount, the FX rate applied), and `as_of` (the FX-rate anchor date this snapshot is valid for).

\`unavailable: true` means `amount` is a placeholder, not a real measurement (e.g. no accounts connected yet) — say so plainly rather than presenting it as a real €0 balance. `partial: true` means one or more accounts were excluded from an otherwise real total (e.g. missing FX rate) — mention the exclusion count and any `hints` rather than presenting the number as unconditionally complete.

This is a snapshot only — no burn rate or runway is implied. Call `well_get_runway` instead for a forward-looking figure.

Call this directly — no other tool call is needed first (workspace is resolved from the caller's authorized token, same as every other well_* tool).

Input parameters:

- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `accounts` (array)
- `amount` (number)
- `as_of` (string)
- `currency` (string)
- `error` (string)
- `excluded` (object)
- `hints` (array)
- `partial` (boolean)
- `success` (boolean)
- `unavailable` (boolean)

### `well_get_cost_structure` (~298 tokens)

Get Cost Structure

Get the workspace's cost structure: outflow for the latest closed month, broken down by category — the exact same computation and numbers the Well app's canvas cost-structure donut chart shows. Use this instead of summing/grouping transactions yourself.

Returns `entries` (an array of `{ category, amount, pct }`, sorted by amount descending) and `currency` (the workspace base currency). `amount` is a magnitude (outflow), not signed.

\`rung` names which grouping actually produced these categories — "ledger_account" (the workspace's own chart of accounts), "category_normalized" (Well's auto-categorization), "transaction_type" (a technical fallback bucket), or "uncategorised" (no signal qualified). State it when you present the breakdown so the user knows whether they're looking at their own ledger's categories or Well's.

If `hints` are present (e.g. a coverage caveat about uncategorized spend), disclose them rather than presenting the breakdown as unconditionally complete.

Call this directly — no other tool call is needed first (workspace is resolved from the caller's authorized token, same as every other well_* tool).

Input parameters:

- `workspace_id` (string): Target workspace. Omit to use the only authorized workspace, or (for read tools) to query all authorized workspaces grouped by workspace. Required for write tools when the token authorizes more than…

Output parameters:

- `currency` (string)
- `entries` (array)
- `error` (string)
- `hints` (array)
- `records_url`: Login-gated deep link to the web-app transactions table, so the user can categorize the underlying spend. Null when no workspace is in context.
- `rung` (string): Which ladder rung produced these categories: the workspace's own ledger accounts, Well's auto-categorization, a technical fallback bucket, or none qualified.
- `success` (boolean)

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/wellapp-ai-well-mcp/v1-mcp#diagnostics

## Score history

- 2026-08-03: 79
- 2026-08-02: 79
- 2026-08-01: 78
- 2026-07-31: 78
- 2026-07-30: 72
- 2026-07-29: 71
- 2026-07-28: 71
- 2026-07-27: 70
- 2026-07-26: 69

## Links

- Remote endpoint: https://api.wellapp.ai/v1/mcp
- Repository: https://github.com/WellApp-ai/well-mcp
- Website: https://docs.wellapp.ai/mcp/introduction
- Changelog RSS feed: https://verifymcp.io/servers/wellapp-ai-well-mcp/v1-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/wellapp-ai-well-mcp/v1-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/wellapp-ai-well-mcp/v1-mcp