Cin7 Core Analytics MCP Server

This server exposes Cin7 Core Analytics schema and semantics, validates PostgreSQL, and runs small read-only query results through the Model Context Protocol (MCP).

Approved MCP clients can discover the analytics warehouse, construct reporting queries, validate them against the physical PostgreSQL schema, preview up to five rows, and execute up to 100 rows after the client obtains explicit user approval. Query scope covers all Cin7 Core instances represented in this runtime namespace.

Authentication and Connection

Preferred OAuth Setup

ChatGPT, Claude Desktop, Codex, and other clients that support MCP OAuth should be configured with the MCP server URL and allowed to complete the browser-based OAuth flow. The client discovers the authorization server from the endpoint's WWW-Authenticate response or the protected-resource metadata URL.

• Server URL: https://test-dear.growthpath.com.au/mcp-c7core-analytics
• Transport: streamable HTTP.
• Protected-resource metadata path: /.well-known/oauth-protected-resource/mcp-c7core-analytics
• Authorization server: https://test-dear.growthpath.com.au
• OAuth flow: authorization code with PKCE S256 and dynamic public-client registration.
• Requested scope: mcp_analytics.query

The person signing in must be an active Django user who is a superuser or belongs to the Django auth group named mcp-analytics. OAuth access and refresh tokens, authorization codes, and DRF token keys must remain in the client's approved credential store rather than chat messages, logs, or source control.

Default OAuth Scope Behavior

When a dynamic client registration request omits scope, the server registers the client as allowed to request both supported scopes:

• mcp_analytics.query for this Analytics MCP resource.
• mcp_dear.read for the separate Cin7 Core API MCP resource.

Registration does not grant both scopes to every access token. The authorization request must identify the intended MCP resource and request its matching scope. Tokens for https://test-dear.growthpath.com.au/mcp-c7core-analytics use mcp_analytics.query; mcp_dear.read cannot be used to access the Analytics endpoint.

Manual API Token Setup

Clients that cannot complete OAuth may use a Django REST Framework token belonging to an active MCP-authorized user. Send Authorization: Token <token key> on every request. A bare Authorization: <token key> value is also accepted for clients that cannot prepend the Token scheme. The token is not a Cin7 Core API key.

MCP Client Values

• Server URL: https://test-dear.growthpath.com.au/mcp-c7core-analytics
• Preferred authentication: OAuth with scope mcp_analytics.query.
• Manual fallback header: Authorization: Token <token key>
• OAuth status endpoint: /mcp_oauth/status/
• Local client label: use a descriptive name such as cin7-core-analytics.

---

What This MCP Server Provides

The Analytics MCP server exposes 47 database tables from the Dear Analytics data warehouse, including:

Choosing Between Analytics and Dear Operations

The Dear Operations MCP server is the cache-backed operational source. This Analytics MCP server may not be enabled in every deployment. When both are connected, choose the server from the question's required data shape and date semantics rather than treating either source as live Cin7 Core data.

Base and Reporting Currencies

Base-currency amounts can use different currencies across Dear instances. Tables with year_month_currency can join that column directly to avg_ex_rate. For other tables, join through dear_metadata, match base_currency_code with avg_ex_rate.from_currency, and match the value's calendar month with avg_ex_rate.value_date. Multiply each value by in_reporting_currency before aggregation. The common currency comes from DearPostgresAnalyticsSettings.reporting_currency and appears as avg_ex_rate.to_currency. Preserve monetary facts with a LEFT JOIN, report missing/null-rate counts, and do not present a complete converted total when coverage is incomplete or target currencies disagree. Synthetic quantity-only adjustments have no revenue amount and do not require revenue conversion. These exchange rates are single-date monthly approximations, sometimes carried forward, not calculated monthly averages.

sales_fact contains consolidated invoice/credit facts, separate CreditNoteRestock adjustments, and synthetic dropship rows; rows are not original invoice lines. Keep restocks when reporting margin. Stored invoice COGS is negative and restock COGS positive: add signed COGS to revenue for margin.

