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

There are two ways to connect, and they give you exactly the same data. Pick the one your MCP client supports.

	Sign in with Piing	Access token
How you authenticate	You sign in and approve, once	You paste a key into a header
Anything to store?	No	Yes — treat it like a password
Who sets it up	You	Your account manager issues the key
Best for	Clients with a built-in sign-in step, such as Claude.ai	Clients configured by file, such as Claude Code, Claude Desktop and ChatGPT

Prefer signing in where your client offers it. There is no key to copy, lose, or rotate, and access follows your Piing account automatically.

Signing in with Piing

Nothing to request in advance. Add the connector, click Connect, and you are sent to Piing to sign in and approve.

The approval screen asks for one permission: to read which organization you belong to. That is all the connector needs. It does not widen what you can see — your existing store permissions still apply to every result, exactly as they do when you sign into Piing.

Getting an access token

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 Piing account determines exactly what the connector can see, whichever way you connected. 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 connection is bound to one Piing org and cannot reach data in any other org.
User	The connection 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 connection can never return data outside your permitted stores, and never from another organization.

To query multiple organizations, add one connection per organization (see below).

Connecting

Open Settings → Connectors → Add custom connector.
Name: Piing Data
URL: https://agent.piing.ai/mcp
Leave the authentication fields empty. Do not add an Authorization header — that switches the connector to the access-token method and skips the sign-in step.
Save, then click Connect.
Sign in with your Piing account and approve the one permission it asks for.

The connector is ready as soon as you approve. Claude remembers the approval, so you only do this once per client.

If you belong to more than one organization

The connector reads whichever organization is active on your Piing account at the moment you approve. Before you connect, sign into Piing and switch to the organization you want to query.

If no organization is active when you approve, the connection is refused rather than guessing — picking one for you could show you the wrong organization's numbers. Switch to the organization you want in Piing, then remove and re-add the connector.

To query a second organization, switch to it in Piing and add the connector again under a different name.

Claude Code, Claude Desktop, ChatGPT — access token

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

Configuration file

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.
Sign-in loops, or the connector never finishes connecting	An `Authorization` header is set, which skips the sign-in step.	Remove the header and reconnect.
Sign-in succeeds, but the connector is still refused	No organization was active on your Piing account when you approved, and you belong to more than one.	Sign into Piing, switch to the organization you want, then remove and re-add the connector.
`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

Read-only. Neither method can change any data in Piing.
Per-user. Both methods act as a specific user, so access always reflects that user's current store permissions — including any change made after you connected.
Revocable. Ask your account manager to revoke either a token or a signed-in connection. Revocation takes effect immediately.
Treat an access token like a password. Anyone holding it can read your permitted data. Don't share it, commit it to source control, or paste it into untrusted tools. This is the main reason to sign in instead where you can — there is no key to leak.

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)
Whether you signed in with Piing or used an access token
A description of the issue and any error message

Overview​

Getting Access​

Signing in with Piing​

Getting an access token​

Scope​

Connecting​

Claude.ai — sign in with Piing​

If you belong to more than one organization​

Claude Code, Claude Desktop, ChatGPT — access token​

Configuration file​

Claude.ai / Claude Desktop (connector settings)​

ChatGPT (custom connector / MCP)​

Connecting to multiple organizations​

Verifying the connection​

Available Tools​

Troubleshooting​

Example​

Security​

Support​