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

# MCP

> Connect AI assistants to Juo using the Model Context Protocol.

The Juo MCP server gives AI assistants and agents access to your store through the [Model Context Protocol](https://modelcontextprotocol.io). Once connected, Claude, ChatGPT, Cursor, Codex, or any other MCP client can read and manage subscriptions, customers, products, schedules, analytics, and workflows.

## Server URL

```
https://mcp.juo.com/mcp
```

The server uses the **Streamable HTTP** transport. You can authenticate in two ways:

* **OAuth** (the default): log in with your Juo account in the browser. See [OAuth authorization flow](#oauth-authorization-flow).
* **Admin API key**: for scripts and agents that run without a browser. See [Connecting with an Admin API key](#connecting-with-an-admin-api-key).

## Toolsets

The server offers two endpoints. Add one of them to a client, not both.

| Endpoint | What it lists |
| - | - |
| `https://mcp.juo.com/mcp` | The core toolset: the 36 tools used most often for subscriptions, schedules, analytics, and workflows, plus three `admin-tools-*` tools that find and run the rest |
| `https://mcp.juo.com/mcp/all` | Every tool, listed directly |

Use `/mcp` unless you have a reason not to. A shorter list helps the assistant pick the right tool, and it stays under client limits such as Cursor's 40 tools. Tools outside the core set are still available: the assistant finds them with `admin-tools-search` and runs them with `admin-tools-write` or `admin-tools-destructive`. Keeping writes and deletions in separate tools lets your client approve one without the other.

> [!NOTE]
>
> `https://mcp.juo.com/sse` still works for clients set up before the move to Streamable HTTP. Use `/mcp` for new connections.

## Connecting a client

> [tab] Claude
>
> In claude.ai, go to **Customize → Connectors**, click **+**, then **Add custom connector**, and enter:
>
> ```
> https://mcp.juo.com/mcp
> ```
>
> On Team and Enterprise plans, an owner adds it under **Organization settings → Connectors**. The connector is also available in Claude Desktop. Claude opens the Juo login page the first time you use it.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http juo https://mcp.juo.com/mcp
> ```
>
> Run `/mcp` in a Claude Code session and select `juo` to log in.

> [tab] Codex
>
> ```bash theme={null}
> codex mcp add juo --url https://mcp.juo.com/mcp
> codex mcp login juo
> ```
>
> `codex mcp login` opens the OAuth login in the browser.

> [tab] Cursor
>
> Add to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "juo": {
>       "url": "https://mcp.juo.com/mcp"
>     }
>   }
> }
> ```
>
> Cursor asks you to log in before the tools become available.

> [tab] VS Code
>
> Add to `.vscode/mcp.json`, or to your user configuration with the **MCP: Open User Configuration** command:
>
> ```json theme={null}
> {
>   "servers": {
>     "juo": {
>       "type": "http",
>       "url": "https://mcp.juo.com/mcp"
>     }
>   }
> }
> ```
>
> Start the server from the file or the MCP view and log in when prompted.

> [tab] Windsurf
>
> Add to Windsurf's `mcp_config.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "juo": {
>       "serverUrl": "https://mcp.juo.com/mcp"
>     }
>   }
> }
> ```
>
> Refresh the MCP servers and log in when prompted.

> [tab] Zed
>
> Add to Zed's `settings.json`, or use **Settings → AI → MCP Servers → Add Server → Add Remote Server**:
>
> ```json theme={null}
> {
>   "context_servers": {
>     "juo": {
>       "url": "https://mcp.juo.com/mcp"
>     }
>   }
> }
> ```
>
> Zed starts the OAuth login on the first connection.

> [tab] Continue
>
> Add to Continue's `config.yaml`:
>
> ```yaml theme={null}
> mcpServers:
>   - name: juo
>     type: streamable-http
>     url: https://mcp.juo.com/mcp
> ```
>
> Reload Continue and log in when prompted.

> [tab] Other clients
>
> Clients that only run local (stdio) servers can connect through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):
>
> ```bash theme={null}
> npx mcp-remote https://mcp.juo.com/mcp
> ```
>
> Use this as the server command in the client's configuration. `mcp-remote` opens the OAuth login in the browser.

## OAuth authorization flow

The Juo MCP server uses the standard OAuth 2.0 authorization code flow with PKCE. When you connect for the first time:

1. The client connects to `https://mcp.juo.com/mcp`.
2. The server answers that authorization is required.
3. The browser opens the Juo login page.
4. You log in with your Juo account, pick a store, and grant access.
5. The client exchanges the code for an access token. You never copy a token by hand.