PostgreSQL rejects result rows exceeding the configured transport limit (64 KiB by default) before transferring their values to Django. Preview and execution accumulate results against a 256 KiB serialized-response budget. Truncated results are explicitly marked; narrow value searches before choosing among ambiguous filter literals.

Available Resources

Available Tools

---

Configuring Claude Code

Option 1: Project Configuration (Recommended for Teams)

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "analytics": {
      "type": "http",
      "url": "https://test-dear.growthpath.com.au/mcp-c7core-analytics"
    }
  }
}

This file can be committed to git so all team members share the same configuration.

The endpoint requires an MCP-authorized user. OAuth clients must request the mcp_analytics.query scope for the https://test-dear.growthpath.com.au/mcp-c7core-analytics resource.

Option 2: CLI Command

# Add the MCP server
claude mcp add --transport http analytics https://test-dear.growthpath.com.au/mcp-c7core-analytics

# Verify it's configured
claude mcp list

# Check connection status (within Claude Code)
/mcp

Scope Options

Scope	Command	Use Case
project	claude mcp add --scope project ...	Shared with team via .mcp.json in git
user	claude mcp add --scope user ...	Available across all your projects
local	claude mcp add --scope local ...	Private, current project only (default)

---

Practical Examples

Discovering Tables

Ask Claude to list available tables:

What analytics tables are available?

@analytics:analytics://tables

Understanding Table Structure

Get the schema for a specific table before writing queries:

Show me the structure of the sales_fact table.

@analytics:analytics://schema/sales_fact

Building JOIN Queries

Use the relationships resource to understand how tables connect:

How do I join sales data to customer information?

@analytics:analytics://relationships
@analytics:analytics://schema/sales_fact
@analytics:analytics://schema/dear_customer

Validating and Running a Query

Ask the MCP client to follow the staged workflow:

Find the top 10 customers by revenue for the last 12 months.
Search the schema and examples, validate the exact PostgreSQL query,
qualify every physical table with public, preview the query, show me the SQL
and preview, and wait for my approval before execution.

Exploring Product Data

I need to analyze product availability across locations.
What tables should I use and how do they relate?

@analytics:analytics://schema/dear_product
@analytics:analytics://schema/dear_product_availability
@analytics:analytics://schema/dear_location
@analytics:analytics://relationships

---

Deployment Notes

Kubernetes Deployment

The MCP server is integrated into Django's ASGI application and served at the /mcp-c7core-analytics path. No separate server or port is required.

The MCP endpoint is available at:

https://<your-ingress-hostname>/mcp-c7core-analytics

This integration means:

• No additional Kubernetes deployment or service needed
• MCP requests are handled by the same pods as the Django application
• TLS is handled by ingress; the analytics MCP middleware validates DRF or OAuth credentials

Pre-authentication Proxy Trust

Rate limits use the original socket peer by default. Only configure MCP_ANALYTICS_TRUSTED_PROXY_CIDRS as a list or tuple of verified proxy networks whose proxies append the actual connecting address or replace incoming forwarding headers with a verified chain. Analytics does not inherit the Dear Operations proxy trust setting. For a trusted socket peer, all X-Forwarded-For fields are combined in received order and checked from right to left; the first untrusted address is used. Malformed configuration or chain entries discard the header, and a chain containing only trusted addresses retains the socket peer.

The ASGI server must preserve the original socket peer: disable upstream proxy-header rewriting before relying on this check. See the repository's mcp_dear/proxy_configuration.md for the shared ASGI serving contract, including the effect on forwarded scheme handling. Deployment configuration must be verified separately; this setting alone does not establish that the socket peer is preserved.

Local Development

For local development, you have two options:

Option A: Via Django (ASGI with Uvicorn)

# Start Django with ASGI server
uvicorn project.asgi:application --host 0.0.0.0 --port 8000

# MCP available at: http://localhost:8000/mcp-c7core-analytics

Option B: Standalone MCP Server

# Start dedicated MCP server on a different port
python manage.py mcp_server --port 8090

# MCP available at: http://localhost:8090/mcp-c7core-analytics

---

Available Tables

The following 47 tables are exposed via this MCP server: