Cin7 Core (Dear) Operations MCP Server

This MCP server is fast and powerful because it uses the GrowthPath App Server's cached Cin7 Core (Dear) data to let AI assistants search orders, products, customers and stock in ways that are not practically possible through the Dear API alone.

It provides read-only searches, selected summary reports and integration-job diagnostics. Results reflect the cached data, not necessarily the current state in Cin7 Core. A cached stock check is not a live availability guarantee. This release does not expose tools for changing Cin7 Core records. Broader historical analytics are available through GrowthPath's separate analytics reporting module.

New to MCP? Model Context Protocol (MCP) is a standard way for AI assistants to connect to business systems. An MCP server makes selected data and tools available to a connected assistant, so you can ask questions in ordinary language instead of looking up each record yourself. Read Cloudflare's introduction to MCP and MCP servers for an overview of how it works and the security considerations.

Configure the Cin7 Core (Dear) Operations MCP server.
Server URL: https://statusanxiety.growthpath.com.au/mcp-dear
Transport: Streamable HTTP
Preferred authentication: MCP OAuth (authorization code with PKCE S256).
Requested scope: mcp_dear.read
Protected-resource metadata URL: https://statusanxiety.growthpath.com.au/.well-known/oauth-protected-resource/mcp-dear
Authorization server: https://statusanxiety.growthpath.com.au
Sign in as an active Django user in the mcp group or a superuser.
Review the client, callback origin, resource and scope before approving access.
Manual fallback: Authorization: Token <token key> (a Django REST Framework token, not a Dear API key).
Store credentials only in the client's approved secret or credential store, never in chat, logs or source control.
This server exposes read-only cached data, not live stock guarantees or record mutations.
Use the MCP endpoint, not the documentation page. A local documentation preview does not verify a local MCP transport.

Authentication

Preferred OAuth Setup For Desktop Agents

Desktop agents that support MCP OAuth should be configured with the MCP server URL below and allowed to complete the browser-based OAuth login. The client should discover this server's protected-resource metadata from the WWW-Authenticate challenge or from the well-known metadata path on the same host as the MCP endpoint.

• Server URL: https://statusanxiety.growthpath.com.au/mcp-dear
• Protected-resource metadata URL: https://statusanxiety.growthpath.com.au/.well-known/oauth-protected-resource/mcp-dear
• Authorization server: https://statusanxiety.growthpath.com.au
• OAuth flow: authorization code with PKCE S256 and dynamic public-client registration.
• OAuth refresh: refresh tokens are supported for OAuth clients and are rotated after successful use.
• Requested scope: mcp_dear.read

The user who signs in through OAuth must be an active Django user authorized for MCP access: either a superuser or a member of the Django auth group named mcp. Do not paste OAuth access tokens, refresh tokens, authorization codes, or DRF token keys into normal chat messages.

After signing in, review the client name, callback origin, requested resource and scopes, then choose Allow access or Cancel. Only approve a connection you started and recognise. Opening the authorization link alone does not grant access. Each authorization requires a new review; the review expires after 10 minutes and a newer review in the same browser replaces the previous one.

OAuth access tokens are intentionally time-limited. Clients that support OAuth refresh should keep refresh tokens only in their approved credential store, use them to get fresh access tokens, and replace the stored refresh token whenever the token endpoint returns a rotated value. If a client cannot refresh automatically, re-run the browser-based OAuth authorization flow rather than copying tokens through chat or logs.

Refresh tokens are stored server-side only as hashes. Administrators can revoke stored refresh tokens in Django admin without seeing the plaintext token value.

Manual API Token Setup

Use this path for MCP clients that cannot complete the OAuth flow. The preferred complete header is Authorization: Token <token>. A bare token header, Authorization: <token>, is also accepted for clients such as Microsoft Copilot Studio that configure the header name and secret value separately but cannot prepend the Token scheme. The token is the key from Django REST Framework's Token model, stored in the Django database and managed in Django admin. It is not a Dear API key.

1. In Django admin, create or select an active Django user account for the MCP client.
2. Authorize that user by adding it to the Django auth group named mcp, or by making it a superuser. Staff status alone does not authorize MCP access.
3. In Django admin, create or find the token for that same user in the Tokens table under Auth Token. The token row's key value is the token used by the MCP client. Modifying this table requires the appropriate Django admin permission and is normally restricted to superusers.
4. Configure the MCP client to send Authorization: Token <token key> on every MCP request. If the client cannot prepend an authentication scheme, configure the same header as Authorization: <token key>.

