> ## Documentation Index
> Fetch the complete documentation index at: https://vexioncards.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# VEXiON MCP server

> Run your loyalty program from Claude, ChatGPT, Cursor and other AI assistants. Connect once, then look up customers, record transactions, build cards and send notifications in plain language.

The VEXiON MCP server lets an AI assistant work with your VEXiON account. You connect it once, then ask in plain language: "How many new customers did we get this month?", "Create a stamp card for the new cafe", "Email Anna her card".

It uses the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), an open standard that AI assistants use to talk to other software. Any MCP client can connect. VEXiON runs the server for you, so there is nothing to install.

| | |
| - | - |
| **Server URL** | `https://api.vexioncards.one/mcp` |
| **Transport** | Streamable HTTP |
| **Sign-in** | OAuth with your VEXiON account (default) or a VEXiON API key |
| **Who can connect** | Admins of a business on VEXiON PRO |
| **Tools** | 31, see the [tool list](https://vexioncards.mintlify.site/ai/mcp-tools.md) |

## What an assistant can do

> [card] Answer questions
>
> Totals, trends and comparisons for transactions, rewards and new customers, by day, week, month, card or location.

> [card] Look things up
>
> Find a customer by email, phone or scanned pass value. Read cards, locations, products and past notifications.

> [card] Make changes
>
> Create and edit cards, customers, products and locations. Record stamps, points and redemptions.

> [card] Reach customers
>
> Send a push notification to wallet cards, or email one customer their card link. Always with a preview first.

## How it works

The assistant never gets your password. It gets a sign-in for the businesses you chose, each with the access level you chose. Every call is checked against that choice, business by business, and you can revoke it at any time. A tool you did not allow is not shown to the assistant at all.

## Requirements

* A business on **VEXiON PRO**. VEXiON ONE does not include AI assistants.
* You are an **admin** of that business. Managers and scanners cannot connect an assistant.
* An active business. A paused, locked or cancelled business cannot be used until it is active again.
* An AI client that supports remote MCP servers over Streamable HTTP. Clients that only support the older SSE transport are not supported.

Developers using an API key need an API key on a plan that includes API access. See [Introduction](https://vexioncards.mintlify.site/api-reference/introduction.md#authentication).

## Connect an assistant

> [!TIP]
>
> Menus in AI apps change often. If a label differs, follow your app's own steps for adding a remote MCP server and use the URL below.

Every client needs the same server URL:

```text theme={null}
https://api.vexioncards.one/mcp
```

### Choose how to sign in

| | OAuth (default) | API key |
| - | - | - |
| **Best for** | Business owners and admins | Developers, scripts, automation |
| **How** | Sign in with your VEXiON account in the browser | Send a VEXiON API key in the `Authorization` header |
| **Access is chosen by** | You, on the VEXiON consent screen | The scopes of the key |
| **Revoke** | Settings > Developer > AI assistants | Revoke the key in Settings > Developer |
| **Works in** | Claude, ChatGPT, Claude Code, Cursor, VS Code, Gemini CLI | Clients that let you set a request header |

Use OAuth whenever your client supports it. Use an API key when there is no browser, for example in CI or a server-side agent.

> [!WARNING]
>
> An API key is a secret. Never paste it into a chat, commit it, or hard-code it in a shared file. Put it in an environment variable, as the examples below do.

### Connect with OAuth

> [tab] Claude.ai and Claude Desktop
>
> Custom connectors work in Claude on the web and in Claude Desktop.
>
> **1. Open Connectors**
>
> Go to **Customize > Connectors**. Click **+ Add**, then **Add custom connector**.
>
> **2. Add the server**
>
> Name it `VEXiON`, paste `https://api.vexioncards.one/mcp` and click **Continue**. Keep the default sign-in settings and click **Add**.
>
> **3. Sign in and choose access**
>
> Click **Connect**. A VEXiON page opens. Sign in, choose the businesses and choose what Claude may do. See [Permissions](https://vexioncards.mintlify.site/ai/mcp-permissions.md).
>
> **4. Turn it on in a chat**
>
> In a conversation, click **+** at the lower left, choose **Connectors** and switch **VEXiON** on.
>
> > [!NOTE]
> >
> > On **Team** and **Enterprise** plans an owner adds the connector first, under **Organization settings > Connectors > Add > Custom > Web**. Members then open **Customize > Connectors** and click **Connect**. Free accounts can add one custom connector.

> [tab] ChatGPT
>
> ChatGPT connects to remote MCP servers as a custom app. The menu names have changed several times, so follow this outline and OpenAI's own page for the current labels: [Connect a custom MCP server in ChatGPT](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt).
>
> **1. Add a custom MCP server**
>
> Open ChatGPT Plugins at `chatgpt.com/plugins`, click the plus button and choose **Add custom MCP server**.
>
> **2. Enter the details**
>
> Give it a name such as `VEXiON`. Under **Connection**, choose the public endpoint and enter `https://api.vexioncards.one/mcp`. Set authentication to OAuth.
>
> **3. Accept the warning**
>
> Read the risk notice, click **I understand and want to continue**, then click **Create as a plugin**.
>
> **4. Sign in**
>
> ChatGPT opens a VEXiON page. Sign in, choose the businesses and the access level. See [Permissions](https://vexioncards.mintlify.site/ai/mcp-permissions.md). Start a new chat, type `@` and pick the VEXiON app.
>
> > [!NOTE]
> >
> > On Business, Enterprise and Edu workspaces an admin may have to allow custom MCP servers before you can add one. Whether you can use tools that change data depends on your ChatGPT plan and workspace settings. VEXiON does not control this.

> [tab] Claude Code
>
> Add the server, then sign in from inside Claude Code.
>
> ```bash terminal theme={null}
> claude mcp add --transport http vexion https://api.vexioncards.one/mcp
> ```
>
> Start Claude Code and run `/mcp`, choose **vexion** and follow the browser steps to sign in and choose access.
>
> To share the server with a team, add `--scope project`. It is written to `.mcp.json` in the project, and each person signs in on their own:
>
> ```bash terminal theme={null}
> claude mcp add --transport http --scope project vexion https://api.vexioncards.one/mcp
> ```
>
> Check the connection with `claude mcp list`.

> [tab] Cursor
>
> Add the server to `~/.cursor/mcp.json` for all projects, or to `.cursor/mcp.json` in one project:
>
> ```json mcp.json theme={null}
> {
>   "mcpServers": {
>     "vexion": {
>       "url": "https://api.vexioncards.one/mcp"
>     }
>   }
> }
> ```
>
> Cursor lists the server under its MCP settings. When it asks you to sign in, sign in with your VEXiON account and choose the access in the browser.

> [tab] VS Code
>
> Add the server to `.vscode/mcp.json` in your workspace, or run **MCP: Open User Configuration** to add it for every workspace:
>
> ```json .vscode/mcp.json theme={null}
> {
>   "servers": {
>     "vexion": {
>       "type": "http",
>       "url": "https://api.vexioncards.one/mcp"
>     }
>   }
> }
> ```
>
> Run **MCP: List Servers**, choose **vexion** and start it. VS Code opens the VEXiON sign-in. Then open the Chat view in Agent mode and use the tools.

> [tab] Gemini CLI
>
> Add the server to `~/.gemini/settings.json`. Gemini CLI uses `httpUrl` for Streamable HTTP servers:
>
> ```json settings.json theme={null}
> {
>   "mcpServers": {
>     "vexion": {
>       "httpUrl": "https://api.vexioncards.one/mcp"
>     }
>   }
> }
> ```
>
> Start Gemini CLI and run `/mcp auth vexion` to sign in. OAuth needs a browser on the same machine, so use an API key over SSH or in CI.

> [tab] Any MCP client
>
> Use the server URL `https://api.vexioncards.one/mcp` with the **Streamable HTTP** transport.
>
> The server follows the standard MCP authorization flow. A client that supports it finds the sign-in details on its own: an unauthenticated request returns `401` with a `WWW-Authenticate` header that points to the protected resource document at `https://api.vexioncards.one/.well-known/oauth-protected-resource/mcp`.
>
> If your client has no OAuth support, use an API key (below).

### Connect with an API key

Create a key in **Settings > Developer** and give it only the scopes the agent needs. See [Introduction](https://vexioncards.mintlify.site/api-reference/introduction.md#authentication) for who can create keys. Send the key as a bearer token:

```http theme={null}
Authorization: Bearer vxn_sk_...
```

> [tab] Claude Code
>
> ```bash terminal theme={null}
> export VEXION_API_KEY=vxn_sk_...
> claude mcp add --transport http vexion https://api.vexioncards.one/mcp \
>   --header "Authorization: Bearer $VEXION_API_KEY"
> ```
>
> For a shared project file, use an environment variable so the key is not committed:
>
> ```json .mcp.json theme={null}
> {
>   "mcpServers": {
>     "vexion": {
>       "type": "http",
>       "url": "https://api.vexioncards.one/mcp",
>       "headers": {
>         "Authorization": "Bearer ${VEXION_API_KEY}"
>       }
>     }
>   }
> }
> ```

> [tab] Cursor
>
> ```json mcp.json theme={null}
> {
>   "mcpServers": {
>     "vexion": {
>       "url": "https://api.vexioncards.one/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:VEXION_API_KEY}"
>       }
>     }
>   }
> }
> ```

> [tab] VS Code
>
> VS Code asks for the key the first time the server starts and stores it for you:
>
> ```json .vscode/mcp.json theme={null}
> {
>   "inputs": [
>     {
>       "type": "promptString",
>       "id": "vexion-api-key",
>       "description": "VEXiON API key",
>       "password": true
>     }
>   ],
>   "servers": {
>     "vexion": {
>       "type": "http",
>       "url": "https://api.vexioncards.one/mcp",
>       "headers": {
>         "Authorization": "Bearer ${input:vexion-api-key}"
>       }
>     }
>   }
> }
> ```

> [tab] Gemini CLI
>
> ```bash terminal theme={null}
> gemini mcp add --transport http \
>   --header "Authorization: Bearer $VEXION_API_KEY" \
>   vexion https://api.vexioncards.one/mcp
> ```
>
> Or in `~/.gemini/settings.json`:
>
> ```json settings.json theme={null}
> {
>   "mcpServers": {
>     "vexion": {
>       "httpUrl": "https://api.vexioncards.one/mcp",
>       "headers": {
>         "Authorization": "Bearer your-api-key"
>       }
>     }
>   }
> }
> ```
>
> Prefer the `gemini mcp add` command with an environment variable over writing the key into the file.

An API key reaches the business it belongs to. The tools the agent sees follow the key's scopes: a key without `notifications:send` never shows the notification tools. See the [tool list](https://vexioncards.mintlify.site/ai/mcp-tools.md) for the scope each tool needs.

### Check that it works

Ask the assistant: "Give me an overview of my VEXiON account." It should answer with your business name, plan, locations and cards. If it does not, see [MCP server errors](https://vexioncards.mintlify.site/api-reference/errors.md#mcp-server-errors).

## Example prompts

You do not need to name a tool. Describe what you want and the assistant picks the right ones. What it can do depends on the access you granted.

| You say | What happens |
| - | - |
| "Give me an overview of my VEXiON account." | Reads your business, locations and cards. A good first message. |
| "How many new customers did we get each week in September, and how many installed the card?" | Runs a sign-up report and returns counts by week. |
| "Compare transactions this month to last month at the Main Street location." | Runs a transaction report for both ranges and compares the totals. |
| "Find the customer with email [anna@example.com](mailto:anna@example.com) and tell me how many stamps she has." | Looks up the customer and reads the card balance and recent transactions. |
| "Anna just bought a coffee. Add one stamp to her card." | Records a transaction for her. Needs write access. |
| "Create a stamp card for my cafe: 8 stamps, free coffee on the ninth, brown design." | Drafts the card, shows you the design and creates it after you agree. Needs write access. |
| "Send a notification to everyone with the coffee card: 'Double stamps this Friday!'" | Shows a preview of the text and the audience filters, then sends only after you confirm. Needs notification access. |
| "Email Tomas his card link so he can add it to his wallet." | Shows a preview, then emails the link after you confirm. Needs write access. |

> [!TIP]
>
> Name the card, location or date range when you can. "Transactions at the Old Town location last week" gives a more exact answer than "recent transactions".

## Where to read next

> [card] [Permissions and security](https://vexioncards.mintlify.site/ai/mcp-permissions.md)
>
> The access levels, what an assistant can never do, and how to revoke an app.

> [card] [Tools](https://vexioncards.mintlify.site/ai/mcp-tools.md)
>
> All 31 tools, the confirmation steps and the notification and report limits.

> [card] [MCP server errors](https://vexioncards.mintlify.site/api-reference/errors.md#mcp-server-errors)
>
> Sign-in errors, missing tools and what to do about them.

> [card] [Rate limits](https://vexioncards.mintlify.site/api-reference/rate-limits.md#mcp-server)
>
> Request and notification limits for the MCP server.

> [!NOTE]
>
> Not a developer? The Knowledge Base has a plain-language guide for business owners: [AI assistants (MCP)](https://vexioncards.mintlify.site/knowledge-base/developer-ai-assistants.md).

> [!NOTE]
>
> Looking for the REST API instead? Start with the [Quickstart](https://vexioncards.mintlify.site/api-reference/quickstart.md). The MCP server uses the same data and the same rules as the REST API, so a key, a plan or an account state that is refused there is refused here too.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.