Imported from xavierzaidane/tokengecko (
AGENTS.md). Install upstream withnpx skills add xavierzaidane/tokengecko. Copyright stays with the author.
description: Instructions building apps with MCP globs: * alwaysApply: true
InsForge SDK Documentation - Overview
What is InsForge?
Backend-as-a-service (BaaS) platform providing:
- Database: PostgreSQL with PostgREST API
- Authentication: Email/password + OAuth (Google, GitHub)
- Storage: File upload/download
- AI: OpenRouter key provisioning and model catalog for direct OpenAI-compatible integrations
- Functions: Serverless function deployment
- Realtime: WebSocket pub/sub (database + client events)
Installation
The following is a step-by-step guide to installing and using the InsForge TypeScript SDK for Web applications. If you are building other types of applications, please refer to:
- Swift SDK documentation for iOS, macOS, tvOS, and watchOS applications.
- Kotlin SDK documentation for Android applications.
- REST API documentation for direct HTTP API access.
🚨 CRITICAL: Follow these steps in order
Step 1: Download Template
Use the download-template MCP tool to create a new project with your backend URL and anon key pre-configured.
Step 2: Install SDK
npm install @insforge/sdk@latest
Step 3: Create SDK Client
You must create a client instance using createClient() with your base URL and anon key:
import { createClient } from '@insforge/sdk';
const client = createClient({
baseUrl: 'https://your-app.region.insforge.app', // Your InsForge backend URL
anonKey: 'your-anon-key-here' // Get this from backend metadata
});
API BASE URL: Your API base URL is https://your-app.region.insforge.app.
Getting Detailed Documentation
🚨 CRITICAL: Always Fetch Documentation Before Writing Code
InsForge provides official SDKs and REST APIs, use them to interact with InsForge services from your application code.
- TypeScript SDK - JavaScript/TypeScript
- Swift SDK - iOS, macOS, tvOS, and watchOS
- Kotlin SDK - Android and Kotlin Multiplatform
- REST API - Direct HTTP API access
Before writing or editing any InsForge integration code, you MUST call the fetch-docs or fetch-sdk-docs MCP tool to get the latest SDK documentation. This ensures you have accurate, up-to-date implementation patterns.
Use the InsForge fetch-docs MCP tool to get specific SDK documentation:
Available documentation types:
"instructions"- Essential backend setup (START HERE)"real-time"- Real-time pub/sub (database + client events) via WebSockets"db-sdk-typescript"- Database operations with TypeScript SDK- Authentication - Choose based on implementation:
"auth-sdk-typescript"- TypeScript SDK methods for custom auth flows"auth-components-react"- Pre-built auth UI for React+Vite (single-page app)"auth-components-react-router"- Pre-built auth UI for React(Vite+React Router) (multi-page app)"auth-components-nextjs"- Pre-built auth UI for Next.js (SSR app)
"storage-sdk"- File storage operations"functions-sdk"- Serverless functions invocation"ai-integration-sdk"- AI integration with the provisioned OpenRouter key and OpenAI SDK"deployment"- Deploy frontend applications via MCP tool"payments"- Stripe Checkout, Billing Portal, webhook projections, and fulfillment patterns
These docs are mostly for the TypeScript SDK. For other languages, you can also use the fetch-sdk-docs MCP tool to get specific documentation.
Use the InsForge fetch-sdk-docs MCP tool to get specific SDK documentation
You can fetch SDK documentation using the fetch-sdk-docs MCP tool with a specific feature type and language.
Available feature types:
db- Database operationsstorage- File storage operationsfunctions- Serverless functions invocationauth- User authenticationai- AI integration with the provisioned OpenRouter key and OpenAI SDKrealtime- Real-time pub/sub (database + client events) via WebSocketspayments- Stripe Checkout and Billing Portal with webhook-based fulfillment
Available languages:
typescript- JavaScript/TypeScript SDKswift- Swift SDK (for iOS, macOS, tvOS, and watchOS)kotlin- Kotlin SDK (for Android and JVM applications)rest-api- REST API
Payments currently has TypeScript SDK docs only. Use the Payments API reference for non-TypeScript clients.
When to Use SDK vs MCP Tools
Always SDK for Application Logic:
- Authentication (register, login, logout, profiles)
- Database CRUD (select, insert, update, delete)
- Storage operations (upload, download files)
- AI integration via the provisioned OpenRouter key with the OpenAI SDK or OpenRouter HTTP API
- Serverless function invocation
- Payments checkout and customer portal session creation
Use MCP Tools for Infrastructure:
- Project scaffolding (
download-template) - Download starter templates with InsForge integration - Backend setup and metadata (
get-backend-metadata) - Database schema management (
run-raw-sql,get-table-schema) - Storage bucket creation (
create-bucket,list-buckets,delete-bucket) - Serverless function deployment (
create-function,update-function,delete-function) - Frontend deployment (
create-deployment) - Deploy frontend apps to InsForge hosting
Important Notes
- For auth: use
auth-sdkfor custom UI, or framework-specific components for pre-built UI - SDK returns
{data, error}structure for all operations - Database inserts require array format:
[{...}] - Serverless functions have one endpoint and do not support nested route paths
- Storage: Upload files to buckets, store URLs in database
- AI integrations should call OpenRouter directly with
baseURL: "https://openrouter.ai/api/v1"and a server-sideOPENROUTER_API_KEY - EXTRA IMPORTANT: Use Tailwind CSS 3.4 (do not upgrade to v4). Lock these dependencies in
package.json
InsForge backend
This project uses InsForge: an all-in-one, open-source Postgres-based backend (BaaS) that gives this app a database, authentication, file storage, edge functions, realtime, an AI model gateway, and payments through one platform.
- Project: tockengecko (API base
https://4p7bs82r.us-east.insforge.app) - Skills: these InsForge skills are installed for supported coding agents. Reach for them before implementing any InsForge feature instead of guessing the API:
insforge: app code with the@insforge/sdkclient (database CRUD, auth, storage, edge functions, realtime, AI, email, and Stripe payments).insforge-cli: backend and infrastructure via theinsforgeCLI (projects, SQL, migrations, RLS policies, storage buckets, functions, secrets, payment setup, schedules, deploys).insforge-debug: diagnosing failures (SDK/HTTP errors, RLS denials, auth and OAuth issues) and running security or performance audits.insforge-integrations: wiring external auth providers (Clerk, Auth0, WorkOS, Better Auth, etc.) for JWT-based RLS, or the OKX x402 payment facilitator.find-skills: discovering additional skills on demand.
- Credentials: app code reads keys from
.env.local; the CLI reads.insforge/project.json. Never hardcode or commit keys.
Key patterns:
- Database inserts take an array:
insert([{ ... }]). - Reference users with
auth.users(id); useauth.uid()in RLS policies. - For storage uploads, persist both the returned
urlandkey.
