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

# MCP server

> Connect AI agents to your Pocketsflow account with the Model Context Protocol — the full public API, exposed as MCP tools.

The Pocketsflow **MCP server** exposes the same public HTTP API you see at [api.pocketsflow.com/docs](https://api.pocketsflow.com/docs) as [Model Context Protocol](https://modelcontextprotocol.io) tools. Point an MCP-capable agent (Claude, Cursor, Windsurf, your own app) at it with an API key and it can create products, read orders, issue refunds, manage webhooks, send newsletters, and more — on your behalf, scoped to your account.

<Card title="Endpoint" icon="plug" horizontal>
  `https://api.pocketsflow.com/mcp` — a Streamable HTTP MCP endpoint.
  Authenticate with your API key as a Bearer token.
</Card>

## Authentication

The MCP server uses the same **API keys** as the REST API. Create one in the dashboard under **Developers → API keys**, then send it on every request:

```
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx
```

| Prefix      | Use                                                 |
| ----------- | --------------------------------------------------- |
| `pk_live_…` | Live mode — real products, customers, and payments. |
| `pk_test_…` | Test mode — sandbox data for development.           |

Every tool call is executed as your account. There is nothing else to configure — the key both authenticates the connection and scopes the data.

<Warning>
  Treat API keys like passwords. An agent connected with a `pk_live_…` key can
  create and delete real data. Use a `pk_test_…` key while developing, and
  prefer a dedicated, revocable key per integration.
</Warning>

## Connect an agent

<CodeGroup>
  ```json Claude / generic mcp.json theme={null}
  {
    "mcpServers": {
      "pocketsflow": {
        "url": "https://api.pocketsflow.com/mcp",
        "headers": {
          "Authorization": "Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
        }
      }
    }
  }
  ```

  ```bash Claude Code CLI theme={null}
  claude mcp add --transport http pocketsflow https://api.pocketsflow.com/mcp \
    --header "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
  ```

  ```json Cursor (~/.cursor/mcp.json) theme={null}
  {
    "mcpServers": {
      "pocketsflow": {
        "url": "https://api.pocketsflow.com/mcp",
        "headers": {
          "Authorization": "Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
        }
      }
    }
  }
  ```

  ```json npx @pocketsflow/mcp (stdio) theme={null}
  {
    "mcpServers": {
      "pocketsflow": {
        "command": "npx",
        "args": ["-y", "@pocketsflow/mcp"],
        "env": {
          "POCKETSFLOW_API_KEY": "pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
        }
      }
    }
  }
  ```
</CodeGroup>

Prefer the remote HTTP URL when your client supports it. Use
`@pocketsflow/mcp` only for clients that speak local stdio MCP.

## Agent skill

Install the companion skill from [skills.sh](https://skills.sh):

```bash theme={null}
npx skills add Pocketsflow/pocketsflow-imperium@pocketsflow
```

The skill teaches agents when to use MCP tools versus the REST API, and the
first-product / sales-check workflows.

Once connected, the agent lists the available tools automatically. Ask it
things like *"list my last 10 orders"*, *"create a \$29 product called Starter
Kit"*, or *"refund order ord\_123"*.

For step-by-step copy-paste setup (Claude Desktop, Cursor, ChatGPT) plus an
auth and first-call walkthrough, see the
[MCP setup guide](/ai-tools/mcp).

## Available tools

Tools mirror the public API, named `verb_resource` (for example `list_orders`,
`create_product`, `cancel_subscription`). Only operations that work with
API-key auth are exposed.

| Area                | Tools                                                                                                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Products            | `list_products`, `create_product`, `get_product`, `update_product`, `update_pricing`, `delete_product`                                                      |
| Checkout            | `create_checkout_session`                                                                                                                                   |
| Orders              | `list_orders`, `get_order`                                                                                                                                  |
| Customers           | `list_customers`, `get_customer`                                                                                                                            |
| Subscription offers | `create_subscription_offer`, `list_subscription_offers`, `get_subscription_offer`, `cancel_subscription`, `pause_subscription`, `resume_subscription`       |
| Refunds             | `create_refund`, `list_refunds`, `get_refund`                                                                                                               |
| Discounts           | `list_discounts`, `create_discount`, `get_discount`, `update_discount`, `delete_discount`                                                                   |
| Upsells             | `list_upsells`, `create_upsell`, `get_upsell`, `update_upsell`, `delete_upsell`                                                                             |
| Reviews             | `list_reviews`                                                                                                                                              |
| Webhooks            | `list_webhooks`, `create_webhook`, `get_webhook`, `update_webhook`, `delete_webhook`, `test_webhook`                                                        |
| Newsletters         | `list_posts`, `create_post`, `get_post`, `update_post`, `delete_post`, `send_post`, `send_email`, `list_subscribers`, `get_subscriber`, `delete_subscriber` |
| Link in Bio         | `get_creator_page`, `update_creator_page`                                                                                                                   |
| Partners            | `become_partner`, `get_partner`, `register_referral`, `list_referrals`, `list_referral_sales`, `get_partner_stats`                                          |
| Account             | `get_account`                                                                                                                                               |

<Note>
  `update_pricing` is an alias of `update_product` for agents that ask to
  change price. Creator payouts remain dashboard/JWT-only and are not exposed
  as MCP tools.
</Note>

<Note>
  The **Payments** tools expose the unified ledger (one-time purchases *and*
  subscription renewals), and the **subscriber** tools return live membership
  status plus full payment history — the same data as [`GET
      /payments`](/api-reference/introduction#payments) and [`GET
      /subscriptions/subscribers`](/api-reference/introduction#subscriptions-and-subscribers).
  Ask things like *"how much recurring revenue did I collect last month?"* or
  *"list my past-due subscribers."*
</Note>

<Note>
  The tool list is generated from the public API contract, so it stays in sync
  as the API evolves. Call `tools/list` on the endpoint (or check your agent's
  tool panel) for the authoritative, current set.
</Note>

## How it works

The MCP server is part of the Pocketsflow backend — there is no separate service to run or host. Each tool call is forwarded to the corresponding public REST endpoint with your API key, so validation, permissions, and per-account data scoping are identical to calling the API directly.

The transport is **stateless Streamable HTTP**: the agent POSTs JSON-RPC messages (`initialize`, `tools/list`, `tools/call`) to `/mcp` and receives a JSON response. No session state is stored server-side.

You can call it directly without an agent framework — every request carries your API key:

```bash theme={null}
curl https://api.pocketsflow.com/mcp \
  -H "Authorization: Bearer pk_test_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_orders",
      "arguments": { "pageSize": 20 }
    }
  }'
```

Because each tool maps to the underlying REST endpoint, tool arguments mirror the
endpoint's parameters (for example `list_orders` accepts pagination filters;
`create_subscription_offer` accepts offer fields; `update_pricing` /
`update_product` accept the product `id` plus fields to change). Errors surface
as MCP tool errors carrying the same status and message the REST endpoint would
return (for example a `401` for an invalid key). Use a `pk_test_…` key to
exercise everything safely against sandbox data first.

## Related topics

* [MCP setup guide](/ai-tools/mcp) — Claude Desktop, Cursor, ChatGPT
* [API reference](/api-reference/introduction) — the underlying REST endpoints
* [Authentication & security](/api-webhooks/authentication-and-security)
* [Webhooks & API overview](/api-webhooks/overview)