pullpush-mcp-dev

MCP server for PullPush.ai platform development — connector authoring, canonical schema management, marketplace publishing, billing, partner admin, and batch operations.

This is the developer/admin companion to kaduno-pullpush-mcp. It exposes the full tool surface including platform administration tools that require elevated API keys.

Quick Start

Connect straight to the hosted endpoint — nothing runs on your machine. X-MCP-Scope: dev selects the full admin tool surface:

{
  "mcpServers": {
    "pullpush-dev": {
      "type": "streamable-http",
      "url": "https://api.pullpush.ai/mcp",
      "headers": {
        "Authorization": "Bearer <admin-or-org-key>",
        "X-MCP-Scope": "dev"
      }
    }
  }
}

For clients that only speak stdio, install a pinned version once and run the binary (avoid npx ...@latest, which re-resolves the package on every start):

npm i -g [email protected]

{
  "mcpServers": {
    "pullpush-dev": {
      "command": "pullpush-mcp-dev",
      "env": { "PULLPUSH_API_KEY": "<admin-or-org-key>" }
    }
  }
}

Add to ~/.cursor/mcp.json (Cursor) or your MCP client config.

The stdio proxy never exits because the API is unreachable: it starts, connects in the background with backoff, reconnects after a lost connection, answers tool calls with a retryable "reconnecting" error while offline, and serves a cached tool catalogue after a restart.

Requires an admin or org-level API key — tenant keys will work but with limited tool access.

Environment Variables

| Variable | Required | Default | Description | | --- | --- | --- | --- | | PULLPUSH_API_KEY | Yes | — | Admin or org-level API key | | PULLPUSH_API_URL | No | https://api.pullpush.ai | API base URL | | PULLPUSH_CACHE_DIR | No | OS cache directory | Where the tool catalogue is cached | | PULLPUSH_TIMEOUT_MS | No | 55000 | How long a tool call may take before the proxy answers with a timeout error |

CLI Flags

npx pullpush-mcp-dev --help      # Show usage help
npx pullpush-mcp-dev --version   # Show version

Tools Overview

Everything in kaduno-pullpush-mcp, plus:

Connector Development

• AI Generation — pullpush.connector.generate creates connector definitions from API docs
• Compose Loop — Iterative AI-driven connector refinement with test gates
• Live Test — Test connectors against real APIs in sandbox mode
• Discover Docs — AI-powered API documentation discovery

Canonical Schema Management

• Propose — Draft canonical type extensions with migration planning
• Extend — Add fields to live canonical types safely
• Activate — Promote draft schemas to active state

Marketplace

• Publish — Submit connectors to the community marketplace
• Stats — Connector install/usage analytics

Platform Admin

• Tenant Governance — Create tenants, manage registrations, approve access
• Billing — Subscriptions, usage, invoices, revenue metrics
• Partners — Partner orgs, commissions, payouts
• Backup — Configure automated backup policies and restore

Batch Operations

• preview-all — Preview sync across all active flows
• reconcile-all — Reconcile all flows in parallel
• health-matrix — Status dashboard across all connections
• pause-degraded — Auto-pause unhealthy flows

Guided Prompts

MCP prompts provide step-by-step workflows:

| Prompt | Use case | | --- | --- | | onboard-connector | Build a new connector from scratch | | extend-canonical | Add fields to a canonical type | | set-up-sync | Configure source→destination sync | | diagnose-flow | Systematic failure diagnosis | | shadow-cutover | Safely go live from shadow mode |

Which Package Do I Need?

| Package | Audience | Key | | --- | --- | --- | | kaduno-pullpush-mcp | Operators, tenants | Tenant or org key | | pullpush-mcp-dev | Developers, admins | Admin or org key |

If you only need to manage your own connections and flows, use kaduno-pullpush-mcp. If you build connectors, manage the platform, or need billing/partner tools, use this package.

Development

git clone <repo-url>
cd publish/mcp-dev
npm install
npm run dev    # Run from source via tsx
npm run build  # Compile with tsup

License

MIT