InsForge Agent Skill

Credential Detection (MCP Mode)

When using MCP tools, credentials are often pre-configured. Before asking the user:

1. Try calling MCP tools first: Attempt get-backend-metadata or get-anon-key
2. If MCP succeeds: Credentials are already configured, proceed with work
3. If MCP fails with auth error: Then ask user for Project URL and API Key

Example: User says "deploy to insforge"
✓ Try: get-backend-metadata via MCP
✓ If success: Extract project URL from metadata, get anon key via get-anon-key
✗ If fail: Ask user for credentials

STOP: Check Credentials First (Manual Mode)

Only ask for credentials if MCP auto-detection fails. You need:

Action: If MCP tools fail and user has not provided credentials, ask now:

Do you have an InsForge project? I'll need:
1. Project URL (e.g., https://abc123.us-east-1.insforge.app)
2. API Key (starts with ik_)

You can find these in InsForge Dashboard → Project Settings.

When to Use Which Documentation

Use sdk-integration.md files when:

• Integrating InsForge services into the user’s frontend application
• Implementing features that run in the browser or client app
• Writing code that uses @insforge/sdk methods
• Examples: User login flow, fetching data, uploading files, real-time subscriptions

Use backend-configuration.md files when:

• Configuring the InsForge backend before the app can use a feature
• Creating database tables, storage buckets, or deploying serverless functions
• Setting up real-time channels or database triggers
• Managing auth settings, AI configurations, or deployments
• Examples: Creating a posts table, enabling OAuth providers, deploying an edge function

Typical Workflow

1. Backend Configuration → Configure infrastructure via HTTP API
2. SDK Integration → Use SDK in application code

Example: Adding file uploads

1. First create a storage bucket → see storage/backend-configuration.md
2. Then implement upload in the app → see storage/sdk-integration.md

Example: Adding user authentication

1. First configure auth settings → see auth/backend-configuration.md
2. Then implement login/signup → see auth/sdk-integration.md

First Step: Get Backend Metadata

Always get the backend metadata first before doing any work. This gives you the complete picture of the current project structure.

GET /api/metadata
Authorization: Bearer {admin-token-or-api-key}

This returns the full backend state including:

• Database: Tables, columns, relationships, indexes, RLS policies
• Auth: Configuration, OAuth providers, user stats
• Storage: Buckets and visibility settings
• Functions: Deployed functions and status
• AI: Configured models
• Realtime: Channel patterns

Understanding the existing backend structure before making changes prevents errors and helps you build on what’s already there.

Quick Setup

npm install @insforge/sdk@latest

import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: 'https://your-project.region.insforge.app',
  anonKey: 'your-anon-key'
})

Module Reference

What Each Module Covers

SDK Quick Reference

All SDK methods return { data, error }.

Backend API Quick Reference

Base URL: https://your-project.region.insforge.app

Authentication: Authorization: Bearer {admin-token-or-api-key}

Deployment Best Practices

ALWAYS: Local Build First

Before deploying to InsForge, verify the build works locally. Local builds are faster to debug and don’t waste server resources on avoidable errors.

# 1. Install dependencies
npm install

# 2. Set up environment variables for your framework
cp .env.example .env.local  # or create .env.production

# 3. Run production build
npm run build

Common build-time issues to fix before deploying:

Framework-Specific Notes

• Environment Variable Prefix: Use the correct prefix for your framework:

  • Vite: VITE_*
  • Next.js: NEXT_PUBLIC_*
  • Create React App: REACT_APP_*
  • Astro: PUBLIC_*

• Edge Functions: If your project has Deno/edge functions in a separate directory (commonly functions/), exclude them from your frontend build to avoid module resolution errors.

Deployment Checklist

• Local npm run build succeeds
• All required environment variables configured for production
• Edge function directories excluded from frontend build (if applicable)
• Build output directory matches your framework’s expected output

Important Notes

• Database inserts require array format: insert([{...}]) not insert({...})
• Storage: Save both url AND key to database for download/delete operations
• Functions invoke URL: /functions/{slug} (without /api prefix)
• Use Tailwind CSS v3.4 (do not upgrade to v4)
• Always local build before deploy: Prevents wasted build resources and faster debugging