# Two Doors In — MCP Server vs. CLI + Skills

> AI coding agents talk to InsForge through exactly two interfaces: a self-hosted or cloud MCP server (tool calls) and a CLI with bundled Skills (terminal commands). This page explains what each door does, when to use which, and what actually happens when an agent connects.

- Repository: InsForge/InsForge
- GitHub: https://github.com/InsForge/InsForge
- Human wiki: https://grok-wiki.com/public/wiki/insforge-insforge-357039661319
- Complete Markdown: https://grok-wiki.com/public/wiki/insforge-insforge-357039661319/llms-full.txt

## Source Files

- `docs/mcp-setup.mdx`
- `docs/quickstart.mdx`
- `docs/vscode-extension.mdx`
- `.claude/skills/README.md`
- `docs/insforge-instructions-sdk.md`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:

- [docs/mcp-setup.mdx](docs/mcp-setup.mdx)
- [docs/quickstart.mdx](docs/quickstart.mdx)
- [docs/vscode-extension.mdx](docs/vscode-extension.mdx)
- [docs/introduction.mdx](docs/introduction.mdx)
- [docs/insforge-instructions-sdk.md](docs/insforge-instructions-sdk.md)
- [.claude/skills/README.md](.claude/skills/README.md)
- [.claude/skills/insforge-dev/SKILL.md](.claude/skills/insforge-dev/SKILL.md)
- [packages/dashboard/src/features/dashboard/components/connect/mcp/helpers.tsx](packages/dashboard/src/features/dashboard/components/connect/mcp/helpers.tsx)
- [packages/dashboard/src/features/dashboard/components/connect/constants.ts](packages/dashboard/src/features/dashboard/components/connect/constants.ts)
- [backend/src/api/routes/usage/index.routes.ts](backend/src/api/routes/usage/index.routes.ts)
- [backend/src/api/routes/docs/index.routes.ts](backend/src/api/routes/docs/index.routes.ts)
- [backend/src/server.ts](backend/src/server.ts)
</details>

# Two Doors In — MCP Server vs. CLI + Skills

InsForge is an AI-optimized Backend-as-a-Service (BaaS) platform. Its core design philosophy is that AI coding agents — not humans — are the primary builders. To make that work, every interaction point is designed to be machine-readable and agent-friendly. There are exactly two entry points an AI agent uses to work with InsForge: the **MCP server** (tool calls that flow through the Model Context Protocol) and the **CLI plus bundled Skills** (terminal commands that the agent runs directly in your project).

Understanding which door to use, and what happens behind each one, is the key to getting InsForge to "just work" for your agent. This page explains both paths clearly — what they are, when to pick each one, and what actually runs when the agent connects.

---

## The Two Doors at a Glance

```text
┌────────────────────────────────────────────────────────────┐
│                      AI Coding Agent                       │
│  (Cursor, Claude Code, Copilot, Windsurf, Codex, ...)      │
└────────────────┬──────────────────────────┬───────────────┘
                 │                          │
         MCP Tool Calls              CLI Terminal Commands
                 │                          │
  ┌──────────────▼────────────┐  ┌──────────▼──────────────┐
  │  @insforge/mcp  (stdio)   │  │  @insforge/cli  (npx)   │
  │  or mcp.insforge.dev/mcp  │  │  + .claude/skills/      │
  │  (Streamable HTTP)        │  │    SKILL.md files        │
  └──────────────┬────────────┘  └──────────┬──────────────┘
                 │                          │
                 └────────────┬─────────────┘
                              │
               ┌──────────────▼──────────────┐
               │  InsForge Backend API        │
               │  backend/src/server.ts       │
               │  /api/* routes               │
               └──────────────────────────────┘
```

Both doors reach the same backend. The difference is *how* the agent discovers capabilities and *what credentials* flow where.

Sources: [packages/dashboard/src/features/dashboard/components/connect/mcp/helpers.tsx:30-153](), [backend/src/server.ts:204-224]()

---

## Door 1 — The MCP Server

### What it is

The Model Context Protocol (MCP) is an open standard that lets AI coding assistants call named tools with structured arguments, exactly like function calls. InsForge ships an MCP server that exposes every backend capability as a callable tool: fetching documentation, scaffolding a project template, running SQL, creating storage buckets, deploying functions, and more.

There are two flavors of this same server:

| Flavor | Endpoint / Transport | Best for |
|---|---|---|
| **Local (stdio)** | `npx -y @insforge/mcp@latest` | Self-hosted InsForge; works without a public internet URL |
| **Remote (Streamable HTTP)** | `https://mcp.insforge.dev/mcp` | Cloud projects; zero install; shared across machines |

The local server is configured by injecting `API_KEY` and `API_BASE_URL` environment variables into the `npx` process. The remote server uses OAuth (browser-based) so no credentials appear in config files.

Sources: [packages/dashboard/src/features/dashboard/components/connect/mcp/helpers.tsx:120-143](), [docs/mcp-setup.mdx:462-478]()

### How to install it

#### Option A — Remote MCP (fastest)

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

Supported clients for this one-liner: Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Goose, GitHub Copilot, OpenCode, VS Code, Zed.

After running, open the agent's MCP panel and click **Authenticate** to complete the OAuth flow. Some clients (Antigravity, Cursor) do this automatically.

Sources: [docs/mcp-setup.mdx:464-475]()

#### Option B — Local MCP (self-hosted or manual)

The InsForge dashboard generates a project-specific install command. Copy it from **Settings → Connect → [Select your agent]** and run it in your terminal. For example, the generated command looks like:

```bash
npx @insforge/install --client claude-code \
  --env API_KEY=<your-key> \
  --env API_BASE_URL=https://your-app.region.insforge.app
```

This writes a config file at the appropriate location for your agent. Example for Claude Code:

```json
// .mcp.json (project-local)
{
  "mcpServers": {
    "insforge": {
      "command": "npx",
      "args": ["-y", "@insforge/mcp@latest"],
      "env": {
        "API_KEY": "<your-key>",
        "API_BASE_URL": "https://your-app.region.insforge.app"
      }
    }
  }
}
```

On Windows, the command becomes `cmd /c npx -y @insforge/mcp@latest` to handle shell differences.

Sources: [packages/dashboard/src/features/dashboard/components/connect/mcp/helpers.tsx:121-153](), [docs/mcp-setup.mdx:85-126]()

#### Option C — VS Code Extension (one-click)

The InsForge VS Code extension handles auth (OAuth + PKCE) and runs `npx @insforge/install` automatically once you pick a project and target agent. No terminal required.

Sources: [docs/vscode-extension.mdx:1-68]()

### What the agent can do once connected

The first thing agents are instructed to call is `fetch-docs`. This tool reads documentation directly from the backend's `/api/docs/` route, which serves the `.mdx` files under `docs/` with snippets resolved:

```
GET /api/docs/:docType
GET /api/docs/:feature/:language
```

The canonical verification prompt is:

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

A green **MCP Connected** indicator appears in the InsForge dashboard when the MCP server calls `POST /api/usage/mcp` (authenticated via API key) and the backend broadcasts the event to admin clients over Socket.IO.

Sources: [packages/dashboard/src/features/dashboard/components/connect/constants.ts:1-2](), [backend/src/api/routes/usage/index.routes.ts:18-47](), [backend/src/api/routes/docs/index.routes.ts]()

### MCP tool categories

The MCP tools divide cleanly into **infrastructure** operations (things that configure or set up the backend) versus **documentation** fetching. The agent calls infrastructure tools for tasks the SDK cannot handle from application code:

| Category | Example tools | When agents use them |
|---|---|---|
| Project setup | `download-template`, `get-backend-metadata` | Scaffolding a new project |
| Database schema | `run-raw-sql`, `get-table-schema` | Creating or inspecting tables |
| Storage management | `create-bucket`, `list-buckets`, `delete-bucket` | Bucket lifecycle |
| Function deployment | `create-function`, `update-function`, `delete-function` | Serverless deploys |
| Frontend hosting | `create-deployment` | Deploying a Vite/Next.js app |
| Documentation | `fetch-docs`, `fetch-sdk-docs` | Reading SDK and API docs |

Sources: [docs/insforge-instructions-sdk.md:107-127]()

### Supported agents (MCP path)

The `MCP_AGENTS` list in the dashboard defines which agents have first-class MCP support:

Cursor · Claude Code · Trae · Cline · Windsurf · Roo Code · Qoder · GitHub Copilot · Google Antigravity · Codex · Kiro · OpenCode · OpenClaw · (manual MCP JSON)

Sources: [packages/dashboard/src/features/dashboard/components/connect/mcp/helpers.tsx:34-118]()

---

## Door 2 — The CLI + Skills

### What it is

The CLI is an npm package (`@insforge/cli`) that runs as a regular terminal command. Instead of registering tool schemas in the agent's MCP panel, it works as a subprocess the agent invokes through shell commands. Skills are Markdown files (`.claude/skills/<name>/SKILL.md`) placed inside your project that teach the agent *how* to use the CLI and *what conventions to follow*.

Think of Skills as a cheat-sheet for the agent: they describe which commands do what, what patterns to follow, and how to stay within InsForge conventions — all in plain text the agent reads from the filesystem.

### How to install it

```bash
npx @insforge/cli link --project-id <your-project-id>
```

Run this once inside your project directory. It links the local folder to your InsForge project. Skills are automatically discovered by Claude Code (and compatible agents) from `.claude/skills/` — no additional config needed.

Sources: [docs/quickstart.mdx:34-48]()

### How Skills are structured

Each skill lives in a subdirectory. The entry point is `SKILL.md` with YAML frontmatter:

```
.claude/skills/
├── README.md
├── insforge-dev/
│   ├── SKILL.md        # Top-level: route to the right sub-skill
│   ├── backend/SKILL.md
│   ├── dashboard/SKILL.md
│   ├── docs/SKILL.md
│   ├── shared-schemas/SKILL.md
│   └── ui/SKILL.md
└── doc-author/
    ├── SKILL.md        # Vendored from Mintlify upstream
    └── INSFORGE.md     # InsForge-specific overrides
```

The top-level `insforge-dev` skill directs the agent to "use the narrowest package skill that matches the task." This keeps the agent's working context small and focused.

The verification prompt for the CLI path is:

```
I'm using InsForge as my backend platform. Read the current directory,
make sure InsForge skills are installed, and use InsForge CLI for backend tasks.
```

Sources: [.claude/skills/README.md:1-31](), [packages/dashboard/src/features/dashboard/components/connect/constants.ts:4-5]()

### When Skills are updated

The `doc-author/SKILL.md` skill is vendored from Mintlify's upstream repository. To refresh it without hand-editing:

```bash
scripts/update-mintlify-skill.sh
```

The script re-downloads the upstream file, updates the commit SHA attribution, and fails loudly if Mintlify's license has changed from MIT. InsForge-specific overrides live in `doc-author/INSFORGE.md` and are never clobbered by the refresh script.

Sources: [.claude/skills/README.md:20-31]()

---

## Choosing the Right Door

The two interfaces are complementary, not competing. The key distinction is **where the agent is running** and **what kind of task it is doing**:

| Situation | Use | Reason |
|---|---|---|
| Agent inside an IDE (Cursor, Windsurf, etc.) | MCP server | Tool calls are first-class in IDE agents; no shell needed |
| Agent in a terminal (Claude Code CLI) | CLI + Skills | Shell access is direct; Skills provide task-specific instructions |
| Infrastructure operations (schema, buckets, deploys) | MCP tools | These require admin credentials the SDK never holds |
| Application code (auth, CRUD, storage access) | SDK (`@insforge/sdk`) | Runtime code runs in the user's browser/server, not the agent |
| Self-hosted InsForge, no public URL | Local MCP (stdio) or CLI | Remote MCP requires `mcp.insforge.dev` to be reachable |
| Cloud project, quick start | Remote MCP | One command, OAuth, no API key in config |

The `insforge-instructions-sdk.md` file is explicit: use the SDK for all application logic (auth, database CRUD, storage, AI calls) and use MCP tools for infrastructure setup. The CLI + Skills path overlaps with MCP for infrastructure tasks but is especially useful when the agent is running in a terminal environment where typing shell commands is natural.

Sources: [docs/insforge-instructions-sdk.md:100-127]()

---

## What Happens When an Agent Connects

Here is the actual sequence when an agent first connects via MCP:

```mermaid
sequenceDiagram
    participant Agent as AI Agent (e.g. Cursor)
    participant MCP as @insforge/mcp (local)<br/>or mcp.insforge.dev (remote)
    participant Backend as InsForge Backend<br/>backend/src/server.ts
    participant Dashboard as InsForge Dashboard<br/>(WebSocket)

    Agent->>MCP: Reads tool schema list on startup
    Agent->>MCP: Calls fetch-docs("instructions")
    MCP->>Backend: GET /api/docs/instructions
    Backend-->>MCP: Returns docs/insforge-instructions-sdk.md content
    MCP-->>Agent: Documentation text
    Agent->>MCP: Calls get-backend-metadata()
    MCP->>Backend: GET /api/metadata (verifyAdmin)
    Backend-->>MCP: { auth, database, storage, functions, version }
    MCP->>Backend: POST /api/usage/mcp { tool_name: "fetch-docs" }
    Backend->>Dashboard: Socket.IO broadcast MCP_CONNECTED event
    Dashboard-->>User: Shows green "MCP Connected" indicator
```

The `/api/usage/mcp` endpoint requires an API key (`verifyApiKey` middleware). It records the tool call and broadcasts a `MCP_CONNECTED` event via `SocketManager.broadcastToRoom('role:project_admin', ...)` so the dashboard updates in real time.

Sources: [backend/src/api/routes/usage/index.routes.ts:18-47](), [backend/src/api/routes/docs/index.routes.ts](), [backend/src/server.ts:204-224]()

---

## Config File Locations by Agent

The agent's MCP config is written to a well-known location that the agent scans at startup. For the local MCP path:

| Agent | Config file |
|---|---|
| Claude Code | `.mcp.json` (project workspace root) |
| Cursor | `~/.cursor/mcp.json` |
| GitHub Copilot | `.vscode/mcp.json` (project workspace) |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Cline | Cline VS Code extension config |
| Codex | `~/.codex/config.toml` |
| Trae | Trae IDE config |
| Qoder / Roo Code | IDE-specific extension config |

For the remote MCP path, the URL `https://mcp.insforge.dev/mcp` replaces the `npx` command + env block.

Sources: [docs/vscode-extension.mdx:54-68](), [docs/mcp-setup.mdx:485-651]()

---

## Summary

InsForge gives AI agents two distinct integration paths. The MCP server (local stdio or remote HTTP) is the richer path: it exposes typed tools for both infrastructure management and documentation fetching, works natively inside IDE agents, and signals connection status to the dashboard in real time. The CLI + Skills path is the lighter-weight path for terminal-based agents: a single `npx link` command + Markdown skill files that teach the agent InsForge conventions without any MCP scaffolding. For most project-level application code, neither path is used directly — the `@insforge/sdk` handles that at runtime. Both paths reach the same Express backend (`backend/src/server.ts`), which routes requests through a layered route → service → provider architecture.

Sources: [docs/introduction.mdx:23-25](), [backend/src/server.ts:65-224]()