Tokens are scoped to one store and stored by the MCP client. You only log in again when a token expires or is revoked.

```mermaid theme={null}
sequenceDiagram
    participant Client as MCP Client
    participant Server as mcp.juo.com
    participant Auth as Juo Auth

    Client->>Server: Connect (Streamable HTTP)
    Server-->>Client: 401 + OAuth metadata
    Client->>Auth: Authorization request (PKCE)
    Auth-->>Client: Redirect to login
    Client->>Auth: Login + grant permissions
    Auth-->>Client: Authorization code
    Client->>Auth: Exchange code for token
    Auth-->>Client: Access token
    Client->>Server: Request with Bearer token
    Server-->>Client: Tools ready
```

## Connecting with an Admin API key

OAuth needs a person in a browser. For scripts, CI jobs, scheduled tasks, and self-hosted agents, connect with an [Admin API key](https://juo.dev/docs/api-reference/admin/introduction.md#authentication) instead.

1. In the Juo admin, go to **Settings → Integrations → API keys**, enter a label, and create a key. Copy it right away: the key is shown only once.
2. Send two headers on every request to `https://mcp.juo.com/mcp`:

| Header | Value |
| - | - |
| `X-Juo-Admin-Api-Key` | The Admin API key |
| `X-Tenant-ID` | The store's myshopify domain, e.g. `my-store.myshopify.com` |

Requests that carry `X-Juo-Admin-Api-Key` skip the OAuth flow. The same headers work on `https://mcp.juo.com/mcp/all`.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http juo https://mcp.juo.com/mcp \
>   --header "X-Juo-Admin-Api-Key: $JUO_ADMIN_API_KEY" \
>   --header "X-Tenant-ID: my-store.myshopify.com"
> ```

> [tab] Codex
>
> In `~/.codex/config.toml`, read the key from an environment variable:
>
> ```toml theme={null}
> [mcp_servers.juo]
> url = "https://mcp.juo.com/mcp"
> http_headers = { "X-Tenant-ID" = "my-store.myshopify.com" }
> env_http_headers = { "X-Juo-Admin-Api-Key" = "JUO_ADMIN_API_KEY" }
> ```

> [tab] Cursor
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "juo": {
>       "url": "https://mcp.juo.com/mcp",
>       "headers": {
>         "X-Juo-Admin-Api-Key": "your_api_key",
>         "X-Tenant-ID": "my-store.myshopify.com"
>       }
>     }
>   }
> }
> ```

> [tab] VS Code
>
> An input variable keeps the key out of the file. VS Code asks for it when the server starts:
>
> ```json theme={null}
> {
>   "inputs": [
>     {
>       "type": "promptString",
>       "id": "juo-api-key",
>       "description": "Juo Admin API key",
>       "password": true
>     }
>   ],
>   "servers": {
>     "juo": {
>       "type": "http",
>       "url": "https://mcp.juo.com/mcp",
>       "headers": {
>         "X-Juo-Admin-Api-Key": "${input:juo-api-key}",
>         "X-Tenant-ID": "my-store.myshopify.com"
>       }
>     }
>   }
> }
> ```

> [tab] Other clients (mcp-remote)
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "juo": {
>       "command": "npx",
>       "args": [
>         "mcp-remote",
>         "https://mcp.juo.com/mcp",
>         "--header", "X-Juo-Admin-Api-Key:${JUO_ADMIN_API_KEY}",
>         "--header", "X-Tenant-ID:my-store.myshopify.com"
>       ],
>       "env": {
>         "JUO_ADMIN_API_KEY": "your_api_key"
>       }
>     }
>   }
> }
> ```

> [tab] HTTP
>
> A custom agent can call the server directly:
>
> ```bash theme={null}
> curl https://mcp.juo.com/mcp \
>   -H "X-Juo-Admin-Api-Key: $JUO_ADMIN_API_KEY" \
>   -H "X-Tenant-ID: my-store.myshopify.com" \
>   -H "Content-Type: application/json" \
>   -H "Accept: application/json, text/event-stream" \
>   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
> ```

> [!NOTE]
>
> The MCP server passes the key on to the Juo Admin API, which validates it. A wrong or revoked key doesn't fail when the client connects. The error shows up on the first tool call.

> [!WARNING]
>
> An Admin API key gives full Admin API access to the store, so treat it like a password. Keep it in an environment variable or a secrets manager, not in a config file you commit. To revoke a key, open **Settings → Integrations → API keys** and click **Revoke**.

## Building workflows with an assistant

The server includes guidance that walks the assistant through building a workflow. Assistants that follow it work like this:

1. **Look up the catalog.** `workflows-catalog` returns the triggers first. With a trigger type, it returns the actions, settings, customer responses, conditions, and A/B test step shape allowed for that trigger. The assistant takes every name from the catalog instead of guessing.
2. **Create the workflow.** `workflows-create` validates the definition. A workflow with issues is still saved, as an unpublishable draft that lists them, so no work is lost.
3. **Fix or change it.** `workflows-edit` changes part of a saved workflow (a step, a setting, a transition, the name) without resending the rest. It saves only valid results and refuses an edit based on an outdated copy.
4. **Publish with your approval.** The assistant asks before publishing. Several workflows can exist for one trigger, but only one is published at a time.
5. **Measure.** `workflows-run-report` returns runs, End steps reached, and customer responses per step, with percentages and A/B variants, for one or more workflows over a date range.

The server also provides a `build-workflow` prompt and a `juo://workflows/catalog` resource for clients that support them. Customer-facing content, such as pop-ups and polls, can't be previewed through MCP, so check it in the workflow editor before you publish.