MCP_DEAR_ALLOWED_ACTOR_EMAIL is not required for read-only MCP access. Access is based on the Django user linked to the supplied DRF token: the user must be active and either in the mcp group or a superuser.

Authorization is also scoped by namespace and Dear instance configuration. Tools can only read the object types and run the read-only or dry-run harnesses explicitly allowed for the runtime namespace.

These object-type permissions also apply to dedicated lookups, stock availability, recent sales, transaction reads and operation planning, not just generic cache searches.

Most tools accept an optional entity argument. If this deployment exposes only one Dear instance, omit entity and the MCP server will use that instance automatically. If multiple instances are exposed, the server will reject ambiguous requests and list the allowed entity values. Use list_queryable_object_types to discover the enabled cached object types and accepted filter keys before calling search_cached_objects.

MCP Client Setup

MCP client setup differs between tools such as Claude Desktop, Codex-style coding tools, and other MCP-enabled assistants, so this page documents the stable protocol values rather than tool-specific click paths. Prefer OAuth when the client supports it. You can give an MCP-enabled assistant this documentation URL and ask it to read the page and configure the server, but do not paste the DRF token into an ordinary chat prompt. If your client asks for a server name, choose a local label such as cin7-mcp; that label is not a server-side identifier and does not prove the connection is installed. Verify the client lists the MCP server, then complete the client's OAuth authentication flow. For Claude Desktop, a restart may be required after changing MCP configuration. For Claude Code, see Claude MCP Quickstart.

• Server URL: https://statusanxiety.growthpath.com.au/mcp-dear
• Transport: streamable HTTP MCP endpoint.
• Preferred authentication: MCP OAuth using the protected-resource metadata and scope mcp_dear.read.
• OAuth status endpoint: /mcp_oauth/status/ reports issuer, resource metadata, and token lifetimes.
• Manual fallback header: Authorization: Token <token key>
• Microsoft Copilot Studio fallback: header name Authorization, value <token key>.
• Manual fallback token source: Django REST Framework's Token model in Django admin.

Enter the token only through the client's approved secret, environment-variable, credential, or HTTP-header configuration mechanism. If a client cannot store the token outside normal chat history, shared configuration, logs, or source control, do not connect that client until a safer setup path is available.

Codex Web App Setup

In the Codex web app, create a new app using this deployment's MCP server URL, https://statusanxiety.growthpath.com.au/mcp-dear, and OAuth.

• Name: use a clear label such as Equipped Dear MCP or Cin7 Dear MCP.
• Connection: choose Server URL and enter https://statusanxiety.growthpath.com.au/mcp-dear.
• Authentication: choose OAuth.
• Advanced OAuth settings: normally leave discovery enabled unless an administrator gives explicit values.
• Risk warning: continue only for approved GrowthPath MCP deployments.

Configured Dear Scope

Knowledge Resources

• dear://meta/server
• dear://instance/{entity}
• dear://catalog/object-types
• dear://catalog/object-type/{object_type}
• dear://catalog/jsonb-search
• dear://typed-dict/{typed_dict_name}
• dear://typed-dict/{typed_dict_name}/json-schema
• dear://harness/{harness_name}
• dear://job-log-guide

MCP Tools

The tools below are the callable API surface exposed by the Cin7/Dear MCP server. Use discovery tools first to resolve the namespace, entity, object type, accepted filters, and safety limits before calling data or diagnostic tools.

Discovery And Schema

Cached Dear Data

Aggregate Reports

Job Logs And Diagnostics

Harnesses

Planning-Only Operations

Agentic Workflow Examples

These examples are intended for n8n-style agents and other MCP clients that need a safe first tool choice before chaining additional steps. Treat them as guidance for read-only investigation and dry-run planning, not permission to perform arbitrary ERP mutations.

Object Types

Paginated Data Tools

Collection tools return has_more. Tools that support page numbers accept a 1-based page. Page-number traversal supports random access, but deep pages are less efficient and pages are not a stable snapshot while cache refreshes run. Page-size ceilings reflect row cost: 1,000 for narrow summaries and stock rows, 500 for sale lines and invoice headers, 250 for full harness log messages, and 100 for complete-aggregate report rows. Nested cache collections have separate limits below. Source-batch reports consume source records, not pages of complete aggregate results.

search_cached_objects returns at most 1,000 summary rows per call and defaults to 25. Set sort_by to last_modified or object_uniqueID, and set sort_direction to asc or desc. For orders, you can also sort by sale_order_date; for purchase_orders, use order_date. For sale_credits and sale_credits_stand_alone, use credit_note_date. These business-date sorts use the document's calendar date, not its cache modification time. The default remains last_modified desc; object_uniqueID is always used as the deterministic tie-breaker.

