Cin7 MCP Server

This MCP server exposes curated Cin7 Core/Dear knowledge plus read-only diagnostic tools for configured Dear instances.

In plain terms, this lets approved AI assistants understand how our Cin7/Dear data is structured, answer safer questions about orders, products, stock, and background jobs, and guide support work without giving broad access to the live system. It is intended to make investigations faster, reduce repeated manual lookup work, and keep access behind clear authentication, scoping, and audit controls. All exposed data access is read-only.

This MCP server prioritizes searching the GrowthPath App Server's cache of JSON documents. That makes it similar to the JSON-centric approach used with the Dear API, but the cache is served by PostgreSQL, and this MCP server understands PostgreSQL's support for searching and working with nested JSON documents. For many investigation tasks, that makes it more powerful than querying the raw Dear API directly. GrowthPath also has a separate analytics reporting module, which is outside the scope of this MCP server and is supported by a state-of-the-art natural language query tool.

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 path: /.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.

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. MCP requests must send Authorization: Token <token>. 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.

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.

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>
• 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 the MCP server URL and OAuth. The example screenshot uses the Equipped deployment URL, but for this deployment use https://statusanxiety.growthpath.com.au/mcp-dear.

• 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.

The example screenshot should show https://equipped.growthpath.com.au/mcp-dear as the server URL, Server URL connection mode, and OAuth authentication.

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

Schema Discovery

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, or array item schemas.

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.

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 run_aggregate_report with entity=<entity>, a report name, optional filters, and a bounded limit to run one of those reports.