> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perkstar.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect with MCP

> Give compatible AI clients secure, read-only access to Perkstar business reporting through OAuth.

Perkstar exposes a Model Context Protocol server for conversational reporting.
The connection is read-only: it can inspect loyalty data and analytics, but it
cannot change customers, balances, cards, messages, or account settings.

## Connection details

| Setting        | Value                                              |
| -------------- | -------------------------------------------------- |
| Server URL     | `https://dashboard.perkstar.co.uk/api/mcp`         |
| Transport      | Stateless Streamable HTTP, JSON response mode      |
| Authentication | OAuth 2.0 Authorization Code with PKCE             |
| Required plan  | Growth or above; Perkstar staff access is separate |
| Mutations      | None                                               |

Add the server URL to a compatible MCP client. The client discovers Perkstar's
authorization, registration, token, and revocation endpoints automatically.
The business owner or manager signs in, selects the organisation, and approves
the read-only `MCP` scope.

<Warning>
  A Perkstar API key cannot access MCP. Use the OAuth flow started by the MCP
  client; do not paste a dashboard API key into an AI application.
</Warning>

## Available business tools

<CardGroup cols={2}>
  <Card title="Programme and protection" icon="shield-check">
    Business overview, loyalty-card health, locations, and unusual-activity
    summaries.
  </Card>

  <Card title="Customers" icon="users">
    Search customers, inspect a customer, view behavioural groups, and rank top
    customers.
  </Card>

  <Card title="Loyalty activity" icon="receipt">
    Query stamps, points, redemptions, adjustments, and outstanding rewards.
  </Card>

  <Card title="Reporting" icon="chart-line">
    Performance, feedback, memberships, bookings, referrals, and broadcast
    reporting.
  </Card>
</CardGroup>

The server also provides guided prompts for a weekly performance review,
win-back candidates, and card health checks. Tools return current Perkstar data;
the AI client decides how to explain it.

## Security model

1. OAuth consent pins the token to one Perkstar organisation.
2. The server checks the token scope, expiry, revocation, plan, and consenting
   user on every request.
3. Tool schemas reject unknown fields and keep result sizes bounded.
4. Requests appear in the organisation's API activity log and follow its
   seven-day API audit retention.
5. Revoking the connection invalidates the access and refresh token pair.

Perkstar staff tools can query across organisations, but they are exposed only
when the consenting user independently passes the Perkstar staff check. A
normal business connection cannot request or smuggle an organisation override.

## Client compatibility

The server supports MCP protocol versions `2025-06-18`, `2025-03-26`, and
`2024-11-05`. It implements `initialize`, `ping`, tool listing and calls, and
prompt listing and retrieval. It does not expose an SSE stream, resources,
sampling, or write tools.

For a bespoke application rather than an MCP client, use the
[marketplace OAuth guide](/guides/oauth-marketplace) and public REST API.


## Related topics

- [Connect Odoo](/guides/odoo.md)
- [Perkstar developer platform](/index.md)
- [Integration gallery](/integrations/index.md)
- [Changelog](/changelog.md)
- [Build an OAuth marketplace app](/guides/oauth-marketplace.md)