When has_more is true, call the tool again with next_cursor as the cursor argument. Repeat the same object type, filters, entity, and any explicit sorting arguments. Cursors are opaque, signed, and bound to that query and Dear account; clients must not inspect or modify them. Alternatively, provide page for random access. Never provide cursor and page together. get_product_availability supports the same two continuation modes.

get_sale_order_lines and get_additional_attribute_sets use cursors only, not page numbers. Repeat the same query with next_cursor as cursor until has_more=false. Sale-line reads default to 100 lines and allow at most 500 per call. Date-filtered calls examine at most 100 parent sales plus one parent-ID lookahead. Continue even when row_count=0 if a cursor is returned. A sale with more than 500 lines continues from its original line position; duplicate SKUs remain separate lines. Exact line counts are off by default. Attribute discovery defaults to 20 sets and allows at most 100 sets (1,000 labels) per call. If its cached definitions change during traversal, restart discovery without a cursor.

total_count is the exact number of matching rows in the local Dear cache at the time of that call. returned_count is the number in the current page. These counts are not live Cin7 Core totals, and pages are not a stable snapshot while cache refreshes run. Without fields, returned rows are summaries; with fields, they contain identity metadata plus the requested scalar values. Neither response contains a complete cached Dear payload. Fetch dear://catalog/cached-object-search for the machine-readable contract.

For sequential traversal without an exact count, set include_total_count=false on search_cached_objects. Counts and total pages are then null rather than estimates; use has_more and next_cursor to continue. On get_product_availability, set include_totals=false to omit both the matching count and stock totals. These options avoid repeating whole-result calculations on every page. Defaults still include exact metadata.

Sale-transaction page-number traversal has a maximum row offset of 10,000. At 500 rows per page this permits 21 pages (10,500 rows); at the default 100 rows per page it permits 101 pages (10,100 rows). Check pagination_truncated before treating a result as complete: remaining matches beyond the accessible pages are not an empty result. Narrow the filters or use analytics reporting when this limit is reached.

Source-batch reports

Call list_aggregate_reports and use each report's execution_tool and execution_mode. For products_by_status, the preferred tool is run_aggregate_report_batch. Each call selects at most 501 source product records: it consumes at most 500 and uses one for lookahead. Filters apply within that source batch, so a call can scan records but return rows=[]. Batching limits work per call; it does not guarantee that a call cannot time out.

1. Start without a cursor. Keep the report name, filters and entity unchanged throughout the traversal.
2. Save each accepted response by batch_id. Count each ID once. If the current batch is retried, replace its saved response instead of adding it again.
3. Pass next_cursor as cursor while has_more=true, even if rows is empty. An empty batch is not the end of the report.
4. Merge accepted batches using batch_group_by and batch_sum_fields from discovery. For products_by_status, sum product_count by status. Sort the combined totals only after has_more=false.

Each response contains batch-local counts, not cumulative or complete totals. If traversal stops early, report partial coverage, not a complete total. Retrying an earlier batch requires discarding that batch and all later batches first. Cache changes between calls are accepted; the traversal is not a consistent snapshot.

Report timeout recovery

A database statement timeout returns a structured error with error.code=query_timeout. The failed call contributes no counts and advances no cursor. Follow only the recovery that the error advertises; batching is registered per report, not automatically available for every slow query.

• If a complete-report error supplies error.fallback, call its tool with its arguments. Discard all previous complete-report pages and start the batch traversal without a cursor. Do not combine complete-report rows with batch counts or retry the unchanged complete query.
• If a complete-report error supplies no fallback, narrow the supported filters or seek support. Do not invent a paging method or repeatedly retry the same request. State when narrower filters change the requested report scope.
• If a batch times out, use error.retry.tool and error.retry.arguments to retry that input cursor once. Keep earlier accepted batches. If the retry also times out, stop and seek support; do not advance the cursor or count either failed call.

Purchase receipts and dates

Discover purchase_orders with get_object_type_schema, then request both StockReceived.Lines and PutAway.Lines through include_nested_collections. Receipt representation depends on purchase type and Cin7 Core's Use put away setting. Advanced Purchases can separate receiving from put-away. PutAway.Lines can contain receipt data when StockReceived.Lines is empty, including for Simple Purchases. Do not infer the configuration or absence of receipts from one empty collection, and do not add both stages as independent deliveries.

Inspect line Received, parent task Status, and PO status. A task status alone does not prove receipt: Received=true identifies received lines, and a task can remain DRAFT while put-away is pending. Line Date is the raw recorded receipt date, not an invoice date or proof of when put-away was authorised. Report the source stage and missing dates. Verify the stage's meaning for the workflow before calculating lead time. PO order_date_from/to filters select OrderDate, not receipt dates. A partial receipt does not prove on-time-in-full delivery.

