bkend-quickstart

name	bkend-quickstart
classification	C
description	bkend.ai platform onboarding and core concepts guide. Covers MCP setup, resource hierarchy (Org->Project->Environment), Tenant vs User model, and first project creation. Use proactively when user is new to bkend or asks about initial setup. Triggers: bkend setup, first project, bkend start, MCP connect, bkend 시작, 처음, 설정, MCP 연결, 프로젝트 생성, bkend始め方, 初期設定, MCP接続, bkend入门, 初始设置, MCP连接, configuracion bkend, primer proyecto, configuration bkend, premier projet, bkend Einrichtung, erstes Projekt, configurazione bkend, primo progetto Do NOT use for: advanced auth flows (use bkend-auth), database queries (use bkend-data), file storage (use bkend-storage), security policies (use bkend-security)
user-invocable	true
argument-hint
allowed-tools	["read_file","write_file","replace","glob","grep_search","run_shell_command","web_fetch"]
imports	[]
agents	{"backend":"bkend-expert"}
context	session
memory	project
pdca-phase	all

bkend-quickstart

bkend.ai platform onboarding and core concepts guide

1. What is bkend.ai

bkend.ai is a Backend-as-a-Service (BaaS) platform built on MongoDB Atlas. It provides:

• REST API endpoints for CRUD operations, authentication, file storage, and more
• MCP (Model Context Protocol) server for AI-assisted development with Gemini CLI, Claude Code, and Cursor
• Console UI at https://console.bkend.ai for visual management
• Zero-config database powered by MongoDB Atlas (no schema migration needed)
• Multi-tenant architecture with project-level isolation

Key Differentiators

Feature	bkend.ai	Traditional BaaS
AI Integration	Native MCP support	None
Database	MongoDB Atlas (managed)	Self-managed
Schema	Schemaless / flexible	Rigid migrations
Auth	Built-in JWT + Social	Plugin-based
File Storage	Integrated	Separate service

2. Core Concepts

2.1 Resource Hierarchy

Organization (Org)
└── Project
    └── Environment (dev / staging / prod)
        ├── Tables (collections)
        ├── Auth (users, sessions)
        ├── Storage (files, buckets)
        └── API Keys

• Organization: Top-level billing and team boundary. One user can belong to multiple orgs.
• Project: A single application or service. Contains its own database, auth, and storage.
• Environment: Isolated runtime context within a project. Each environment has its own data, API keys, and configuration. Default environments: dev, staging, prod.

2.2 Tenant vs User Model

bkend.ai distinguishes between two identity layers:

Concept	Tenant	User
Who	Developer / team member	End-user of your app
Scope	Console + API management	App-level auth
Auth	Console login	/auth/* endpoints
Permissions	Org/Project roles	RBAC (admin/user/self/guest)
API Key	Yes (X-API-Key)	No (uses JWT)

• Tenant: You, the developer. Manages projects via the Console or API keys.
• User: Your application's end-user. Authenticates via email, social login, or magic link.

2.3 API Structure

Base URL:

https://api-client.bkend.ai

MCP URL:

https://api.bkend.ai/mcp

Required Headers for all API calls:

X-Project-Id: <your-project-id>
X-Environment: <dev|staging|prod>

Authentication Headers (choose one):

# For tenant/server-side calls
X-API-Key: <your-api-key>

# For user-authenticated calls
Authorization: Bearer <access-token>

Standard Response Format:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Standard Error Format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [...]
  }
}

3. Quick Start Steps

Step 1: Sign Up

Visit https://console.bkend.ai/signup and create your tenant account.

Step 2: Create an Organization

POST https://api-client.bkend.ai/orgs
Content-Type: application/json

{
  "name": "My Company",
  "slug": "my-company"
}

Or use the Console: Dashboard > Create Organization.

Step 3: Create a Project

POST https://api-client.bkend.ai/projects
Content-Type: application/json
X-Org-Id: <your-org-id>

{
  "name": "My App",
  "slug": "my-app"
}

Or use the Console: Organization > New Project.

Step 4: Set Environment

Each project starts with three environments: dev, staging, prod. Choose your target:

X-Project-Id: proj_abc123
X-Environment: dev

Step 5: Create a Table

POST https://api-client.bkend.ai/tables
Content-Type: application/json
X-Project-Id: proj_abc123
X-Environment: dev
X-API-Key: <your-api-key>

{
  "name": "todos",
  "schema": {
    "title": { "type": "string", "required": true },
    "completed": { "type": "boolean", "default": false },
    "priority": { "type": "number", "default": 0 }
  }
}

Step 6: Get an API Key

Navigate to Console > Project > Settings > API Keys and generate a new key. Or via API:

POST https://api-client.bkend.ai/api-keys
X-Project-Id: proj_abc123
X-Environment: dev

Step 7: Call the API

# Create a record
curl -X POST https://api-client.bkend.ai/data/todos \
  -H "Content-Type: application/json" \
  -H "X-Project-Id: proj_abc123" \
  -H "X-Environment: dev" \
  -H "X-API-Key: your-api-key" \
  -d '{"title": "Learn bkend", "completed": false}'

# List records
curl https://api-client.bkend.ai/data/todos \
  -H "X-Project-Id: proj_abc123" \
  -H "X-Environment: dev" \
  -H "X-API-Key: your-api-key"

4. MCP Setup

4.1 Gemini CLI

Create or edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "bkend": {
      "httpUrl": "https://api.bkend.ai/mcp",
      "headers": {
        "X-Project-Id": "proj_abc123",
        "X-Environment": "dev",
        "X-API-Key": "your-api-key"
      }
    }
  }
}

After setup, restart Gemini CLI. You can then use natural language:

> Create a users table with name, email, and age fields
> Add a new user named Alice with email [e-mail]
> List all users where age > 25

4.2 Claude Code

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "bkend": {
      "type": "http",
      "url": "https://api.bkend.ai/mcp",
      "headers": {
        "X-Project-Id": "proj_abc123",
        "X-Environment": "dev",
        "X-API-Key": "your-api-key"
      }
    }
  }
}

4.3 Cursor

Open Cursor Settings > MCP Servers and add:

{
  "bkend": {
    "type": "http",
    "url": "https://api.bkend.ai/mcp",
    "headers": {
      "X-Project-Id": "proj_abc123",
      "X-Environment": "dev",
      "X-API-Key": "your-api-key"
    }
  }
}

5. Framework Quick Start

5.1 Next.js Setup

Environment Variables (.env.local):

NEXT_PUBLIC_BKEND_API_URL=https://api-client.bkend.ai
NEXT_PUBLIC_BKEND_PROJECT_ID=proj_abc123
NEXT_PUBLIC_BKEND_ENVIRONMENT=dev
BKEND_API_KEY=your-api-key

bkendFetch Client (lib/bkend.ts):

interface BkendFetchOptions extends RequestInit {
  token?: string;
}

export async function bkendFetch<T = any>(
  path: string,
  options: BkendFetchOptions = {}
): Promise<T> {
  const { token, headers: customHeaders, ...rest } = options;

  const headers: Record<string, string> = {
    "Content-Type": "application/json",
    "X-Project-Id": process.env.NEXT_PUBLIC_BKEND_PROJECT_ID!,
    "X-Environment": process.env.NEXT_PUBLIC_BKEND_ENVIRONMENT!,
    ...customHeaders as Record<string, string>,
  };

  // Server-side: use API key
  if (typeof window === "undefined" && process.env.BKEND_API_KEY) {
    headers["X-API-Key"] = process.env.BKEND_API_KEY;
  }

  // Client-side: use JWT token
  if (token) {
    headers["Authorization"] = `Bearer ${token}`;
  }

  const res = await fetch(
    `${process.env.NEXT_PUBLIC_BKEND_API_URL}${path}`,
    { headers, ...rest }
  );

  if (!res.ok) {
    const error = await res.json();
    throw new Error(error.error?.message || "bkend API error");
  }

  return res.json();
}

Middleware (middleware.ts):

import { NextRequest, NextResponse } from "next/server";

export async function middleware(request: NextRequest) {
  const accessToken = request.cookies.get("bkend_access_token")?.value;
  const refreshToken = request.cookies.get("bkend_refresh_token")?.value;

  // Public routes - skip auth
  const publicPaths = ["/login", "/signup", "/"];
  if (publicPaths.includes(request.nextUrl.pathname)) {
    return NextResponse.next();
  }

  if (!accessToken && !refreshToken) {
    return NextResponse.redirect(new URL("/login", request.url));
  }

  // Auto-refresh if access token is missing but refresh token exists
  if (!accessToken && refreshToken) {
    try {
      const res = await fetch(
        `${process.env.NEXT_PUBLIC_BKEND_API_URL}/auth/token/refresh`,
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            "X-Project-Id": process.env.NEXT_PUBLIC_BKEND_PROJECT_ID!,
            "X-Environment": process.env.NEXT_PUBLIC_BKEND_ENVIRONMENT!,
          },
          body: JSON.stringify({ refreshToken }),
        }
      );

      if (res.ok) {
        const data = await res.json();
        const response = NextResponse.next();
        response.cookies.set("bkend_access_token", data.data.accessToken, {
          httpOnly: true,
          secure: true,
          sameSite: "lax",
          maxAge: 3600,
        });
        return response;
      }
    } catch {
      return NextResponse.redirect(new URL("/login", request.url));
    }
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

5.2 Flutter Setup

DioClient (lib/core/network/bkend_client.dart):