Integration Wizard

/toolify — Wire up an integration or MCP server

Interactive wizard for adding an external tool / API / MCP into a project. Ends with working code + env vars set + a verification path.

Scope

• Primary stacks: Next.js (App Router + TypeScript) and Rails. Reason: those are the two stacks the user actually ships in; supporting every stack bloats the wizard.
• What toolify handles: auth pattern (API key, OAuth, JWT, session cookie), env var setup, official SDK vs raw fetch, client wrapper location, example usage, webhook handling (if applicable), MCP .mcp.json wiring (if MCP server).
• What toolify does NOT handle: writing business logic on top of the integration (that's for the human). It scaffolds the plumbing, not the feature.

Step 0 — Get the tool name

Ask if not provided: "Which tool are we integrating?"

Detect category from name:

Category	Examples	Extra steps
Payments	Stripe, LemonSqueezy, Paddle	Webhook signature verification, customer model, event handlers
Auth	NextAuth/Auth.js, Clerk, Supabase Auth, Devise	Session management, protected routes, callbacks
Email	Resend, Postmark, SendGrid, Kit	From address, template setup, unsubscribe handling
CMS/DB	Sanity, Prisma, Drizzle, Neon, Supabase	Schema location, migration path, client singleton pattern
AI/LLM	Anthropic, OpenAI, Gemini, Vercel AI SDK	Model choice, streaming vs non-streaming, rate limits
Analytics	Fathom, PostHog, Plausible	Script placement, event tracking API
Scheduling/Comms	SavvyCal, Cal.com, Twilio, Riverside	Webhook events, embed patterns
Scraping	ScrapeCreators, Apify, Playwright	Rate limits, response caching, retry policy
Affiliate/Referral	Rewardful, PartnerStack	Cookie handling, webhook events, dashboard access
Storage	Vercel Blob, S3, R2	Bucket setup, signed URL pattern, presigned upload
MCP server	Any MCP — Sanity, Stripe, GitHub, Kit, etc.	.mcp.json entry + env vars, no client wrapper
Custom / other	Internal API, unknown tool	Ask more questions

If category detection fails, ask 2 questions to place it: "Is it an API you call, a webhook receiver, or both?" / "Does it have an official SDK?"

Step 1 — Structural interview

Ask the following in order (skip questions that don't apply based on category):

1. Which project? (path — infer from cwd; ask if ambiguous)
2. Which stack? (Next.js / Rails — infer from package.json vs Gemfile; ask if both)
3. Auth pattern? (API key / OAuth / JWT / session cookie / signed webhooks — usually knowable from official docs)
4. Official SDK exists? (check the docs; prefer SDK when good; fall back to raw fetch when SDK is bloated/abandoned)
5. Env var name convention? (default: SCREAMING_SNAKE_CASE matching official convention — e.g., STRIPE_SECRET_KEY, RESEND_API_KEY)
6. Environments? (dev / preview / prod — different keys?)
7. Webhook receiver needed? (YES for Stripe/Rewardful/most payment+auth+CMS; NO for pure client-side or read-only APIs)
8. Rate limits to respect? (grep official docs)
9. Where does the client wrapper live? (default: src/lib/<tool>.ts for Next.js; app/services/<tool>_client.rb for Rails)

Show the user the answers as a summary before scaffolding — one chance to correct before writing files.

Step 2 — Fetch official setup docs

Pull the current official quickstart. Prefer context7 if your agent has it (fresher docs than training data); otherwise fetch the official quickstart URL with your agent's URL-fetch tool (WebFetch in Claude Code) or curl.

Read once, then work from cached content. Don't re-fetch mid-scaffold. Note the SDK version cited so package.json gets the right pin.

Step 3 — Scaffold files

For a standard Next.js integration, generate:

src/lib/<tool>.ts                    # client singleton + typed wrappers
src/app/api/webhooks/<tool>/route.ts # webhook handler (if applicable)
src/app/api/<tool>/example/route.ts  # one working example route
.env.local.example                    # env var template with placeholder values

For Rails:

config/initializers/<tool>.rb        # SDK config
app/services/<tool>_client.rb        # client wrapper
app/controllers/webhooks/<tool>_controller.rb  # webhook handler if applicable
config/routes.rb                      # webhook route
.env.example                          # env vars

For an MCP server, only:

.mcp.json                             # add or update with the new server entry
.env.local                            # add the env vars the MCP needs

Every scaffolded file should have a comment at the top like:

// Scaffolded by /toolify on 2026-06-30. Official docs: <url>. SDK version: <version>.
// The client wrapper is scoped to plumbing only — business logic lives elsewhere.

Step 4 — Auth pattern implementation

Apply the right auth pattern per tool category. Never invent — use the pattern the official docs specify. Common patterns:

• API key in header: Authorization: Bearer <key> or X-<Vendor>-Key: <key> — check vendor's exact spelling
• Webhook signature: use the vendor's crypto method (Stripe uses HMAC-SHA256; Rewardful uses similar). NEVER skip signature verification on webhooks — it's the #1 security bug in scaffolded integrations.
• OAuth: redirect URL setup, token storage, refresh handling. Prefer Auth.js/NextAuth for Next.js; Devise + omniauth for Rails.
• Signed URL / presigned: for uploads / temp access — set expiration explicitly, never use unbounded.

Step 5 — Env var setup

Add to the appropriate file:

• Local dev: .env.local (Next.js) / .env (Rails) — NEVER committed
• Vercel: sensitivity depends on the var. Two rules — apply the right one:
  • Public / bundle-baked vars (NEXT_PUBLIC_*) — these get inlined into the client bundle at build time and are ALREADY public. Use --no-sensitive so you can audit them later:

    vercel env add NEXT_PUBLIC_APP_URL production --value "<url>" --no-sensitive --yes
    

  • Server-side secrets (API keys, webhook secrets, DB URLs) — never enter the client bundle. Use Vercel's default --sensitive behavior so the value is write-only via the CLI (can't be read back via vercel env pull):

    vercel env add STRIPE_SECRET_KEY production --value "<key>" --sensitive --yes
    vercel env add STRIPE_WEBHOOK_SECRET production --value "<secret>" --sensitive --yes
    

  • The rule: only NEXT_PUBLIC_* uses --no-sensitive. Everything else uses --sensitive. Getting this wrong means server secrets are readable via vercel env pull in someone's local terminal — same class of leak as committing them.
  • See references/vercel-env-vars.md for the full policy + verification via vercel env pull + brackets-check.
• Heroku: heroku config:set <VAR>=<value> -a <app-name>

Also update .env.example / .env.local.example with the placeholder so teammates know the var is needed.

Step 6 — Smoke test

Generate a one-line verification the user can run:

# Example for a REST API:
curl -H "Authorization: Bearer $STRIPE_SECRET_KEY" https://api.stripe.com/v1/customers?limit=1

# Example for an SDK:
node -e "const s = require('./src/lib/stripe.ts').default; s.customers.list({limit:1}).then(console.log)"

# For MCP: restart your agent so it reloads MCP config, run any command that touches the MCP server

Show the expected output shape. If the call fails, the wizard should be first to catch it, not the user in prod.

Step 7 — Report + follow-ups

Report:

• Files created (paths)
• Env vars added (names only — never values in the report)
• SDK/dependency added to package.json / Gemfile
• Smoke-test command run + result
• Any TODOs the user needs to complete manually (e.g., "add webhook URL to <vendor> dashboard")

Offer:

• "Set up a loopify cron to check the webhook is still receiving events daily?"
• "Save this integration recipe as a skill via skillify from-chat?"
• "Commit these changes now?"

Reference — integration recipes

Full recipes for common tools live in references/ (populate as they're used):

• references/stripe-nextjs.md — payment integration + webhook + customer portal
• references/kit-nextjs.md — Kit (ConvertKit) MCP + subscriber API
• references/sanity-nextjs.md — Sanity CMS + MCP + Studio embed
• references/anthropic-nextjs.md — Claude API + streaming + rate limits
• references/scrapecreators-nextjs.md — social scraping API + retry policy
• references/rewardful-nextjs.md — referral tracking + webhook events

If a recipe doesn't exist yet, the wizard fetches the official docs, scaffolds fresh, and offers to save the recipe as ${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/toolify/recipes/<tool>-<stack>.md for reuse (never inside the skill folder — upgrades wipe it). When looking up recipes, check both references/ (shipped) and the config recipes dir (yours).

Composes with

• skillify — sibling in -ify trifecta. Use skillify when the goal is a new SKILL.md, not an integration.
• loopify — sibling. Use loopify for setting up cron/agent-loop patterns on top of the toolified integration (e.g., poll a webhook, sync data daily).
• compound-engineering:context7 — fetch current SDK docs (fresher than training data).
• makerskills:watch-video — if the user has a Loom of an integration walkthrough, feed it in to synthesize the recipe.

Notes on quality

• Never skip webhook signature verification. Even for internal-only endpoints. The vendor provides the crypto pattern for a reason.
• Never commit secrets. .env.local and .env are gitignored — verify before finishing.
• Never invent auth patterns. Use the vendor's official pattern verbatim. If docs are unclear, fetch again.
• SDK version matters. Pin the SDK version in package.json / Gemfile.lock. Note the version in the file header comment.
• One tool per invocation. Don't scaffold Stripe + Kit + Sanity in one run. Wizard is designed for depth per tool, not breadth.
• Prefer official SDKs unless they're bloated/abandoned. Raw fetch is fine when the SDK adds no value.
• Recipe-first for repeat tools. If integrating a tool the user has done before, load the recipe from references/ or $MAKERSKILLS_CONFIG/toolify/recipes/ and adapt, don't re-derive.