Expanded searches allow at most 25 parent documents and return at most 100 source slots per requested collection per parent per call. Check source_state, source_complete, invalid counts and unavailable_branch_counts; missing or invalid data is not zero. Source completeness describes structure, not freshness or complete pagination. Before advancing the outer cursor, finish each parent's nested pages: select that parent by object_uniqueID, request only the unfinished collection, and pass its next_offset as nested_collection_offset. The maximum offset is 10,000; at a limit of 100, capacity is 101 pages and 10,100 source slots per parent collection. Check pagination_truncated and matches_remain before reporting complete coverage.

Schema Discovery

The GrowthPath App Server stores cached Dear JSON documents in PostgreSQL. These tools support searching nested JSON fields without requiring the assistant to retrieve every complete document.

TypedDict resources are split into compact human-readable field lists and full JSON Schema resources. Use the compact dear://typed-dict/{typed_dict_name} resource first, then fetch dear://typed-dict/{typed_dict_name}/json-schema when a client needs required fields, nested object definitions, literals, unions, array item schemas, or descriptions. TypedDict class docstrings become object descriptions. Field descriptions are published when the annotation uses structured Annotated string metadata; ordinary source comments are not parsed.

Before supplying fields to get_recent_sales or search_cached_objects, call get_object_type_schema and use the exact, case-sensitive paths from field_projection.selectable_fields. A request may select 1 to 20 scalar paths. Whole objects, paths through arrays, and fields outside the MCP disclosure allowlist remain unavailable through field projection; use a registered nested collection or dedicated collection tool instead.

For get_sale_order_lines, call get_object_type_schema with object_type=orders and select from sale_order_lines.selectable_fields. Default line fields are ProductID, SKU and Quantity. Select ProductCustomField1 through ProductCustomField10 explicitly when needed. Their labels depend on each product's attribute set; a slot number alone does not identify its business meaning. Use include_attribute_metadata=true to resolve current cached product assignments. These definitions are not historical label snapshots, and attribute metadata does not make product or customer master attributes bulk-selectable.

The search_cached_objects tool also accepts bounded PostgreSQL JSONB filters through the reserved jsonb_filters key. Fetch dear://catalog/jsonb-search for the supported operators and examples, then use the object-type and JSON Schema resources to choose valid nested payload paths.

Allowlisted Harnesses

A harness is a pre-approved diagnostic script exposed through the MCP server as a controlled job. Harnesses are used for narrow evidence collection workflows that are too specific for a generic read-only tool but still need guardrails, audit logs, and namespace scoping.

Only harnesses listed for the current namespace can be invoked. Each run is validated against the registry, records JobLog output, and executes on the configured target rather than giving the MCP client arbitrary shell access. Harnesses documented here should remain read-only or dry-run only.

The transaction validator accepts a month from 1 to 12, a year from 1 to 9999 (excluding December 9999), and a sample_limit from 1 to 100. Logs retain at most 8 KiB of source bytes per line and the first 1 MiB per run; truncation markers are additional. Raw-payload differences are represented by hashes, not payload contents. Output limits do not change the underlying comparison results.

Example MCP Usage

The User prompt column shows text a user might type into an MCP-enabled assistant. The Expected MCP server behavior column explains which MCP tool the assistant should call and the structured arguments it should send to this server.

Aggregate Reports

Use list_aggregate_reports to discover the enabled sale, customer, and product aggregate reports for the current namespace. Use the returned execution_tool. For run_aggregate_report, supply a report name, optional filters and entity, and limit from 1 to 100. For run_aggregate_report_batch, supply the report name, optional filters and entity, then follow next_cursor; there is no client-selected batch limit or page number. Follow the batch merge rules and timeout recovery instructions.

{
  "object_type": "purchase_orders",
  "filters": {"order_number": "PO-001"},
  "fields": ["OrderNumber", "Supplier", "Type", "Status"],
  "include_nested_collections": ["StockReceived.Lines", "PutAway.Lines"],
  "limit": 1,
  "nested_collection_limit": 100,
  "include_total_count": false
}

{
  "object_type": "sale_credits",
  "filters": {
    "status": "AUTHORISED",
    "credit_note_date_from": "2026-10-01",
    "credit_note_date_to": "2026-10-31"
  },
  "sort_by": "credit_note_date",
  "sort_direction": "asc",
  "include_credit_header_amounts": true,
  "include_total_count": false,
  "limit": 100
}