> ## 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.

Juo MCP remote server exposes subscription platform to AI assistants and agents via the [Model Context Protocol](https://modelcontextprotocol.io). Once connected, tools like Claude, Cursor, or any MCP-compatible client can read and manage subscriptions, customers, products, and more — directly from AI workflow.

## Server URL

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

The server uses **Server-Sent Events (SSE)** transport and requires authentication via the standard **OAuth 2.0** authorization code flow.

## Connecting a client

<Tabs>
  <Tab title="Claude Desktop">
    Add the following to `claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "juo": {
          "url": "https://mcp.juo.com/sse"
        }
      }
    }
    ```

    On macOS the config file is located at:

    ```
    ~/Library/Application Support/Claude/claude_desktop_config.json
    ```

    Restart Claude Desktop — it will open a browser window to complete OAuth authorization on first use.
  </Tab>

  <Tab title="Cursor">
    Open **Cursor Settings → MCP** and add a new server:

    | Field | Value                     |
    | ----- | ------------------------- |
    | Name  | `juo`                     |
    | Type  | `sse`                     |
    | URL   | `https://mcp.juo.com/sse` |

    Save and reload the window. Cursor will prompt you to authorize via OAuth before the tools become available.
  </Tab>

  <Tab title="Windsurf">
    Edit Windsurf MCP config file (`~/.codeium/windsurf/mcp_config.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "juo": {
          "serverUrl": "https://mcp.juo.com/sse"
        }
      }
    }
    ```

    Restart Windsurf and complete the OAuth flow when prompted.
  </Tab>

  <Tab title="VS Code">
    Add to `settings.json` (requires [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) with MCP support enabled):

    ```json theme={null}
    {
      "mcp.servers": {
        "juo": {
          "url": "https://mcp.juo.com/sse"
        }
      }
    }
    ```

    Reload the window and authorize via OAuth when prompted.
  </Tab>

  <Tab title="Continue">
    Add the following to [Continue](https://continue.dev) config (`~/.continue/config.yaml`):

    ```yaml theme={null}
    mcpServers:
      - name: juo
        transport:
          type: sse
          url: https://mcp.juo.com/sse
    ```

    Reload Continue and complete the OAuth authorization in the browser.
  </Tab>

  <Tab title="Claude Code">
    Add the Juo MCP server using the CLI:

    ```bash theme={null}
    claude mcp add --transport sse juo https://mcp.juo.com/sse
    ```

    Alternatively, add it manually to `~/.claude/settings.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "juo": {
          "url": "https://mcp.juo.com/sse"
        }
      }
    }
    ```

    On the next Claude Code session start, the OAuth authorization flow will open in the browser.
  </Tab>

  <Tab title="Zed">
    Add to Zed `settings.json`:

    ```json theme={null}
    {
      "context_servers": {
        "juo": {
          "source": {
            "type": "url",
            "url": "https://mcp.juo.com/sse"
          }
        }
      }
    }
    ```

    Reopen the project — Zed will prompt for OAuth authorization on first connection.
  </Tab>
</Tabs>

## 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. Client initiates a connection to `https://mcp.juo.com/sse`.
2. The server signals that authorization is required.
3. Browser opens the Juo authorization page.
4. You log in with a Juo account and grant the requested permissions.
5. The auth server exchanges the code for an access token and returns it to the client — no manual copying of tokens required.

Tokens are scoped to a tenant and stored securely by an MCP client. Re-authorization is only required 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 (SSE)
    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: Connect with Bearer token
    Server-->>Client: Connected — tools ready
```

## Available tools

Once connected, the following tools are available to AI client:

<AccordionGroup>
  <Accordion title="Customers">
    | Tool               | Description                                                             |
    | ------------------ | ----------------------------------------------------------------------- |
    | `customers-list`   | Paginated list of customers; search by ID, name, email, or phone        |
    | `customers-create` | Create a customer with contact details (name, email, phone, tags, note) |
    | `customers-update` | Partial update of a customer's profile                                  |
    | `customers-delete` | Permanently delete a customer                                           |
  </Accordion>

  <Accordion title="Subscriptions">
    | Tool                       | Description                                                                                         |
    | -------------------------- | --------------------------------------------------------------------------------------------------- |
    | `subscriptions-list`       | Paginated list; search by ID, serial, status, dates, or customer; optionally expand customer inline |
    | `subscriptions-create`     | Create a subscription with billing policy, items, delivery address, and payment method              |
    | `subscriptions-update`     | Update payment method, delivery address/method/price, or next billing date                          |
    | `subscriptions-cancel`     | Cancel with an optional reason; optionally notify the customer by email                             |
    | `subscriptions-pause`      | Pause an active subscription                                                                        |
    | `subscriptions-resume`     | Resume a paused subscription                                                                        |
    | `subscriptions-reactivate` | Reactivate a canceled subscription                                                                  |
  </Accordion>

  <Accordion title="Subscription items">
    | Tool                         | Description                                                                              |
    | ---------------------------- | ---------------------------------------------------------------------------------------- |
    | `subscriptions-items-create` | Add a product variant to a subscription; supports custom price and recurring cycle limit |
    | `subscriptions-items-update` | Update item quantity, billing policy, or delivery policy                                 |
    | `subscriptions-items-delete` | Remove an item (subscription must retain at least one item)                              |
  </Accordion>

  <Accordion title="Subscription discounts">
    | Tool                             | Description                                                                                                              |
    | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
    | `subscriptions-discounts-create` | Apply a discount code or a manual discount (percentage or fixed amount) targeting all items, specific items, or shipping |
    | `subscriptions-discounts-update` | Update discount value or recurring cycle limit                                                                           |
    | `subscriptions-discounts-delete` | Remove a discount from a subscription                                                                                    |
  </Accordion>

  <Accordion title="Products">
    | Tool                                | Description                                                                                    |
    | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
    | `products-list`                     | Paginated list; search by ID, title, status, or variant SKU; filter by subscription plan group |
    | `products-create`                   | Create a product with title, description, vendor, type, tags, status, and optional image       |
    | `products-update`                   | Partial update of a product (title, description, vendor, type, status, tags)                   |
    | `products-delete`                   | Permanently delete a product                                                                   |
    | `products-add-variant`              | Add a variant (price, SKU, barcode, option values) to a product                                |
    | `products-remove-variant`           | Remove a variant from a product                                                                |
    | `products-assign-product-to-plan`   | Associate all variants of a product with a subscription plan                                   |
    | `products-remove-product-from-plan` | Disassociate all variants of a product from a subscription plan                                |
    | `products-assign-variant-to-plan`   | Associate a specific variant with a subscription plan                                          |
    | `products-remove-variant-from-plan` | Remove a specific variant from a subscription plan                                             |
  </Accordion>

  <Accordion title="Schedules">
    | Tool                         | Description                                                                                                                      |
    | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
    | `schedules-list`             | View the upcoming billing order projection for a customer (read-only)                                                            |
    | `schedules-list-adjustments` | List pending schedule adjustments for a customer                                                                                 |
    | `schedules-create`           | Create a one-off adjustment to an upcoming order: skip, change date, update shipping/payment, swap products, or apply a discount |
    | `schedules-delete`           | Delete a pending adjustment, reverting the affected order to its original state                                                  |
  </Accordion>

  <Accordion title="Workflows">
    | Tool                      | Description                                                                                                        |
    | ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
    | `workflows-list`          | Paginated list of workflow definitions; optionally include archived or filter to interactive-only                  |
    | `workflows-get`           | Get the full definition of a workflow including steps, transitions, and publication status                         |
    | `workflows-create`        | Create a new workflow in draft status                                                                              |
    | `workflows-update`        | Full replacement update of a workflow definition                                                                   |
    | `workflows-delete`        | Soft-delete a workflow (run history is preserved)                                                                  |
    | `workflows-publish`       | Publish a draft workflow, making it active for incoming events                                                     |
    | `workflows-unpublish`     | Move a published workflow back to draft without affecting in-flight runs                                           |
    | `workflows-archive`       | Archive a workflow without deleting it                                                                             |
    | `workflows-duplicate`     | Create a copy of a workflow as a new draft                                                                         |
    | `workflows-list-runs`     | Paginated list of execution runs for a workflow                                                                    |
    | `workflows-get-run`       | Get the current state of a specific run (active step, context, status)                                             |
    | `workflows-get-run-stats` | Aggregate stats: total/successful/failed runs, per-step counts, experiment variant enrollment and conversion rates |
    | `workflows-export-runs`   | Generate a signed URL to download all runs for a workflow as a CSV file                                            |
  </Accordion>
</AccordionGroup>