---
title: 'Guper through AI (MCP)'
description: 'Connect an AI assistant to your organization and run Guper by conversation, with the permissions you already have.'
---

# Guper through AI (MCP)

Your organization has an address that any AI assistant speaking **MCP** (Model Context Protocol) understands. Once connected, you talk to the assistant and it uses Guper for you — looks up a customer, reads a balance, builds an audience, creates a campaign.

```
https://{organization}.myguper.com/mcp
```

It works in Claude, Cursor, ChatGPT, and any MCP-capable client.

**There is no key to generate and no SDK to install.** You sign in with your panel credentials, in the browser — and the assistant gets exactly the permissions you already have there.

## Connecting

1. Open the connectors area in your assistant. In Claude: **Settings → Connectors → Add custom connector**. In Cursor the field is called *MCP server URL*.
2. Paste your organization's address — `https://{organization}.myguper.com/mcp`.
3. A browser window opens with the Guper sign-in screen. Use **the same email and password as the panel**.
4. Done.

The application registers itself with your organization. The access is **yours, individual** — not the company's. If you leave, your access leaves with you, and nobody else's credentials need changing.

Work with more than one organization? Each is a separate connector with its own address. One access never reaches another.

## What you can ask for

The assistant searches an operation catalog before acting, so use everyday words:

- *"what's the cashback balance for customer 4,482,109?"*
- *"how many orders did store 1838 place this week?"*
- *"build an audience of everyone who bought wine in the last 90 days"*
- *"create a birthday campaign with 10% cashback"*
- *"why couldn't this customer redeem?"*

If it says it found nothing, try domain terms — cashback, redemption, audience, campaign, order — instead of describing the problem. The search is lexical.

## What it will not do on its own

**Anything that moves money requires explicit confirmation.** There are 41 such operations: balance adjustments, cancellations, credits. The assistant asks first and will not execute without your "yes".

**Non-idempotent operations require a repeat key.** That stops a network failure from turning one campaign into two.

**You do not see what you cannot see.** Operations outside your permissions never reach the assistant — it is not that it tries and gets denied: from its point of view they do not exist. A typical support profile sees about a fifth of the catalog.

## For administrators

### Who can use it

Anyone with a **panel** login (`admin` or `staff`) and an access profile assigned. End-customer logins cannot connect.

A user with no access profile gets a message on the screen and the connection does not complete. An access that can do nothing would make the assistant answer "I couldn't find anything" to everything, which is indistinguishable from a broken system.

### Controlling what the AI can do

Through the **panel's access profiles**, the same ones as always. There is no new screen and no parallel permission system: what the assistant can do is literally what sits in **Settings → Team → Access Roles**.

Someone with `Customer 360` at *view* can look customers up through AI but not change them. Someone without `Loyalty cards` sees nothing about cashback.

### Cutting someone's access

Deactivate the user in the panel. New sign-ins are blocked immediately, and existing access falls away at the next renewal — within an hour at most.

Changed a permission? It applies at the next renewal, also within an hour. What the assistant may do is re-checked at every renewal, never inherited.

### Duration

Access is valid for 1 hour and renews itself for up to 30 days without a new sign-in. After that, sign in again.

### Password attempts

Eight wrong attempts lock that email for 15 minutes. The lock is per email, not per network — one person's mistake does not affect the office.

## Building your own client

Guper's MCP follows **OAuth 2.1 with PKCE** and the standards MCP clients expect. You do not need to register anything by hand: registration is dynamic.

The starting point is the protected resource metadata ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)):

```bash
curl https://{organization}.myguper.com/.well-known/oauth-protected-resource
```

It points at the authorization server, whose metadata ([RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)) answers at:

```bash
curl https://{organization}.myguper.com/.well-known/oauth-authorization-server/api/connect
```

From there the flow is standard:

| step | endpoint |
|---|---|
| dynamic registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) | `POST /api/connect/oauth/register` |
| authorization | `GET /api/connect/oauth/authorize` |
| code exchange and renewal | `POST /api/connect/oauth/token` |
| revocation ([RFC 7009](https://www.rfc-editor.org/rfc/rfc7009)) | `POST /api/connect/oauth/revoke` |
| public key | `GET /api/connect/oauth/jwks` |

Details your client must respect:

- **PKCE is required, and only `S256`.** `plain` is not accepted.
- **The `redirect_uri` is matched by exact equality.** No prefixes, no wildcards. Always `https://`; `http://` only on loopback (`127.0.0.1`, `localhost`), per [RFC 8252](https://www.rfc-editor.org/rfc/rfc8252).
- **Public clients only** (`token_endpoint_auth_method: none`).
- **The `code` lasts 2 minutes and works once.** Presenting it again ends the whole session, by design.
- **Refresh tokens rotate.** Each use issues a new one; presenting a spent token ends the whole session.

The token is an RS256-signed JWT whose `aud` is your organization's canonical resource URI (`https://{organization}.myguper.com/mcp`). A token issued for one organization **fails** validation in another — the isolation comes from the protocol.

The `scope` carries permissions as `resource.level`, the same ones as the panel:

```
customer.360.edit customer.360.messages.view customer.addBalance.full order.edit
```

## Does this change my current integration?

**No.** `apiKey`/`apiSecret` → token → calls keep working exactly as they are, and no endpoint changed. MCP is a new, per-person path alongside what already exists.

Server-to-server integration continues on the usual path — see [Authentication](/docs/{lang}/guides/authentication).

## Common problems

| symptom | likely cause | what to do |
|---|---|---|
| "couldn't connect" | wrong organization address | check the subdomain in the address |
| sign-in opens then returns an error | the client's return address changed | remove and re-add the connector — it registers again |
| "application not recognized" | registered in another organization | expected: each organization has its own registration. Add the connector here |
| assistant finds nothing | the search is lexical | use domain terms, not a description of the problem |
| always asks for confirmation | financial operation | by design: 41 operations move money |
| an expected operation is missing | outside your profile | check **Settings → Team → Access Roles** |
| "too many attempts" | 8 wrong passwords | wait 15 minutes |

## See also

- [Authentication](/docs/{lang}/guides/authentication) — the `apiKey`/`apiSecret` path, for system integration
- [Integration landscape](/docs/{lang}/guides/integration-landscape) — how the pieces fit together
