MCP Setup

Connect InsForge MCP server to your AI coding assistant

Overview

The InsForge MCP (Model Context Protocol) server gives your AI coding assistant direct access to your backend infrastructure. Once connected, your AI can:

• Fetch documentation - Get real-time docs for database, auth, storage, functions, and AI APIs
• Manage database schemas - Create tables, add columns, configure Row Level Security
• Query and inspect data - Get table schemas, view data, run custom SQL
• Manage storage - Create buckets, configure access policies
• Deploy functions - Create and update serverless edge functions
• Download templates - Scaffold new projects with InsForge pre-configured

Already using the VS Code extension? The InsForge VS Code extension provides one-click MCP installation.

Prerequisites

1. An AI coding assistant

   InsForge MCP works with:

   • Cursor - AI-first code editor
   • Claude Code - Claude’s coding interface
   • GitHub Copilot - In VS Code
   • Windsurf, Cline, Roo Code, OpenCode - Alternative AI editors
   • Google Antigravity, Codex, Kiro, Qoder - Emerging tools
2. An InsForge project

   You need either:

   • A cloud project at insforge.dev (easiest)
   • A self-hosted instance running on Docker (see Deployment Guide)

Quick Setup (Recommended)

The fastest way to connect InsForge MCP:

Option 1: One-Click Installation (Cloud)

If you’re using cloud-hosted InsForge:

1. Open your InsForge dashboard at insforge.dev
2. Click Connect in the top navigation
3. Select your AI assistant from the dropdown
4. Click the Add to [Assistant] button or copy the installation command
5. Follow the on-screen instructions

Option 2: Remote MCP (Universal)

Works with most AI assistants. One command handles everything:

npx add-mcp https://mcp.insforge.dev/mcp

Supported clients: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Goose, GitHub Copilot, OpenCode, VS Code, Zed

This command:

• Automatically generates configuration for your AI client
• Prompts for authentication (opens browser)
• Binds to your InsForge project

After installation, you may need to authenticate or bind a project manually (see client-specific instructions below).

Manual Configuration

Prefer to configure MCP manually? Choose your AI assistant:

Cursor

Installation

Method 1: One-Click (Cloud only)

From your InsForge dashboard, click Add to Cursor to auto-generate the configuration.

Method 2: Manual Configuration

1. Open Cursor Settings
2. Navigate to Tools & MCP
3. Click New MCP Server
4. Paste the MCP JSON from your InsForge project settings
5. Save the configuration
6. Look for a green status indicator

MCP JSON Format

For local/self-hosted InsForge:

{
  "mcpServers": {
    "insforge": {
      "command": "npx",
      "args": [
        "-y",
        "@insforge/mcp",
        "--api-key",
        "your-api-key-here",
        "--base-url",
        "http://localhost:7130"
      ]
    }
  }
}

For cloud-hosted InsForge (remote MCP):

{
  "mcpServers": {
    "insforge": {
      "url": "https://mcp.insforge.dev/mcp"
    }
  }
}

Verify Installation

Start a new chat in Cursor and send:

I'm using InsForge as my backend platform, call InsForge MCP's fetch-docs tool to
learn about InsForge instructions.

You should see your AI assistant call the fetch-docs tool and return InsForge documentation.

Claude Code

Installation

Method 1: Command-Line Installation

From your InsForge dashboard, select Claude Code and copy the installation command:

npx add-mcp https://mcp.insforge.dev/mcp

Run this in your terminal. It creates .mcp.json in your home directory.

Method 2: Manual Configuration

Create or edit ~/.mcp.json:

{
  "mcpServers": {
    "insforge": {
      "type": "http",
      "url": "https://mcp.insforge.dev/mcp"
    }
  }
}

For self-hosted InsForge:

{
  "mcpServers": {
    "insforge": {
      "command": "npx",
      "args": [
        "-y",
        "@insforge/mcp",
        "--api-key",
        "ik_your-api-key-here",
        "--base-url",
        "http://localhost:7130"
      ]
    }
  }
}

Authentication

In your terminal (not the IDE), run:

claude /mcp

Select insforge, then Authenticate to open the OAuth flow in your browser.

Verify Installation

Start a new chat in Claude Code and send:

I'm using InsForge as my backend platform, call InsForge MCP's fetch-docs tool to
learn about InsForge instructions.

GitHub Copilot

Installation

From your InsForge dashboard, select Copilot and copy the installation command.

Run in your terminal:

npx add-mcp https://mcp.insforge.dev/mcp

This creates .vscode/mcp.json in your workspace:

{
  "servers": {
    "insforge": {
      "type": "http",
      "url": "https://mcp.insforge.dev/mcp"
    }
  }
}

Self-Hosted Configuration

For local InsForge, use:

{
  "servers": {
    "insforge": {
      "command": "npx",
      "args": [
        "-y",
        "@insforge/mcp",
        "--api-key",
        "ik_your-api-key",
        "--base-url",
        "http://localhost:7130"
      ]
    }
  }
}

Verify Installation

In VS Code chat, send:

I'm using InsForge as my backend platform, call InsForge MCP's fetch-docs tool to
learn about InsForge instructions.