> [!NOTE]
>
> Workflows are never hard-deleted through MCP. Asking to delete or remove a workflow archives it, and `workflows-unarchive` restores it as a draft.

## Available tools

Tools marked † aren't listed on `/mcp`. There, the assistant reaches them with `admin-tools-search` and runs them with `admin-tools-write` or `admin-tools-destructive`. On `/mcp/all` they're listed like any other tool.

> [accordion] Subscriptions
>
> | Tool | Description |
> | - | - |
> | `subscriptions-list` | List subscriptions with their items, discounts, and customer ID; filter with `query`, e.g. `customer:<customerId>` or `status:active` |
> | `subscriptions-create` † | Create a subscription with billing policy, items, delivery address, and payment method |
> | `subscriptions-update` | Change the payment method, delivery address, method or price, or the next billing date |
> | `subscriptions-pause` | Pause an active subscription; nothing is billed until it's resumed |
> | `subscriptions-resume` | Resume a paused subscription |
> | `subscriptions-cancel` | Cancel a subscription, optionally emailing the customer |
> | `subscriptions-reactivate` | Reactivate a canceled subscription |
> | `subscriptions-custom-attributes-create` † | Add custom attributes to a subscription; existing keys are never overwritten |

> [accordion] Subscription items
>
> | Tool | Description |
> | - | - |
> | `subscriptions-items-create` | Add a product variant, optionally with a custom price and a recurring cycle limit (1 = one-time add-on) |
> | `subscriptions-items-update` | Change an item's quantity or its billing and delivery frequency |
> | `subscriptions-items-delete` | Remove an item; removing the last item cancels the subscription |

> [accordion] Subscription discounts
>
> | Tool | Description |
> | - | - |
> | `subscriptions-discounts-create` | Apply a discount code, or a manual percentage or fixed amount on all items, chosen items, or shipping |
> | `subscriptions-discounts-update` † | Change a discount's value or recurring cycle limit |
> | `subscriptions-discounts-delete` | Remove a discount from a subscription |

> [accordion] Schedules
>
> | Tool | Description |
> | - | - |
> | `schedules-list` | Preview a customer's upcoming orders (read-only) |
> | `schedules-list-adjustments` | List a customer's schedule adjustments (skips, moved dates, other one-order changes) |
> | `schedules-create` | Change one upcoming order without changing the subscription: skip it or some items, move its date, change its address, payment method, or products, or discount it |
> | `schedules-delete` | Delete an adjustment, so the order follows the subscription again |

