`docs/research/connectors.md`

109 lines
# VenturaClaw — Connector Research Report

**Generated:** 2026-05-05 by `exa-agent`
**Connectors verified:** 56 / 56
**Confidence:** 50 high · 6 marked `_uncertain` (shopify_payments, adobe, godaddy, sucuri, zapier, paper) or `public_api:false` (paper, purelymail)

Canonical machine-readable source: `lib/mcp/connector-specs.json` (schema v2).

---

## Executive summary

- All 56 connectors have verified-from-official-docs specs with auth method, scopes, API base URL, rate limits, webhook support, MCP availability, top SMB actions/triggers, difficulty, and source citations.
- **Hardest docs to find:** Sucuri (paid scan API, key-in-URL only), Action Network (partner-feature gated), Adobe (fragmented across products).
- **Existing public MCP servers (15):** Shopify, Stripe, Slack, HubSpot, Square, Notion, Browserbase, Postgres, Cloudflare, Twilio, Figma (Dev Mode), Paper (built-in desktop), Zapier (paid remote), AWS umbrella, monday.
- **App-review blockers for v1:** TikTok (mandatory video.publish review with end-to-end demo), Instagram (content_publish + manage_messages), Facebook (pages_manage_posts + business verification), YouTube Shorts (10k unit/day quota = ~6 uploads/day until expansion form approved), LinkedIn (Marketing Developer Platform partner approval, multi-week), X/Twitter (Free tier kneecaps to 1.5k posts/mo; SMBs need $200/mo Basic), Salesforce (Connected App + admin work).
- **Recommended v1 phasing — easy/medium connectors only:** Stripe + Shopify + Gmail + Slack + Mailchimp + Klaviyo + HubSpot + Notion + Airtable + Twilio + ClickUp + Asana + Cloudflare + Vercel + Browserbase + Postgres + Supabase. Defer all hard/app-review connectors to v2.

---

## Surprising findings

- **Paper has NO public REST API.** Integration is MCP-only via local Paper Desktop app (port 29979).
- **Purelymail has NO REST API at all.** SMTP/IMAP only. Footer email-routing only — not a Zapier-style connector.
- **Pinterest has NO webhooks.** Polling required for everything.
- **LinkedIn has no general webhooks.** Compliance API is private partner-approval.
- **YouTube's default 10k-unit quota = ~6 uploads/day.** Almost every SMB hits this on day one. Expansion form is the gate.
- **Shopify's REST Admin API became LEGACY Oct 2024.** All new public apps must use GraphQL.
- **Klaviyo's revision header is mandatory** and date-versioned (e.g. `revision: 2026-04-15`). Easy to miss.
- **Reddit's Devvit framework is now the blessed extension path,** not raw OAuth.
- **Notion's MCP went remote-OAuth.** The local one is being sunset.
- **Trello requires creating a Power-Up first** before you can mint an API key (recent change).

---

## Per-connector specs

For each connector, see `lib/mcp/connector-specs.json` → `connectors.<slug>`. Fields:

| Field | Meaning |
|---|---|
| `official_docs_url` | Canonical REST/GraphQL reference URL |
| `auth_method` | oauth2 / api_key / hmac / basic / smtp |
| `oauth_scopes` | Required OAuth scopes (if oauth2) |
| `api_base_url` | Production API base |
| `rate_limits` | Documented limits per minute / hour / day |
| `webhook_support` | true if push events available |
| `mcp_server` | Canonical npm package or GitHub repo, or "none" |
| `priority_actions` | Top 5 SMB-relevant write actions |
| `priority_triggers` | Top 3 SMB-relevant events |
| `difficulty` | easy / medium / hard |
| `notes` | Gotchas, restrictions, app-review requirements |
| `_uncertain` | true → fields need human verification before production use |
| `public_api` | false → tool integrates only via desktop/SMTP, not HTTP API |

---

## v1 launch plan (recommended)

Wire these 17 connectors with REAL API calls before public launch. All are `easy` or `medium` difficulty with no app review required (or trivial review).

| Connector | Auth | MCP available | Effort |
|---|---|---|---|
| Stripe | api_key | ✓ official | 1 day |
| Shopify | oauth2 | ✓ official + community | 2 days |
| Gmail | oauth2 | community | 1.5 days |
| Slack | oauth2 | ✓ official | 1 day |
| Mailchimp | oauth2 | none | 1.5 days |
| Klaviyo | oauth2 | none | 1.5 days |
| HubSpot | oauth2 | ✓ remote official | 1 day |
| Notion | oauth2 | ✓ official | 0.5 day |
| Airtable | oauth2 | community | 1 day |
| Twilio | basic | ✓ official | 0.5 day |
| ClickUp | oauth2 | community | 1 day |
| Asana | oauth2 | community | 1 day |
| Cloudflare | api_key | ✓ official | 0.5 day |
| Vercel | api_key | community | 0.5 day |
| Browserbase | api_key | ✓ official | 0.5 day |
| Postgres | basic | ✓ official | 0.5 day |
| Supabase | api_key | community | 1 day |

**Total v1 effort estimate:** ~15 engineering days.

---

## v2 connectors (deferred — app review or partner approval required)

| Connector | Blocker |
|---|---|
| Instagram | content_publish app review + business verification |
| TikTok | video.publish review with end-to-end demo video |
| Facebook Pages | pages_manage_posts + business verification |
| LinkedIn | Marketing Developer Platform partner approval |
| YouTube Shorts | 10k quota expansion form |
| X / Twitter | $200/mo Basic tier required |
| Threads | content_publish review |
| Salesforce | Connected App + customer admin work |
| Action Network | Partner feature access |
| GoDaddy | Reseller-tier required for new API keys |
| Sucuri | Paid scan API add-on |
| Adobe | Adobe Partner program registration |
| Shopify Payments | Partner-gated (use Stripe/PayPal instead for SMBs) |

---

## Sources

Per-connector source URLs are stored in the JSON spec file. Every claim cites at least one official-docs URL or canonical GitHub repo. No marketing pages used.