{
  "markdown": "# PullPush MCP — connect any two APIs and keep them in sync\n\n[![npm](https://img.shields.io/npm/v/kaduno-pullpush-mcp)](https://www.npmjs.com/package/kaduno-pullpush-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP%20registry-ai.pullpush%2Fpullpush--mcp-a855f7)](https://registry.modelcontextprotocol.io/v0/servers?search=ai.pullpush/pullpush-mcp)\n[![license](https://img.shields.io/badge/license-MIT-22c55e)](./LICENSE)\n\nThe official MCP server for [PullPush.ai](https://pullpush.ai) — an integration platform that\nconnects e-commerce stores, warehouses, marketplaces, ERPs, and POS systems, and keeps stock\nlevels, orders, and products in sync across all of them.\n\nThis server lets AI agents (Claude, Cursor, or anything that speaks\n[Model Context Protocol](https://modelcontextprotocol.io)) build, run, and monitor those\nintegrations end to end: connect two systems, preview the sync safely, and cut over to live —\nwithout a human clicking through a dashboard.\n\n## Why agents like it\n\n- **Deterministic runtime, no LLM in the hot path.** AI helps at build time (connector\n  generation, field-mapping suggestions); the sync engine itself is predictable, versioned,\n  and observable.\n- **Safe by default.** New flows start in **shadow mode** (read-only). `pullpush.sync`\n  `action:\"preview\"` shows a structured source-vs-destination diff before anything is written.\n- **Credentials never touch your machine or env.** Connection secrets are envelope-encrypted\n  (AES-256-GCM, per-tenant keys) server-side the moment they're created.\n- **Self-describing.** A `get-started` MCP prompt walks from zero to a working integration;\n  `pullpush://` resources expose the tool catalog, quickstart, and agent guide — no pre-briefing\n  needed.\n- **Structured, actionable errors.** Failures return `{code, suggestion, suggestedTool,\n  retryable}` — an agent always knows the next step.\n- **Server-grade reliability.** Circuit breakers, per-key ordered delivery, idempotency,\n  dead-letter queue with retry, exponential backoff.\n\n## Try it in 60 seconds — no signup\n\n```bash\ncurl -X POST https://api.pullpush.ai/api/sandbox\n```\n\nReturns a free 48-hour sandbox tenant: an API key, ready-to-paste MCP configs, and two\npre-wired demo connections whose stock data deliberately disagrees — so your first\n`pullpush.sync` `action:\"preview\"` shows a real canonical diff (drifted quantities, a missing\nitem, in-sync rows). The sandbox deletes itself on expiry — or keep it:\n`POST /api/sandbox/claim` (Bearer = the sandbox key, `{\"email\": \"...\"}`) converts it to a\npersistent free tenant with everything you built preserved.\n\n## Quick start\n\nNo clone or install needed — run directly via `npx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pullpush\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"kaduno-pullpush-mcp@latest\"],\n      \"env\": {\n        \"PULLPUSH_API_KEY\": \"<your-api-key>\"\n      }\n    }\n  }\n}\n```\n\nAdd this to `~/.cursor/mcp.json` (Cursor), Claude Desktop's config, or the MCP config for your\nclient. Prefer a remote server? Connect straight to the hosted endpoint instead:\n\n```json\n{\n  \"mcpServers\": {\n    \"pullpush\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://api.pullpush.ai/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer <your-api-key>\" }\n    }\n  }\n}\n```\n\nThen ask your agent to run the **`get-started`** prompt — it walks through the whole flow:\ncatalog connectors → create + test connections → suggest a field mapping → create the flow in\nshadow mode → preview the diff → cut over.\n\n## Getting an API key\n\nFor a throwaway key, use the sandbox above. For a persistent tenant:\n\n1. [Sign up free](https://app.pullpush.ai/sign-up) (1 connection, 1,000 events/month — no card)\n2. Admin panel → **Settings → API Keys**\n3. Create a key with the scope you need (tenant, org, or admin)\n\n## Tools\n\n**48 tools** (**30 explicit tools** plus **184 actions** across 18 domain routers) covering the\nfull integration lifecycle. Explicit tools are individually named; domain routers accept an\n`action` parameter with multiple operations.\n\n### Connections\n\n- `pullpush.connection.create` — Create and configure a connection to an external system (Shopify, WooCommerce, Linnworks, Xero, HubSpot, and 20+ more)\n- `pullpush.connection.test` — Test live connection credentials; returns health metrics and failure count\n- `pullpush.connection` — List, get, update, delete, and configure connections (router with actions: list, get, update, delete, health, config)\n\n### Flows\n\n- `pullpush.flow.create` — Wire a source→destination sync pipeline with triggers, mapping, and canonical data models\n- `pullpush.flow.dryRun` — Dry-run an event through flow transform/filter without delivery; returns mapped payload\n- `pullpush.flow.natural` — Create a flow from a natural-language description; proposes mapping and creates in shadow mode\n- `pullpush.flow` — List, get, update, pause/resume, delete flows and view delivery history (router)\n\n### Sync & reconciliation\n\n- `pullpush.sync.reconcile` — Reconcile-and-deliver: diff source vs destination, then deliver changes with per-item progress\n- `pullpush.sync` — Preview diffs, snapshot data, inspect single keys, scan catalogs, diagnose unmatched SKUs, manage baselines (router with actions: preview, snapshot, inspect, reconcile, scan, reset-baseline, baseline.history, baseline.rollback, channel-cache, unmatched)\n\n### Field mapping\n\n- `pullpush.mapping.suggest` — AI-proposes field mapping from source sample to target shape; returns mapping, confidence, preview\n- `pullpush.mapping.validate` — Validate a mapping config against source and destination schemas\n- `pullpush.mapping.compare` — Compare two mappings side by side\n- `pullpush.mapping.explain` — Explain how a mapping transforms data, step by step\n- `pullpush.mapping.diff` — Diff two mapping versions to see what changed\n- `pullpush.mapping.get` — Get a flow's current mapping config, source fields, and destination fields\n\n### Diagnostics\n\n- `pullpush.explain` — Diagnose why a flow, connection, or delivery failed; gathers errors, identifies patterns, suggests fixes\n- `pullpush.diagnose.recent` — Scan all flows for recent failures; returns a prioritized issue list\n- `pullpush.ask` — Answer natural-language ops questions using tenant failures and anomalies\n\n### Connector authoring\n\n- `pullpush.connector.generate` — AI-generates TypeScript connector code, typechecks, tests, and registers\n- `pullpush.connector` — List, get, update, and manage connector definitions (router)\n\n### Data operations\n\n- `pullpush.data.push` — Push file data (CSV, JSON, XML) into a connection\n- `pullpush.import` — File-based data import operations (router)\n- `pullpush.export` — Scheduled export pipelines: create, list, update, delete, test, run (router)\n- `pullpush.canonical` — Inspect and manage canonical data models (router)\n\n### Shadow mode & safety\n\n- `pullpush.shadow` — Run integrations read-only before going live; compare shadow vs live results (router)\n\n### Batch operations\n\n- `pullpush.batch.test` — Test multiple connections in parallel\n- `pullpush.batch.status` — Get status matrix across all flows\n- `pullpush.batch.setup` — One-call setup: create connections + flow + test in one operation\n- `pullpush.batch` — Multi-flow batch operations and proactive reports (router)\n\n### Ops & health\n\n- `pullpush.health.overview` — Tenant health dashboard: connections, flows, failures, backlog, delivery rate, anomalies\n- `pullpush.health.mcp` — MCP server health: database, tools registered, uptime\n- `pullpush.ops` — Anomaly detection, dead-letter recovery, operation monitoring (router)\n\n### Workflows\n\n- `pullpush.workflow.create` — Create multi-step workflow with trigger and step DAG\n- `pullpush.workflow.trigger` — Manually trigger a workflow run from an existing event\n- `pullpush.workflow` — List, get, and manage workflows (router)\n\n### Integrations & marketplace\n\n- `pullpush.integration.create` — Create an integration grouping flows/workflows under one name\n- `pullpush.integration` — List and manage integrations (router)\n- `pullpush.marketplace.install` — Install a marketplace listing into your tenant\n- `pullpush.marketplace` — Browse and manage marketplace connectors (router)\n- `pullpush.destination.provision` — Provision custom fields on destination API (e.g. HubSpot properties)\n\n### Administration\n\n- `pullpush.tenant` — Tenant management: list, get, create, update (router)\n- `pullpush.billing` — Subscription and usage management (router)\n- `pullpush.partner` — Partner program operations (router)\n- `pullpush.backup` — Backup and restore operations (router)\n- `pullpush.feedback` — Submit feedback about MCP tool quality or missing features\n\nFull tool reference: [pullpush.ai/docs/mcp](https://pullpush.ai/docs/mcp)\n\n## Environment variables\n\n| Variable | Required | Default | Description |\n| --- | --- | --- | --- |\n| `PULLPUSH_API_KEY` | Yes | — | Your PullPush API key |\n| `PULLPUSH_API_URL` | No | `https://api.pullpush.ai` | API base URL (override for self-hosted) |\n\n## Auth scopes\n\n| Scope | Access |\n| --- | --- |\n| **Tenant key** | Your tenant's connections, flows, sync, diagnostics |\n| **Org key** | All tenants in your organization (read or read+write) |\n| **Admin key** | Full platform access (billing, partners, all tenants) |\n\nTools are automatically scoped: a tenant key never sees another tenant's data.\n\n## Features\n\n- **Auto-refresh**: tool catalog refreshes every 5 minutes — new server-side tools appear\n  without a restart\n- **Offline quickstart**: built-in `pullpush://docs/quickstart-local` resource works without\n  network\n- **Retry on unknown tool**: automatically refreshes the catalog when a tool is not found\n- **Clear error messages**: auth failures, network issues, and version mismatches are explained\n\n## Documentation\n\n- [Getting started](https://pullpush.ai/docs/getting-started) — 5 minutes to a first integration\n- [MCP guide](https://pullpush.ai/docs/mcp) — full tool reference and client setup\n- [Shadow mode](https://pullpush.ai/docs/shadow-mode) · [Preview & reconcile](https://pullpush.ai/docs/preview-reconcile) · [Security](https://pullpush.ai/docs/security)\n- [llms.txt](https://pullpush.ai/llms.txt) — machine-readable product summary\n- [Machine-readable integration catalog](https://pullpush.ai/api/integrations)\n- MCP registry entry: [`ai.pullpush/pullpush-mcp`](https://registry.modelcontextprotocol.io/v0/servers?search=ai.pullpush/pullpush-mcp)\n\n## Also available: pullpush-mcp-dev\n\nFor connector authors, platform admins, and internal developers,\n[pullpush-mcp-dev](https://www.npmjs.com/package/pullpush-mcp-dev) exposes additional tools for:\n\n- AI-powered connector generation and composition\n- Canonical schema management\n- Marketplace publishing\n- Billing and partner administration\n- Batch operations across all tenants\n\n## Development\n\n```bash\ngit clone https://github.com/Kaduno-systems/pullpush-mcp.git\ncd pullpush-mcp\nnpm install\nnpm run dev    # Run from source via tsx\nnpm run build  # Compile with tsup\n```\n\nThis repository is a published mirror of the MCP client package; the platform itself is\ndeveloped in a private monorepo. Issues and questions are welcome here or at\n[hello@pullpush.ai](mailto:hello@pullpush.ai).\n\n## License\n\nMIT\n\n## Development\n\nDevelopment happens in the PullPush platform monorepo; the [Kaduno-systems/pullpush-mcp](https://github.com/Kaduno-systems/pullpush-mcp) repository is a published mirror of each release. Issues are welcome there; code changes land via the monorepo.\n",
  "bytes": 11481,
  "sha": "446096dbb8c2e3aa115ff01222040755d57072c55ebae61d40fde533d561d946",
  "repo_slug": "kaduno-systems/pullpush-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_pullpush_pullpush_mcp_9e3ae261/readme"
}