> [accordion] Customers
>
> | Tool | Description |
> | - | - |
> | `customers-list` | Find customers by name, email, phone, or ID with `query` |
> | `customers-create` † | Create a customer with contact details (name, email, phone, tags, note) |
> | `customers-update` † | Partially update a customer's profile |
> | `customers-delete` † | Permanently delete a customer |
> | `customers-create-payment-method` † | Attach a payment method to a customer through a supported payment provider |

> [accordion] Products
>
> | Tool | Description |
> | - | - |
> | `products-list` | List products; search by title, status, or variant SKU/title with `query`, or filter by plan group |
> | `products-create` † | Create a product with title, description, vendor, type, tags, status, and an optional image |
> | `products-update` † | Partially update a product |
> | `products-delete` † | Permanently delete a product |
> | `products-add-variant` † | Add a variant to a product |
> | `products-remove-variant` † | Remove a variant from a product |
> | `products-assign-product-to-plan` † | Make all variants of a product available under a subscription plan |
> | `products-remove-product-from-plan` † | Remove all variants of a product from a subscription plan |
> | `products-assign-variant-to-plan` † | Make one variant available under a subscription plan |
> | `products-remove-variant-from-plan` † | Remove one variant from a subscription plan |

> [accordion] Workflows
>
> | Tool | Description |
> | - | - |
> | `workflows-catalog` | The triggers, actions, settings, customer responses, conditions, and A/B test step shape a workflow may use; filter by `triggerType` |
> | `workflows-list` | List workflows (ID, name, trigger type, status); filter by status or trigger type |
> | `workflows-get` | Get a workflow's full definition: trigger, steps, transitions, A/B variants, layout, and status |
> | `workflows-create` | Create a workflow; one with issues is saved as an unpublishable draft that lists them |
> | `workflows-validate` | Check a workflow definition without saving it |
> | `workflows-edit` | Change part of a saved workflow without resending the whole definition; saves only valid results |
> | `workflows-update` | Replace a workflow's name, description, trigger, or steps in full |
> | `workflows-duplicate` † | Copy a workflow as a new draft |
> | `workflows-publish` | Publish a draft; only one workflow per trigger type is published at a time |
> | `workflows-unpublish` | Move a published workflow back to draft; runs in progress finish on their current version |
> | `workflows-archive` | Archive a workflow; run history is kept |
> | `workflows-unarchive` † | Restore an archived workflow as a draft |
> | `workflows-visualize` | Show workflows as diagrams drawn like the workflow editor; offered only to clients that support MCP Apps |
> | `workflows-conclude-experiment` | End an A/B test step: send every new run to the winning variant, or stop the test |

> [accordion] Workflow runs and reporting
>
> | Tool | Description |
> | - | - |
> | `workflows-run-report` | How workflows perform: runs, End steps reached, and customer responses per step, with percentages and A/B variants, over an optional date range |
> | `workflow-runs-list` | List runs across all workflows; filter with `query`, e.g. by customer, status, workflow, or start date |
> | `workflows-list-runs` | List one workflow's runs, with the same `query` filters |
> | `workflows-get-run` | Get one run in full: trigger payload, customer responses, action outputs, A/B variant, outcome, error, and event timeline |
> | `workflows-get-run-stats` | Totals for one workflow: runs per status and outcome, entries per step, A/B enrollments, and conversion rates |
> | `workflows-export-runs` | Get a short-lived link to a CSV with one row per run |

> [accordion] Analytics
>
> | Tool | Description |
> | - | - |
> | `analytics-list-metrics` | Describe the metric catalog: what each metric measures, and the filters and group-by dimensions it supports |
> | `analytics-query` | Query one metric over a date range as a time series, with optional grouping, filters, currency conversion, or cohorts |
>
> Call `analytics-list-metrics` before building a query. An unsupported filter returns a `400`.

> [accordion] Finding and running other tools
>
> | Tool | Description |
> | - | - |
> | `admin-tools-search` | Find the tools not listed on `/mcp` and get their input schemas |
> | `admin-tools-write` | Run one of those tools that creates or changes data |
> | `admin-tools-destructive` | Run one of those tools that deletes or removes data |
>
> These three are listed only on `/mcp`.


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