> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/connectors/spiffy/setup.md).

# Get Started

Add the Spiffy connector once in your AI tool, sign in to Spiffy, and the tools are ready in any conversation after that.

For click-by-click steps in a specific app, the [Spiffy University guides](https://university.spiffy.co) cover Claude, ChatGPT, Grok, and others. This page covers the connection details, which are the same wherever you connect from.

## What you need

* A Spiffy account with dashboard access to whatever you want the assistant to work with.
* A client that supports remote MCP servers or custom connectors (Claude, ChatGPT, Grok, and others).

## Connection details

| Field          | Value                                         |
| -------------- | --------------------------------------------- |
| Server URL     | `https://api.spiffy.co/mcp`                   |
| Transport      | Streamable HTTP                               |
| Authentication | OAuth 2.1 (authorization code flow with PKCE) |

## Adding the connector

Menu names vary by client, but the flow is the same:

1. In your client, add a custom connector or remote MCP server.
2. Enter the server URL: `https://api.spiffy.co/mcp`
3. The client finds Spiffy's sign-in automatically (via standard OAuth discovery) and opens it.
4. Sign in and review the consent screen.
5. Choose the accounts and scopes to grant (see below), then approve.
6. The client finishes the OAuth handshake and the Spiffy tools show up.

To disconnect, remove the connector in your client or revoke it from your Spiffy connected-apps settings. Either one drops the OAuth grant right away.

### Grok

Grok adds custom MCP servers from its connectors page:

1. Open [grok.com/connectors](https://grok.com/connectors).
2. Click **New Connector** and choose **Custom**.
3. Enter `Spiffy` as the name and `https://api.spiffy.co/mcp` as the server URL, then add the connector.
4. Sign in to Spiffy when prompted and approve the accounts and scopes you want to grant.

Spiffy tools are then available in your Grok chats.

## Accounts and scopes

During consent you decide what the connector can touch.

**Accounts.** A Spiffy login can reach more than one account. You grant access to the accounts you pick, and a single authorization can cover several at once (the HTTP v2 API is limited to one account per token; the connector is not).

**Scopes.** You grant scopes per account. The connector asks only for what the tools you plan to use need:

| Scope                          | Covers                                                |
| ------------------------------ | ----------------------------------------------------- |
| `account`                      | Account details                                       |
| `users`                        | Account users                                         |
| `customers`                    | Customers and their saved cards/notes                 |
| `orders`                       | Orders, refunds, order notes                          |
| `subscriptions`                | Subscriptions and subscription billing                |
| `subscription_metered_billing` | Metered-billing usage on subscriptions                |
| `paymentplans`                 | Payment plans                                         |
| `payments`                     | Payments, retries, refunds                            |
| `checkouts`                    | Checkout configuration                                |
| `products`                     | Products, options, prices                             |
| `promos`                       | Promotions and their codes                            |
| `affiliates`                   | Affiliate programs, affiliates, links, payouts        |
| `analytics`                    | Read aggregated analytics and attribution reporting   |
| `reports`                      | Create, run, and read saved reports and their results |
| `integrations`                 | Integration entity fields                             |
| `webhooks`                     | Webhook endpoints and events                          |

A tool only runs if your grant includes its scope. Read-only tools need read access to the scope; tools that change data need write access.

### Working across multiple accounts

Every account-scoped tool takes an optional `account_id`. You usually don't need to set it:

* If your grant covers one account, the connector uses it automatically.
* If your grant covers several accounts, read tools default to one of them and tell the assistant which one they used, so it can re-run elsewhere if needed. Write tools won't default. They need an explicit `account_id`, so a change never lands on the wrong account by accident.

When you work across accounts, say which one you mean: *"In the Acme account, refund order 1234."*

## Check the connection

Ask for something simple and read-only:

> *List my five most recent orders.*

A working connection calls `list_orders` and returns the results. If you get an authorization error instead, see [Troubleshooting](https://developers.spiffy.co/connectors/spiffy/troubleshooting.md).
