> ## 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 setup guide

> Copy-paste setup for the Pocketsflow MCP server in Claude Desktop, Cursor, and ChatGPT — auth, first tool call, and what to try next.

Connect any [Model Context Protocol](https://modelcontextprotocol.io) client to
your Pocketsflow account. The hosted server at
`https://api.pocketsflow.com/mcp` exposes the full public API as tools — create
products, read orders, issue refunds, manage webhooks, send newsletters, and
more — scoped by your API key.

<Card title="Endpoint" icon="plug" horizontal>
  `https://api.pocketsflow.com/mcp` — Streamable HTTP. Authenticate with
  `Authorization: Bearer <API key>`.
</Card>

This page is the **copy-paste setup guide**. For the full tool list and how the
server works, see [MCP server](/api-reference/mcp-server). For editor-specific
workflows (project rules, scaffolding), see
[Claude Code](/ai-tools/claude-code), [Cursor](/ai-tools/cursor), and
[Windsurf](/ai-tools/windsurf).

## 1. Create an API key (auth)

Every MCP connection uses the same **API keys** as the REST API.

1. Open the dashboard → **Developers → API keys**.
2. Create a key. Prefer **`pk_test_…`** while you set things up.
3. Copy the key once — it is shown only at creation.

| Prefix      | Mode | Use                                      |
| ----------- | ---- | ---------------------------------------- |
| `pk_test_…` | Test | Sandbox data. No real money. Start here. |
| `pk_live_…` | Live | Real products, customers, and payments.  |

Send it on every request:

```
Authorization: Bearer pk_test_xxxxxxxxxxxxxxxxxxxxxxxx
```

<Warning>
  Treat API keys like passwords. An agent with a `pk_live_…` key can create and
  delete real data. Use a dedicated, revocable key per client, keep configs out
  of git, and rotate if a key leaks.
</Warning>

## 2. Add the server to your client

Pick your client and paste the config. Replace the placeholder key with yours.

<Tabs>
  <Tab title="Claude Desktop">
    Claude Desktop's local config only launches **stdio** servers. Bridge the
    hosted HTTP endpoint with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote)
    (requires [Node.js](https://nodejs.org) 18+).

    1. Open **Settings → Developer → Edit Config** (creates
       `claude_desktop_config.json` if needed).
    2. Merge the block below into `mcpServers`.
    3. **Quit Claude Desktop completely** and relaunch.

    **Config paths**

    | OS      | Path                                                              |
    | ------- | ----------------------------------------------------------------- |
    | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
    | Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |
    | Linux   | `~/.config/Claude/claude_desktop_config.json`                     |

    ```json theme={null}
    {
      "mcpServers": {
        "pocketsflow": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://api.pocketsflow.com/mcp",
            "--header",
            "Authorization:${AUTH_HEADER}"
          ],
          "env": {
            "AUTH_HEADER": "Bearer pk_test_xxxxxxxxxxxxxxxxxxxxxxxx"
          }
        }
      }
    }
    ```

    <Note>
      Put the Bearer value in `env`, not inline in `args`. Claude Desktop does
      not escape spaces in args reliably (especially on Windows) — the
      `Authorization:${AUTH_HEADER}` form avoids that.
    </Note>

    After restart, open a new chat and confirm **pocketsflow** tools appear
    under the hammer / tools menu.

    <Tip>
      Prefer the terminal? [Claude Code](/ai-tools/claude-code) supports remote
      HTTP natively:

      ```bash theme={null}
      claude mcp add --transport http pocketsflow https://api.pocketsflow.com/mcp \
        --header "Authorization: Bearer pk_test_xxxxxxxxxxxxxxxxxxxxxxxx"
      ```
    </Tip>
  </Tab>

  <Tab title="Cursor">
    Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json`
    (per project):

    ```json theme={null}
    {
      "mcpServers": {
        "pocketsflow": {
          "url": "https://api.pocketsflow.com/mcp",
          "headers": {
            "Authorization": "Bearer pk_test_xxxxxxxxxxxxxxxxxxxxxxxx"
          }
        }
      }
    }
    ```

    Reload Cursor (or toggle the server in **Settings → MCP**). In **Agent**
    mode, Composer lists the Pocketsflow tools automatically.

    <Warning>
      Keep `mcp.json` out of version control — it contains your API key.
    </Warning>

    Deeper Cursor workflow (project rules, OpenAPI docs index):
    [Cursor + Pocketsflow](/ai-tools/cursor).
  </Tab>

  <Tab title="ChatGPT">
    ChatGPT connects to **remote HTTPS** MCP servers only (no local stdio).
    Custom connectors need **Developer Mode** on a paid plan (Plus, Pro, Team,
    Enterprise, or Edu).

    <Steps>
      <Step title="Enable Developer Mode">
        In ChatGPT, open **Settings → Apps & Connectors → Advanced settings**
        (wording may be under **Security and login** on some builds) and turn
        **Developer Mode** on.
      </Step>

      <Step title="Create a connector">
        Go to **Settings → Apps & Connectors** (or
        [chatgpt.com/connectors](https://chatgpt.com/connectors)) → **Create** /
        **Add custom connector**. Fill in:

        | Field          | Value                                |
        | -------------- | ------------------------------------ |
        | Name           | `Pocketsflow`                        |
        | Description    | Operate my Pocketsflow store via MCP |
        | Connector URL  | `https://api.pocketsflow.com/mcp`    |
        | Authentication | **Token** (Bearer)                   |
        | Token          | `pk_test_xxxxxxxxxxxxxxxxxxxxxxxx`   |
      </Step>

      <Step title="Use it in a chat">
        Start a new conversation → **+** → enable the **Pocketsflow** app /
        Developer Mode tools → ask something read-only first (see below).
      </Step>
    </Steps>

    <Note>
      If the UI asks for a custom header instead of a Token field, set
      `Authorization` to `Bearer pk_test_…` (including the `Bearer ` prefix).
      Workspace admins on Business/Enterprise may need to allow custom
      connectors first.
    </Note>
  </Tab>
</Tabs>

## 3. First tool call walkthrough

Once the client shows Pocketsflow tools, verify the connection with a
**read-only** call before anything that writes.

<Steps>
  <Step title="Confirm the account">
    Ask:

    > Using the Pocketsflow tools, call `get_account` and summarize who I'm
    > authenticated as.

    You should see your store / account details. A 401 or "API key" error means
    the header is missing, mistyped, or the key was revoked — fix the config and
    reload the client.
  </Step>

  <Step title="List products">
    Ask:

    > List my products with `list_products`.

    Empty is fine in a fresh test account — a successful empty list still proves
    auth and tool discovery work. (`list_products` takes no filters today.)
  </Step>

  <Step title="Create something in test mode">
    With a `pk_test_…` key:

    > Create a \$19 product called "MCP Starter Kit" and give me a checkout link.

    The agent should call `create_product` then
    `create_checkout_session` and return a hosted checkout URL. Open it to
    confirm the sandbox product.
  </Step>
</Steps>

### Handy prompts

| Goal          | Say                                                           |
| ------------- | ------------------------------------------------------------- |
| Recent sales  | *"List my last 10 orders and their totals."*                  |
| Subscriptions | *"Which subscribers are past due?"*                           |
| Discount      | *"Create a 20% off code LAUNCH that expires in 7 days."*      |
| Refund        | *"Refund order `ord_…` and confirm the status."*              |
| Webhook check | *"List my webhooks and send a test event to the first one."*  |
| Newsletter    | *"Draft a post announcing the new product — don't send yet."* |

<Tip>
  Destructive or expensive actions (refunds, deletes, live sends) deserve an
  explicit confirmation in the chat. Prefer `pk_test_…` until the flow is
  trusted.
</Tip>

## 4. Verify without an AI client

You can hit the same endpoint with `curl` to isolate client vs. server issues:

```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": "get_account",
      "arguments": {}
    }
  }'
```

A JSON result with account fields means the key and endpoint are healthy — if
the AI client still fails, re-check its config and reload.

## Troubleshooting

| Symptom                         | Likely fix                                                                                                |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Tools never appear              | Reload / fully quit the client; confirm JSON is valid; for Claude Desktop ensure Node/`npx` is on `PATH`. |
| `401` / "API key"               | Key missing `Bearer ` prefix, wrong env var, or revoked key. Recreate under **Developers → API keys**.    |
| ChatGPT can't reach the server  | Must be public HTTPS — `https://api.pocketsflow.com/mcp` already is. Localhost URLs will not work.        |
| Writes affect live data         | You used `pk_live_…`. Switch the config to `pk_test_…` and reload.                                        |
| Claude Desktop drops the server | Config only accepts stdio — use the `mcp-remote` block above, not a bare `url` field.                     |

## Related topics

* [MCP server](/api-reference/mcp-server) — tool catalog and transport details
* [Authentication & security](/api-webhooks/authentication-and-security)
* [Developer setup](/development)
* [Claude Code + Pocketsflow](/ai-tools/claude-code)
* [Cursor + Pocketsflow](/ai-tools/cursor)
* [Windsurf + Pocketsflow](/ai-tools/windsurf)