# Connect an AI Agent (MCP)

> Manage your product feeds from Claude Code, Codex, or Cursor — connect the Simple Product Feeds MCP server with your API key in under two minutes.

Simple Product Feeds ships a hosted [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server, so any MCP-capable agent — Claude Code, Codex, Cursor, and others — can inspect, explain, and fix your feeds by talking to it in plain language.

**Endpoint:** `https://app.simpleproductfeeds.com/v1/mcp`
**Auth:** your API key as a Bearer token (create one in the app under Settings → API keys)

The tools cover the full loop — inspect, explain, fix, publish, verify:

| Tool | What it does |
|------|--------------|
| `spf_list_feeds` | List your feeds with type, product count, run status, and feed URL. |
| `spf_feed_health` | One-call health digest: run status, included/excluded scope counts, and per-channel validation errors and warnings. |
| `spf_feed_findings` | Drill into validation problems: issue categories with affected fields, counts, and sample rows with Shopify admin links. |
| `spf_feed_products` | Browse the transformed feed rows themselves — searchable, paginated, with exclusion verdicts. |
| `spf_debug_row` | Explain why any product row came out the way it did — transformed output and rule-attributed exclusion reasons, optionally rendered per channel. |
| `spf_channel_status` | Channel connections at a glance, with recent sync logs per channel. |
| `spf_preview_rule` | Dry-run a rule before applying: field-level before/after diffs on sample products, plus a preview token. |
| `spf_apply_rule` | Create or update a rule (requires the preview token — agents must show you the diff first), or activate/deactivate one. |
| `spf_set_overrides` | Override product values in the feed (title, brand, condition, exclusion, custom labels…) without touching Shopify. |
| `spf_restore_overrides` | The undo: restore products to their original Shopify values. |
| `spf_run_feed` | Publish changes (regenerate from the existing snapshot) and poll the run to completion. |
| `spf_update_mappings` | Remap which Shopify column feeds each feed column. Overrides overlay the defaults; setting a value to null restores the default — every remap is undoable. |
| `spf_sync_channel` | Trigger a channel sync — SFTP upload for Commission Junction, a fetch-now request for Google Merchant Center — and watch it via the sync logs. |
| `spf_set_cells` | Edit individual source cells on any product row — the same cells the in-app spreadsheet edits. Null restores the original; preview mode dry-runs the row first. |
| `spf_set_margin_tiers` | Assign each product a margin tier written to a custom label — by product category (no cost data needed) or by computed margin band — for per-margin bidding in Google Shopping. |

**Writing changes is preview-first by design.** An agent cannot create or modify a rule without first previewing it — the apply call requires a signed token proving the exact rule text was previewed. Overrides and mappings are typed, validated, and undoable, and validation counts recompute automatically after writes. Every agent mutation is recorded in a per-shop audit trail: which tool, which API key, what arguments, when.

## Claude Code

**Fastest path — the plugin** (MCP connection + the feed-ops skill: proven workflows and feed domain knowledge, loaded on demand):

```
/plugin marketplace add simpleproductfeeds/skills
/plugin install simple-product-feeds@simpleproductfeeds
```

Set `SPF_API_KEY` in your environment and you're connected. Update later with `/plugin marketplace update simpleproductfeeds`. The skill's source (and a plain-skills install path) lives at [github.com/simpleproductfeeds/skills](https://github.com/simpleproductfeeds/skills).

**Or connect just the MCP server:**

```bash
claude mcp add --transport http simple-product-feeds \
  https://app.simpleproductfeeds.com/v1/mcp \
  --header "Authorization: Bearer $SPF_API_KEY"
```

Or commit a project-scoped `.mcp.json` (the `${SPF_API_KEY}` placeholder reads from the environment, so no secret lands in git):

```json
{
  "mcpServers": {
    "simple-product-feeds": {
      "type": "http",
      "url": "https://app.simpleproductfeeds.com/v1/mcp",
      "headers": { "Authorization": "Bearer ${SPF_API_KEY}" }
    }
  }
}
```

## Codex

Add to `~/.codex/config.toml` — `bearer_token_env_var` names the environment variable holding your key:

```toml
[mcp_servers.simple-product-feeds]
url = "https://app.simpleproductfeeds.com/v1/mcp"
bearer_token_env_var = "SPF_API_KEY"
```

## Cursor

Add to `mcp.json`:

```json
{
  "mcpServers": {
    "simple-product-feeds": {
      "url": "https://app.simpleproductfeeds.com/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:SPF_API_KEY}" }
    }
  }
}
```

## Agencies: one connection per client shop

Organization keys (`spf_org_sk_...`) manage many client shops. Select the shop in the connection URL:

```
https://app.simpleproductfeeds.com/v1/mcp?shop_id=123
```

Add one MCP server entry per client shop (e.g. `spf-clientname`), each with the same org key and a different `shop_id`. Shop IDs come from [`GET /v1/org/shops`](/docs/api/admin-api).

## Tell your agent about us (AGENTS.md / CLAUDE.md)

If your project has an `AGENTS.md` or `CLAUDE.md`, paste this so any agent working in the repo knows the feed tool exists:

```markdown
## Product feeds (Simple Product Feeds)
This store's product feeds are managed by Simple Product Feeds. An MCP
server exposes the full loop — diagnose, trace rows, fix (preview-first),
publish, verify: https://app.simpleproductfeeds.com/v1/mcp (Bearer
$SPF_API_KEY). Live docs: https://www.simpleproductfeeds.com/llms.txt ·
REST API: https://app.simpleproductfeeds.com/v1/openapi.json · Deeper
skill: https://github.com/simpleproductfeeds/skills
```

## Try it

Once connected, ask your agent:

> Show me the health of my Google feed.

or

> Why is product variant 46618568622245 excluded from my primary feed?

## Notes

- The server is stateless JSON-RPC over Streamable HTTP: one request per POST, plain JSON responses, no session to manage.
- Rate limit: 120 requests/minute per key, shared with the REST API.
- claude.ai (web) custom connectors require OAuth and aren't supported yet — use Claude Code, Codex, or Cursor for now.