Piing Data MCP Connector

Overview

The Piing Data MCP Connector lets you query your Piing store data in natural language from any Model Context Protocol (MCP) client — such as Claude Desktop, Claude Code, or ChatGPT. Ask questions like "what were my sales last 30 days?" or "rank my stores by revenue this month" and the connector returns structured results scoped to your account.

The connector is read-only. It can report on sales, traffic, products, store performance and task completion — it cannot create, update or delete anything in Piing.

Endpoint: https://agent.piing.ai/mcp

Transport: Streamable HTTP (MCP)

Getting Access

Access is granted with a personal access token (an API key) that is issued to you by Piing.

See your account manager for an access token.

Tokens are created and managed by Piing administrators — they are not self-service. When you request one, your account manager will generate a token tied to your user account and send it to you securely. The token is shown only once, so store it somewhere safe (a password manager is ideal). If a token is ever lost or compromised, your account manager can revoke it and issue a new one.

Scope

Your token determines exactly what the connector can see. Scope is enforced on every request:

Dimension	Scope
Access type	Read-only. Queries and reports only — no writes, no task actions.
Organization	A single organization. The token is bound to one Piing org and cannot reach data in any other org.
User	The token acts as you. It is tied to your specific Piing user account.
Stores	Only the stores you are permitted to see. The connector resolves your store permissions on every request and limits all results to that set.

In practice this means:

A user with organization-wide access sees all of that organization's stores.
A user who only manages one or two stores sees only those stores — the same data they'd see when signed into Piing.
A token can never return data outside your permitted stores, and never from another organization.

To query multiple organizations, request one token per organization and add each as a separate connection (see below).

Connecting

Add the connector to your MCP client as an HTTP server, passing your access token as a bearer header.

Claude Code / Claude Desktop (and most MCP clients)

Add an entry to your MCP configuration:

{
  "mcpServers": {
    "piing-data": {
      "type": "http",
      "url": "https://agent.piing.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Replace YOUR_ACCESS_TOKEN with the token from your account manager. After saving, reconnect or restart your MCP client so it picks up the new server.

Claude.ai / Claude Desktop (connector settings)

If your client offers a settings UI rather than a config file:

Open Settings → Connectors → Add custom connector.
Name: Piing Data
URL: https://agent.piing.ai/mcp
Under headers/authentication, add Authorization = Bearer YOUR_ACCESS_TOKEN.
Save and enable the connector. The client will list the available tools.

ChatGPT (custom connector / MCP)

In the connector settings, add a custom MCP server.
URL: https://agent.piing.ai/mcp
Add the header Authorization: Bearer YOUR_ACCESS_TOKEN.
Save; the get_* and query_dataset tools become available.

Connecting to multiple organizations

Use one named server per organization, each with its own token:

{
  "mcpServers": {
    "piing-acme": {
      "type": "http",
      "url": "https://agent.piing.ai/mcp",
      "headers": { "Authorization": "Bearer ACME_ACCESS_TOKEN" }
    },
    "piing-globex": {
      "type": "http",
      "url": "https://agent.piing.ai/mcp",
      "headers": { "Authorization": "Bearer GLOBEX_ACCESS_TOKEN" }
    }
  }
}

Your client will namespace each connection's tools by server name, so you can query both organizations side by side in the same session.

Verifying the connection

Once connected, ask your assistant to run the connector's ping tool, or simply ask a data question like "what were my total sales in the last 30 days?". A successful reply confirms the token, scope and connection are working.

Available Tools

All tools accept a natural-language query describing what you want, plus an optional explicit dateRange. Results are always limited to your permitted stores.

Tool	Purpose
`get_sales_summary`	Revenue, transaction count, average basket and conversion over a period.
`get_traffic_summary`	Visitor traffic, dwell time and time-of-day breakdown.
`get_product_performance`	Performance by product / category.
`get_performance_rankings`	Top / bottom N stores, regions, salespeople or assignees.
`get_store_comparison`	Compare metrics across stores.
`get_store_performance`	Detailed performance for a single store.
`get_task_summary`	Task counts by status (completed, in progress, not started, overdue) over a period.
`get_task_completion_summary`	Task completion rate, on-time rate and overdue counts over a period.
`get_task_details_by_date`	Per-task detail — due date, overdue flag, store and assignment counts — for drilling into specific tasks.
`get_employee_productivity`	Task productivity by assignee — throughput, completion rate and productivity score.
`query_dataset`	Flexible row-level query (counts, filters, aggregations) when a pre-built summary isn't enough.
`ping`	Health check — confirms the connector is reachable.

You normally won't call these by name; just ask your assistant a question and it will choose the right tool. For query_dataset, your assistant needs to know the dataset name and its fields — your account manager can share the available datasets.

Troubleshooting

Symptom	Cause	Fix
`404` from `/mcp`	Connector not enabled for your account.	Ask your account manager to enable it.
`401 Unauthorized`	Missing, wrong or revoked token.	Check the `Authorization` header; ask your account manager to re-issue.
"No permitted stores for this session."	Your account has no stores in scope.	Confirm your store permissions with your account manager.
A metric comes back empty / null	Data not yet synced for that store or period.	The metric is unavailable for that window — it does not mean the store has no data.

Example

You: Rank my stores by revenue this month.

Assistant: (calls get_performance_rankings)

Carindale (Mega) — $90,285

Belconnen Mega — $89,853

Harbourtown QLD — $85,734 …

Security

Treat your token like a password. Anyone with it can read your permitted data. Don't share it, commit it to source control, or paste it into untrusted tools.
Read-only. A token cannot change any data in Piing.
Revocable. If a token is lost or no longer needed, ask your account manager to revoke it. Revocation takes effect immediately.
Per-user. Because each token acts as a specific user, access automatically reflects that user's current store permissions.

Support

For help with the MCP connector, contact your Piing account manager or email support@piing.ai with:

Your organization name
The MCP client you're using (e.g. Claude Desktop)
A description of the issue and any error message

Overview​

Getting Access​

Scope​

Connecting​

Claude Code / Claude Desktop (and most MCP clients)​

Claude.ai / Claude Desktop (connector settings)​

ChatGPT (custom connector / MCP)​

Connecting to multiple organizations​

Verifying the connection​

Available Tools​

Troubleshooting​

Example​

Security​

Support​