bkend-mcp: MCP Tools & AI Integration Expert Skill

1. MCP Overview

The Model Context Protocol (MCP) is an open standard that enables AI models to interact with external tools and data sources through a unified interface. bkend.ai implements MCP to provide AI-powered development workflows.

Protocol Specification

How It Works

1. The AI client (Gemini CLI, Claude Code, Cursor, etc.) connects to the MCP server
2. The server advertises available tools and resources
3. The AI model invokes tools on behalf of the user
4. The server executes operations and returns structured results
5. OAuth 2.1 + PKCE ensures secure, user-authorized access

2. MCP Tool Catalog (28 Tools)

bkend.ai exposes 28 MCP tools organized into 6 categories. Each tool follows the MCP tool schema with name, description, and inputSchema properties.

2.1 Fixed Tools (3)

These tools are always available regardless of project context.

Usage Notes:

• Always call get_context first to verify your session is properly authenticated
• Use search_docs to find REST API documentation for Auth and Storage features (no MCP tools available for these)
• Use get_operation_schema to get detailed request/response schemas for code generation

2.2 Project Management Tools (6)

Tools for managing organizations, projects, and environments.

Usage Notes:

• Start with backend_org_list to get the orgId
• Then use backend_project_list or backend_project_create to set up project context
• Each project can have multiple environments with isolated data

2.3 Table Management Tools (9)

Tools for defining and managing database table schemas.

Field Types:

• string, number, boolean, date, datetime
• text (long text), richtext (HTML content)
• email, url, phone
• enum (with options array)
• relation (with targetTable and relationType)
• file (stored in bkend Storage)
• json (arbitrary JSON object)

2.4 Data CRUD Tools (5)

Tools for creating, reading, updating, and deleting records in tables.

Filter Syntax:

{
  "filter": {
    "field": "status",
    "operator": "eq",
    "value": "active"
  }
}

Supported Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, startsWith, endsWith, exists

Sort Syntax:

{
  "sort": {
    "field": "createdAt",
    "order": "desc"
  }
}

2.5 Environment Tools (3)

Included in Project Management above: backend_env_list, backend_env_create, plus:

2.6 Schema Tools (2)

Included in Table Management above: backend_schema_version_list, backend_schema_version_get.

These tools provide migration history and rollback capabilities for table schemas.

3. MCP Resources (4)

MCP resources provide read-only contextual data that AI models can access without explicit tool calls.

Resource Usage:

• Resources are automatically available to AI models that support MCP resource reading
• Use bkend://context to understand the current working environment
• Use bkend://tables to discover available data structures
• Use bkend://schema/{table} to get detailed field definitions before data operations
• Use bkend://docs/{topic} to retrieve documentation (topics: auth, storage, rls, api-keys, webhooks)

4. Auth & Storage MCP Limitation

Important: bkend.ai does NOT provide MCP tools for Authentication or Storage operations. These features are accessible only through the REST API.

Why No MCP Tools?

• Authentication operations (signup, login, token management) involve sensitive credentials and security flows that are better handled through direct REST API calls with proper error handling
• Storage operations (file upload, download, signed URLs) require binary data transfer that is not well-suited for the MCP tool protocol

Recommended Workflow

1. Use search_docs to find the relevant REST API documentation:

   search_docs("authentication signup")
   search_docs("storage file upload")

2. Use get_operation_schema to get the detailed OpenAPI schema:

   get_operation_schema("auth-signup")
   get_operation_schema("storage-upload")

3. Generate REST API client code based on the retrieved documentation and schemas
4. Use the generated code in your application to call the REST API directly

Auth REST API Endpoints (Reference)

Storage REST API Endpoints (Reference)

5. AI Tool Setup

5.1 Gemini CLI

Create or edit .gemini/settings.json in your project root:

{
  "mcpServers": {
    "bkend": {
      "httpUrl": "https://api.bkend.ai/mcp"
    }
  }
}

Verification:

gemini --mcp-list

The first time you invoke a bkend tool, Gemini CLI will open your browser for OAuth authentication.

5.2 Claude Code

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

{
  "mcpServers": {
    "bkend": {
      "type": "streamable-http",
      "url": "https://api.bkend.ai/mcp"
    }
  }
}

Verification:

claude mcp list

Claude Code will automatically handle OAuth 2.1 + PKCE authentication when tools are first invoked.

