MCP: Using PullPush from AI Agents

PullPush ships an official Model Context Protocol (MCP) server: 47 tools (30 explicit tools plus 179 actions across 17 domain routers) that let AI agents — Claude, Cursor, or any MCP client — build, run, and monitor integrations end to end: connect two systems, preview the sync safely in shadow mode, and cut over to live.

The server is self-describing: agents don't need to be pre-briefed. A built-in get-started prompt walks from zero to a working integration, and pullpush:// resources expose the live tool catalog, quickstart, and agent guide.

Try it in 60 seconds — no signup

Request a free sandbox tenant (no auth, expires after 48 hours):

curl -X POST https://api.pullpush.ai/api/sandbox

The response contains an API key, ready-to-paste MCP client configs, and two pre-wired demo connections (a "warehouse" source and a "webshop" destination) whose stock data deliberately disagrees. Create a flow between them and run pullpush.sync action:"preview" — you'll see drifted quantities, a missing item, and in-sync rows as a structured canonical diff. The sandbox deletes itself when it expires; nothing to clean up.

Want to keep what you built? Claim the sandbox before it expires:

curl -X POST https://api.pullpush.ai/api/sandbox/claim \
  -H "Authorization: Bearer <your-sandbox-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

This converts it to a persistent free-plan tenant — connections, flows, and previews are all preserved, and the API key keeps working. If the email already has a PullPush account it becomes OWNER immediately; otherwise the response contains a signupUrl that creates the login and attaches it to the tenant.

Quick start

Run the published package via npx — no clone or install:

{
  "mcpServers": {
    "pullpush": {
      "command": "npx",
      "args": ["-y", "kaduno-pullpush-mcp@latest"],
      "env": {
        "PULLPUSH_API_KEY": "<your-api-key>"
      }
    }
  }
}

Or connect to the hosted remote endpoint directly:

{
  "mcpServers": {
    "pullpush": {
      "type": "streamable-http",
      "url": "https://api.pullpush.ai/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

Get an API key: sign up free, then admin panel → Settings → API Keys. Keys are scoped — a tenant key only ever sees that tenant's data.

Then ask your agent to run the get-started prompt. The flow it follows:

pullpush.connector action:"catalog" — see available integrations
pullpush.connection.create + pullpush.connection.test — connect source and destination (credentials are envelope-encrypted server-side the moment they're stored)
pullpush.mapping.suggest — AI-suggested field mapping between the two systems
pullpush.flow.create — wire the sync flow, starting in shadow mode (read-only)
pullpush.sync action:"preview" — structured source-vs-destination diff before anything is written
pullpush.shadow action:"cutover" — go live once the preview looks right

The main tools

Tool	What it does
`pullpush.connector`	Browse the connector catalog, inspect definitions, generate new connectors from API docs
`pullpush.connection.create` / `.test`	Create and live-test connections to external systems
`pullpush.connection`	Connection lifecycle: configure, poll, monitor health, OAuth
`pullpush.mapping.suggest`	AI-suggested canonical field mappings
`pullpush.flow.create` / `pullpush.flow`	Create flows; status dashboard, deliveries, retries
`pullpush.sync`	Preview diffs, run reconciliation, monitor sync state
`pullpush.shadow`	Enable shadow mode, compare, cut over to live
`pullpush.explain`	Diagnose why a flow, connection, or delivery failed — with evidence and suggested fixes
`pullpush.ops`	Health dashboards, anomaly detection, dead-letter queue recovery
`pullpush.workflow`	Multi-step DAG automations: branches, delays, lookups
`pullpush.tenant`	Tenant management (org/admin keys)

Every tool returns structured results, and errors come back as {code, suggestion, suggestedTool, retryable} — an agent always knows the next step. The full auto-generated reference for every tool and action ships with the server as the pullpush://tools/catalog resource, or live at GET /api/mcp/info (authenticated). A public machine-readable server card is at api.pullpush.ai/.well-known/mcp-server-card.json.

Resources and prompts

Resource / prompt	Purpose
`get-started` (prompt)	Guided first-run: zero to a working integration in shadow mode
`set-up-sync` (prompt)	Recipe-aware source→destination setup
`pullpush://tools/catalog`	Tool catalog grouped by workflow stage
`pullpush://docs/quickstart`	5-minute quickstart
`pullpush://docs/agent-guide`	How to drive PullPush as an autonomous agent

Auth scopes

Scope	Access
Tenant key	Your tenant's connections, flows, sync, diagnostics
Org key	All tenants in your organization (read or read+write)
Admin key	Full platform access (billing, partners, all tenants)

Safety model

Deterministic runtime — AI helps at build time (connector generation, mapping suggestions); the sync engine itself never calls an LLM
Shadow mode by default — new flows are read-only until explicitly cut over
Preview before write — structured canonical diffs show exactly what would change
Encrypted credentials — AES-256-GCM envelope encryption, per-tenant keys; secrets never appear in tool results or logs

ChatGPT

ChatGPT connects over the same remote MCP endpoint using OAuth (not an API key). See ChatGPT for Developer Mode setup, scopes, and troubleshooting. Public marketplace listing comes after docs are complete.