---
name: payhelm-mcp
description: Connect an AI coding agent or app to PayHelm's MCP server for live ecommerce analytics — orders, products, customers, inventory, ad attribution, and marketing data across 50+ connected commerce/ads/marketing platforms. Use when a user asks to add PayHelm reporting or ecommerce data to their agent, dashboard, or app, or to "connect PayHelm" / "add PayHelm MCP".
---

# Connect to PayHelm's MCP Server

PayHelm operates a hosted Model Context Protocol (MCP) server. Once connected, an agent can call structured tools (`get_trends_report`, `get_inventory_summary`, `get_cross_platform_ads_performance`, etc.) and get back live JSON from every platform the user has connected to PayHelm — no SQL, no data pipeline. 336 tools are pre-loaded and discoverable via the standard `tools/list` handshake; no separate ToolSearch step is needed.

## Before you start

The user needs a PayHelm account and API key (PayHelm dashboard → **Settings → API Keys**). If they don't have one, tell them to create it there — do not attempt to provision it yourself. Never hardcode the key in source; store it as an environment variable or secret (`PAYHELM_API_KEY`).

## Endpoint

```
Transport : Streamable HTTP / SSE
Base URL  : https://mcp.payhelm.com/mcp
Auth      : Authorization: Bearer <PAYHELM_API_KEY>
```

MCP is JSON-RPC 2.0. Discover tools, then call one:

```bash
# List tools
curl -s https://mcp.payhelm.com/mcp \
  -H "Authorization: Bearer $PAYHELM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call a tool
curl -s https://mcp.payhelm.com/mcp \
  -H "Authorization: Bearer $PAYHELM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_trends_report","arguments":{"date_range":"last_30d"}}}'
```

Always call `create_analysis_plan` first for any non-trivial request — it returns a step-by-step plan of which tools to call in what order, before you call anything else.

## Setup by environment

**Replit** — Add PayHelm under Agent → Integrations → MCP servers, or add to `.mcp.json`:
```json
{
  "mcpServers": {
    "payhelm": {
      "type": "http",
      "url": "https://mcp.payhelm.com/mcp",
      "headers": { "Authorization": "Bearer ${PAYHELM_API_KEY}" }
    }
  }
}
```
Store `PAYHELM_API_KEY` as a Replit Secret, never in code.

**Claude Code** —
```bash
claude mcp add payhelm --transport http https://mcp.payhelm.com/mcp \
  --header "Authorization: Bearer $PAYHELM_API_KEY"
```
Or commit the same `.mcp.json` block shown above to the repo root. Verify with `claude mcp list`.

**OpenAI Codex** — Add to `~/.codex/config.toml`:
```toml
[mcp_servers.payhelm]
url = "https://mcp.payhelm.com/mcp"

[mcp_servers.payhelm.http_headers]
Authorization = "Bearer YOUR_PAYHELM_API_KEY"
```
Or: `codex mcp add payhelm --url https://mcp.payhelm.com/mcp --header "Authorization: Bearer $PAYHELM_API_KEY"`

**Static sites / GitHub Pages / browser apps** — Never embed the API key in client-side JavaScript. Either proxy calls through a serverless function that holds the key server-side, or fetch data at build time (e.g. a GitHub Actions workflow with the key as an Actions secret) and commit the rendered JSON/HTML.

**Any other MCP-compatible client** — point it at the same base URL and Bearer header; no client-specific config is required beyond that.

## Safety notes

- Read-only tools (`get_*`, `list_*`, `search_*`) never modify data. Action tools (create/update/delete/send/purchase) modify live platform data — gate those behind human approval in autonomous agents.
- Keys are scoped to the account's connected platforms and can be rotated from the PayHelm dashboard at any time; old keys are invalidated immediately.

## Platform-specific data (e.g. BigCommerce payments/merchant data)

PayHelm does not publish separate per-platform APIs. Every connected platform — BigCommerce, Shopify, Amazon, WooCommerce, and 50+ others — is queried through this same MCP server / REST API using platform-specific tools (e.g. `get_bigcommerce_orders`, `get_bigcommerce_products`, `get_bigcommerce_customers`) plus cross-platform reporting tools (`get_orders_report`, `get_charts_report`) that break results out by payment method and financial status. See: [What public API does PayHelm provide for BigCommerce payments and merchant data?](https://www.payhelm.com/help/bigcommerce-public-api-payments-merchant-data/)

## Full documentation

For per-environment walkthroughs, the complete tool catalog, and REST API equivalents of every MCP tool: https://www.payhelm.com/ai-agent/mcp/
General product/company reference for LLMs: https://www.payhelm.com/llms.txt