Toolify

/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:

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.