5.3 Cursor

1. Open Settings (Cmd/Ctrl + ,)
2. Navigate to MCP section
3. Click Add Server
4. Configure:
   • Name: bkend
   • Type: HTTP
   • URL: https://api.bkend.ai/mcp
5. Click Save

Cursor will prompt for OAuth authentication when MCP tools are first used.

5.4 Windsurf

Create or edit .windsurfrules or use the MCP configuration in settings:

{
  "mcpServers": {
    "bkend": {
      "serverUrl": "https://api.bkend.ai/mcp",
      "transport": "streamable-http"
    }
  }
}

5.5 VS Code (GitHub Copilot)

Add to .vscode/settings.json:

{
  "github.copilot.chat.mcpServers": {
    "bkend": {
      "type": "http",
      "url": "https://api.bkend.ai/mcp"
    }
  }
}

5.6 Other Editors

Any MCP-compatible editor can connect to bkend.ai using:

• Transport: Streamable HTTP
• URL: https://api.bkend.ai/mcp
• Auth: OAuth 2.1 + PKCE (handled automatically by most clients)

6. OAuth 2.1 + PKCE Authentication Flow

Flow Overview

AI Client                    bkend.ai Auth Server              User Browser
   |                                |                               |
   |-- 1. Generate code_verifier -->|                               |
   |-- 2. Compute code_challenge -->|                               |
   |                                |                               |
   |-- 3. GET /oauth/authorize ---->|                               |
   |      ?client_id=...           |                               |
   |      &code_challenge=...      |                               |
   |      &code_challenge_method=S256                               |
   |      &redirect_uri=...        |                               |
   |      &response_type=code      |                               |
   |      &scope=mcp               |                               |
   |                                |-- 4. Show login page -------->|
   |                                |<-- 5. User authenticates -----|
   |                                |                               |
   |<-- 6. Redirect with auth code -|                               |
   |      ?code=AUTH_CODE           |                               |
   |                                |                               |
   |-- 7. POST /oauth/token ------->|                               |
   |      grant_type=authorization_code                             |
   |      code=AUTH_CODE            |                               |
   |      code_verifier=...         |                               |
   |                                |                               |
   |<-- 8. Access + Refresh tokens -|                               |
   |                                |                               |
   |-- 9. MCP requests with ------->|                               |
   |      Authorization: Bearer ... |                               |

Token Lifecycle

Token Refresh

When the access token expires, the MCP client automatically:

1. Sends a POST /oauth/token request with grant_type=refresh_token
2. Includes the refresh token in the request body
3. Receives a new access token (and optionally a new refresh token)
4. Retries the failed MCP request with the new access token

7. MCP Best Practices

7.1 Session Initialization

Always start by verifying your session context:

1. Call get_context -> verify org, project, and environment
2. Call backend_table_list -> understand available data structures
3. Proceed with specific operations

7.2 Schema-First Development

Create tables and define schemas via MCP before performing data operations:

1. backend_table_create -> define table with fields
2. backend_field_manage -> add/modify fields as needed
3. backend_index_manage -> create indexes for query performance
4. backend_data_create -> insert records

7.3 Documentation-Driven Code Generation

For Auth and Storage features (no MCP tools), use documentation tools:

1. search_docs("authentication login flow") -> get documentation
2. get_operation_schema("auth-login") -> get OpenAPI schema
3. Generate client code based on the schema

7.4 Environment Awareness

• Always confirm which environment (dev/staging/prod) you are working in before making changes
• Use get_context to verify the active environment
• Create separate environments for development and production workflows

7.5 Batch Operations

• Use filtering and pagination with backend_data_list for large datasets
• Set appropriate limit values (default: 20, max: 100) to avoid excessive data transfer
• Use sort to control the order of returned records

8. Common MCP Errors and Solutions

Connection Errors

Tool Invocation Errors

Authentication Errors

Quick Reference Card

Essential Tool Sequence

get_context                          # 1. Verify session
backend_org_list                     # 2. List organizations
backend_project_list(orgId)          # 3. List projects
backend_table_list(envId)            # 4. List tables
backend_data_list(envId, tableId)    # 5. Query data

MCP Server Connection

URL:       https://api.bkend.ai/mcp
Transport: Streamable HTTP
Auth:      OAuth 2.1 + PKCE

Tool Count Summary