bkend-mcp

# 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 | Property | Value | |-----------------|--------------------------------------| | Protocol | MCP 2025-03-26 | | Transport | Streamable HTTP | | Authentication | OAuth 2.1 + PKCE | | Server URL | `https://api.bkend.ai/mcp` | | Content Type | `application/json` | | Session Header | `Mcp-Session-Id` | ### 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. | Tool Name | Description | Parameters | |------------------------|---------------------------------------------------|--------------------------------| | `get_context` | Returns current session context including org, project, environment, and user info | None | | `search_docs` | Searches bkend.ai documentation by topic or keyword | `query` (string, required), `category` (string, optional) | | `get_operation_schema` | Returns the OpenAPI schema for a specific REST API operation | `operationId` (string, required) | **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. | Tool Name | Description | Parameters | |--------------------------|------------------------------------------------|-----------------------------------------------------| | `backend_org_list` | Lists all organizations the user belongs to | None | | `backend_project_list` | Lists all projects in the current organization | `orgId` (string, required) | | `backend_project_create` | Creates a new project | `orgId` (string, required), `name` (string, required), `description` (string, optional) | | `backend_project_get` | Gets project details | `projectId` (string, required) | | `backend_env_list` | Lists environments for a project | `projectId` (string, required) | | `backend_env_create` | Creates a new environment (dev/staging/prod) | `projectId` (string, required), `name` (string, required), `type` (enum: dev/staging/prod) | **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. | Tool Name | Description | Parameters | |--------------------------------|---------------------------------------------|---------------------------------------------------------| | `backend_table_list` | Lists all tables in the environment | `envId` (string, required) | | `backend_table_create` | Creates a new table with fields | `envId` (string, required), `name` (string, required), `fields` (array, required) | | `backend_table_get` | Gets table schema details | `envId` (string, required), `tableId` (string, required) | | `backend_table_update` | Updates table settings | `envId` (string, required), `tableId` (string, required), `settings` (object, required) | | `backend_table_delete` | Deletes a table and all its data | `envId` (string, required), `tableId` (string, required) | | `backend_field_manage` | Adds, updates, or removes fields on a table | `envId` (string, required), `tableId` (string, required), `action` (enum: add/update/remove), `field` (object, required) | | `backend_index_manage` | Manages indexes on a table | `envId` (string, required), `tableId` (string, required), `action` (enum: create/delete), `index` (object, required) | | `backend_schema_version_list` | Lists schema versions (migration history) | `envId` (string, required), `tableId` (string, required) | | `backend_schema_version_get` | Gets a specific schema version | `envId` (string, required), `tableId` (string, required), `versionId` (string, required) | **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. | Tool Name | Description | Parameters | |------------------------|------------------------------------------|-----------------------------------------------------------| | `backend_data_list` | Lists records with filtering and paging | `envId` (string, required), `tableId` (string, required), `filter` (object, optional), `sort` (object, optional), `page` (number, optional), `limit` (number, optional) | | `backend_data_get` | Gets a single record by ID | `envId` (string, required), `tableId` (string, required), `recordId` (string, required) | | `backend_data_create` | Creates a new record | `envId` (string, required), `tableId` (string, required), `data` (object, required) | | `backend_data_update` | Updates an existing record | `envId` (string, required), `tableId` (string, required), `recordId` (string, required), `data` (object, required) | | `backend_data_delete` | Deletes a record | `envId` (string, required), `tableId` (string, required), `recordId` (string, required) | **Filter Syntax:** ```json { "filter": { "field": "status", "operator": "eq", "value": "active" } } ``` **Supported Operators:** `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`, `startsWith`, `endsWith`, `exists` **Sort Syntax:** ```json { "sort": { "field": "createdAt", "order": "desc" } } ``` ### 2.5 Environment Tools (3) Included in Project Management above: `backend_env_list`, `backend_env_create`, plus: | Tool Name | Description | Parameters | |----------------------|------------------------------------------------|-----------------------------------------------------| | `backend_env_get` | Gets environment details and configuration | `envId` (string, required) | ### 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 URI | Description | MIME Type | |-------------------------------|------------------------------------------------|--------------------| | `bkend://context` | Current session context (org, project, env) | `application/json` | | `bkend://tables` | List of all tables in the current environment | `application/json` | | `bkend://schema/{table}` | Full schema definition for a specific table | `application/json` | | `bkend://docs/{topic}` | Documentation content for a specific topic | `text/markdown` | **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`)