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

# MCP Server

> Integrate PagAmerican directly into AI agents like Claude and Cursor via the Model Context Protocol.

The **PagAmerican MCP Server** exposes the Data API as native tools for AI agents compatible with the [Model Context Protocol](https://modelcontextprotocol.io). Once connected, you can ask Claude, Cursor, or any MCP client to pull your sales in natural language — no code required.

<Info>
  It's a **remote server** — nothing to install. Authentication uses the **same `clientId` + `apiKey`** as the REST API, sent as the `X-Client-ID` and `X-Api-Key` headers, and the tools automatically return only the data that belongs to you (your tenant scope is enforced server-side).
</Info>

***

## Prerequisites

* A credential pair (`clientId` + `apiKey`) provided by the PagAmerican team, with the `analytics.read` scope — see [Authentication](/authentication)
* An MCP-compatible client (Claude Desktop, Cursor, Claude Code, …)

***

## Configuration

The server lives at `https://external-api-service.pagamerican.app/mcp` (Streamable HTTP transport).

<Tabs>
  <Tab title="Claude Desktop">
    Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):

    ```json theme={null}
    {
      "mcpServers": {
        "pagamerican": {
          "url": "https://external-api-service.pagamerican.app/mcp",
          "headers": {
            "X-Client-ID": "YOUR_CLIENT_ID",
            "X-Api-Key": "YOUR_API_KEY"
          }
        }
      }
    }
    ```

    Restart Claude Desktop. The `purchases_list` and `orders_list` tools appear in the tool picker.

    <Note>
      Older Claude Desktop versions don't support remote servers directly. In that case, bridge it with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote): set `"command": "npx"` with `"args": ["-y", "mcp-remote", "https://external-api-service.pagamerican.app/mcp", "--header", "X-Client-ID:YOUR_CLIENT_ID", "--header", "X-Api-Key:YOUR_API_KEY"]`.
    </Note>
  </Tab>

  <Tab title="Cursor">
    Edit `~/.cursor/mcp.json` (or **Settings → MCP → Add server**):

    ```json theme={null}
    {
      "mcpServers": {
        "pagamerican": {
          "url": "https://external-api-service.pagamerican.app/mcp",
          "headers": {
            "X-Client-ID": "YOUR_CLIENT_ID",
            "X-Api-Key": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code (CLI)">
    ```bash theme={null}
    claude mcp add --transport http pagamerican \
      https://external-api-service.pagamerican.app/mcp \
      --header "X-Client-ID: YOUR_CLIENT_ID" \
      --header "X-Api-Key: YOUR_API_KEY"
    ```
  </Tab>
</Tabs>

<Warning>
  Treat `X-Api-Key` like a password. Don't commit these config files to a public repository or share them in screenshots.
</Warning>

***

## Available tools

| Tool             | Maps to                 | Description                                                           |
| ---------------- | ----------------------- | --------------------------------------------------------------------- |
| `purchases_list` | `GET /api/v1/purchases` | Lists your purchases for a date range                                 |
| `orders_list`    | `GET /api/v1/orders`    | Lists your completed orders — one item per purchase inside each order |

Both tools take `from` and `to` (`YYYY-MM-DD`; `to` is exclusive, max 90 days from `from`) and an optional `limit` (1–5000, default 1000).

<Note>
  `orders_list` is available for **creator** credentials only — with affiliate keys the tool isn't listed. Affiliates get the same data through `purchases_list`.
</Note>

***

## Example prompts

Once connected, try:

* *"List my sales between April 1 and May 1, 2026."*
* *"How much revenue did I make last week? Use the purchases tool."*
* *"Show my top 10 most recent purchases and their payment methods."*
* *"Which orders were completed in July? Use the orders tool."*

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 — Missing or invalid credentials">
    Make sure both `X-Client-ID` and `X-Api-Key` headers are set with your exact `clientId` and `apiKey`. If the key was revoked or regenerated, update your config and restart the client.
  </Accordion>

  <Accordion title="403 — Insufficient scope">
    Your credentials must have the `analytics.read` scope. Contact the PagAmerican team if your key is missing it.
  </Accordion>

  <Accordion title="The tool doesn't show up">
    Fully restart the AI client after editing the config (a reload isn't always enough). Confirm the JSON is valid and the `url` has no typos. On older Claude Desktop, use the `mcp-remote` bridge shown above.
  </Accordion>

  <Accordion title="Date range error">
    `to` is exclusive and the window can't exceed 90 days. To get April, ask for `from=2026-04-01` to `to=2026-05-01`.
  </Accordion>
</AccordionGroup>

***

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    How to obtain your `clientId` and `apiKey`.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/purchases/list-purchases">
    The same data over plain REST, with a "Try it" playground.
  </Card>
</CardGroup>