Windsurf

Installation

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "insforge": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.insforge.dev/mcp"
      ]
    }
  }
}

Windsurf doesn’t support HTTP transport natively. The mcp-remote package acts as a proxy.

Verify Installation

Start a chat and send:

I'm using InsForge as my backend platform, call InsForge MCP's fetch-docs tool to
learn about InsForge instructions.

Cline

Installation (Smithery)

Install via Smithery CLI:

npx -y @smithery/cli mcp add devel/insforge --client cline

Manual Installation

Follow the Cline documentation:

1. Open Cline Settings → MCP Servers
2. Click Add Remote Server
3. Enter:
   • Server Name: insforge
   • Server URL: https://mcp.insforge.dev/mcp
   • Transport: Streamable HTTP
4. Click Authenticate when prompted

Verify Installation

I'm using InsForge as my backend platform, call InsForge MCP's fetch-docs tool to
learn about InsForge instructions.

OpenCode

Installation

Run the setup command:

npx add-mcp https://mcp.insforge.dev/mcp

This creates opencode.json:

{
  "mcp": {
    "insforge": {
      "type": "remote",
      "url": "https://mcp.insforge.dev/mcp",
      "enabled": true
    }
  }
}

Authentication

opencode mcp auth insforge

This opens your browser for OAuth authentication.

Verify Installation

I'm using InsForge as my backend platform, call InsForge MCP's fetch-docs tool to
learn about InsForge instructions.

Codex

Installation

Enable Remote MCP (first time only):

Edit ~/.codex/config.toml:

[beta]
rmcp = true

Add InsForge MCP:

codex mcp add insforge --url https://mcp.insforge.dev/mcp

Or run:

npx add-mcp https://mcp.insforge.dev/mcp

This creates:

[mcp_servers.insforge]
type = "http"
url = "https://mcp.insforge.dev/mcp"

Authentication

codex mcp login insforge

Verify Installation

Inside Codex, run /mcp to see connected servers.

Other Clients (Generic MCP JSON)

Universal MCP JSON

If your AI client supports MCP but isn’t listed above, use this generic configuration:

For cloud-hosted InsForge (remote MCP):

{
  "mcpServers": {
    "insforge": {
      "url": "https://mcp.insforge.dev/mcp"
    }
  }
}

For self-hosted InsForge (local MCP):

{
  "mcpServers": {
    "insforge": {
      "command": "npx",
      "args": [
        "-y",
        "@insforge/mcp",
        "--api-key",
        "ik_your-api-key-here",
        "--base-url",
        "http://localhost:7130"
      ]
    }
  }
}

Getting Your API Key (Self-Hosted)

1. Open your InsForge dashboard at http://localhost:7130
2. Navigate to Settings → API Keys
3. Your API key starts with ik_
4. If not set, it’s auto-generated from your .env file under ACCESS_API_KEY

Verify Installation

I'm using InsForge as my backend platform, call InsForge MCP's fetch-docs tool to
learn about InsForge instructions.

Available MCP Tools

Once connected, your AI assistant can use these tools:

Documentation & Metadata

• fetch-docs - Get SDK documentation for database, auth, storage, functions, AI
• get-backend-metadata - Retrieve your backend URL, anon key, API version

Database Management

• run-raw-sql - Execute custom SQL queries
• get-table-schema - Inspect table structure and columns
• list-tables - Show all tables in your database

Storage Management

• create-bucket - Create new storage buckets
• list-buckets - Show all storage buckets
• delete-bucket - Remove storage buckets

Function Management

• create-function - Deploy new serverless functions
• update-function - Update existing functions
• delete-function - Remove deployed functions
• list-functions - Show all deployed functions

Project Scaffolding

• download-template - Download starter templates with InsForge pre-configured

See the MCP Tools Reference for detailed usage examples

Troubleshooting

Connection not working

Check MCP server status:

In your AI assistant’s settings, verify the InsForge MCP server shows a green/connected status.

For cloud-hosted: Ensure you completed the OAuth authentication flow.

For self-hosted: Verify your API key is correct and starts with ik_.

Restart your AI assistant: Most clients require a full restart after MCP configuration changes.

API key not found (self-hosted)

Check your .env file for ACCESS_API_KEY:

ACCESS_API_KEY=ik_your-api-key-here-32-chars-minimum

If not set, InsForge auto-generates one on startup. Check the logs:

docker compose logs insforge | grep "API Key"

Or open the dashboard at http://localhost:7130 → Settings → API Keys.

Changes not taking effect

Most AI clients cache MCP configurations. To refresh:

1. Close the AI assistant completely
2. Restart the application
3. Start a new chat session

For Cursor: Also try Cursor Settings → Tools & MCP → Click the refresh icon.

Permission denied errors

Cloud-hosted: Re-authenticate using the OAuth flow. Your session may have expired.

Self-hosted: Verify your API key has not been rotated. Check the dashboard for the current key.

Next Steps

Build Your First App

Create a todo app or Instagram clone in minutes

MCP Tools Reference

Complete list of MCP tools with examples

Core Features

Learn about database, auth, storage, and functions

Join Discord

Get help from the community