# MCP

{% hint style="info" %}
💡 Use the bkend MCP server to manage your backend with natural language from AI tools like Claude Code, Cursor, and VS Code.
{% endhint %}

## Overview

bkend connects to AI tools through [MCP (Model Context Protocol)](https://spec.modelcontextprotocol.io/2025-03-26). When you issue natural language commands from an MCP-compatible AI tool, bkend automatically manages Database, Auth, and Storage for you.

{% @mermaid/diagram content="flowchart LR
A\[AI Tool] -->|MCP Protocol| B\[bkend MCP Server]
B -->|OAuth 2.1 + PKCE| C\[bkend Backend]
C --> D\[Database]
C --> E\[Auth]
C --> F\[Storage]" %}

***

## MCP Server Information

| Item             | Value                                                                              |
| ---------------- | ---------------------------------------------------------------------------------- |
| Server URL       | `https://api.bkend.ai/mcp`                                                         |
| Protocol Version | `2025-03-26`                                                                       |
| Transport        | Streamable HTTP                                                                    |
| Authentication   | [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12) + PKCE |
| Message Format   | JSON-RPC 2.0                                                                       |

***

## Available Tools

### Fixed Tools

These tools handle session context and documentation search.

| Tool          | Description                                                                                          | Details                                                               |
| ------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `get_context` | Must be called at session start — provides Organization ID, resource hierarchy, and usage guidelines | [Context](https://bkend.gitbook.io/bkend-docs/01-overview/06-context) |
| `search_docs` | Search bkend documentation — API guides, auth implementation, CRUD patterns, code examples           | [Context](https://bkend.gitbook.io/bkend-docs/01-overview/06-context) |

### API Tools

These tools directly manage your backend. They all use the `backend_` prefix.

| Category           | Tool Count | Description                                                     | Details                                                                           |
| ------------------ | :--------: | --------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Project Management |      9     | Manage Organizations, projects, environments, and access tokens | [Project Tools](https://bkend.gitbook.io/bkend-docs/01-overview/07-project-tools) |
| Table Management   |      7     | Manage tables, fields, indexes, and schema versions             | [Table Tools](https://bkend.gitbook.io/bkend-docs/01-overview/08-table-tools)     |

### REST API Code Generation

Auth, Storage, and Data CRUD do not have dedicated MCP tools. Instead, use `search_docs` to find implementation guides, then generate **REST API code**.

| Feature   | MCP Tool | Alternative                                                                                                  |
| --------- | :------: | ------------------------------------------------------------------------------------------------------------ |
| Auth      |    N/A   | Generate REST API code — [Code Generation](https://bkend.gitbook.io/bkend-docs/09-code-generation#auth)      |
| Storage   |    N/A   | Generate REST API code — [Code Generation](https://bkend.gitbook.io/bkend-docs/09-code-generation#storage)   |
| Data CRUD |    N/A   | Generate REST API code — [Code Generation](https://bkend.gitbook.io/bkend-docs/09-code-generation#data-crud) |

{% hint style="info" %}
💡 When you ask your AI tool to "implement a login feature" or "add data to a table," `search_docs` automatically finds the relevant docs and generates the REST API calling code.
{% endhint %}

{% hint style="warning" %}
⚠️ MCP tools control **management functions** (table schemas, projects, environments, etc.). They are different from the REST API used for app user data. For REST API integration, see [Integrating bkend in Your App](https://bkend.gitbook.io/bkend-docs/01-what-is-bkend/03-app-integration).
{% endhint %}

***

## Complete Tool List

{% @mermaid/diagram content="graph TD
subgraph Fixed\["Fixed Tools"]
A\[get\_context]
B\[search\_docs]
end

```
subgraph Project["Project Management"]
    C[backend_org_list / _get]
    D[backend_project_list / _get / _create / _update]
    E[backend_env_list / _get / _create]
    F[backend_access_token_list / _get]
end

subgraph Table["Table Management"]
    G[backend_table_list / _get / _create / _update]
    H[backend_field_manage]
    I[backend_index_manage]
    J[backend_schema_version_list]
    K[backend_index_version_list]
end

Fixed --> Project
Project --> Table" %}
```

***

## Resources

MCP Resources let you query the current state in read-only mode through the `bkend://` URI schema.

| Resource          | URI Pattern                              | Description           |
| ----------------- | ---------------------------------------- | --------------------- |
| Organization      | `bkend://organizations/{organizationId}` | Organization details  |
| Organization List | `bkend://organizations`                  | List of Organizations |
| Project           | `bkend://projects/{projectId}`           | Project details       |
| Project List      | `bkend://projects`                       | List of projects      |
| Environment       | `bkend://environments/{environmentId}`   | Environment details   |
| Environment List  | `bkend://environments`                   | List of environments  |
| Table             | `bkend://tables/{tableId}`               | Table details         |
| Table List        | `bkend://tables`                         | List of tables        |

> For details, see [MCP Resources](https://bkend.gitbook.io/bkend-docs/01-overview/10-resources).

***

## Permissions (Scopes)

These are the permissions granted during MCP integration.

| Resource     | Read | Create | Update | Delete |
| ------------ | :--: | :----: | :----: | :----: |
| Organization |   ✅  |    -   |    -   |    -   |
| Project      |   ✅  |    ✅   |    ✅   |    ✅   |
| Environment  |   ✅  |    ✅   |    -   |    ✅   |
| Table Schema |   ✅  |    ✅   |    ✅   |    ✅   |
| Table Data   |   ✅  |    ✅   |    ✅   |    ✅   |
| Access Token |   ✅  |    -   |    -   |    -   |

***

## Quick Start

> For the full setup guide, see [Setup](https://bkend.gitbook.io/bkend-docs/01-overview/02-setup).

***

## Next Steps

* [Setup](https://bkend.gitbook.io/bkend-docs/01-overview/02-setup) — Install and authenticate your AI tool
* [Usage](https://bkend.gitbook.io/bkend-docs/01-overview/03-usage) — Prompt examples and best practices
* [MCP Protocol](https://bkend.gitbook.io/bkend-docs/01-overview/04-protocol) — Protocol specification details
* [OAuth 2.1 Authentication](https://bkend.gitbook.io/bkend-docs/01-overview/05-oauth) — Authentication flow and token management
* [Context](https://bkend.gitbook.io/bkend-docs/01-overview/06-context) — `get_context` and `search_docs` details
* [Project Tools](https://bkend.gitbook.io/bkend-docs/01-overview/07-project-tools) — Organization, project, and environment management
* [Table Tools](https://bkend.gitbook.io/bkend-docs/01-overview/08-table-tools) — Table, field, and index management
* [Code Generation](https://bkend.gitbook.io/bkend-docs/01-overview/09-code-generation) — REST API code generation for Auth, Storage, Data
* [Resources](https://bkend.gitbook.io/bkend-docs/01-overview/10-resources) — MCP resource URIs
* [API Reference](https://bkend.gitbook.io/bkend-docs/01-overview/11-api-reference) — Complete tool schemas
* [Hands-on Project Cookbooks](https://github.com/popup-studio-ai/bkend-docs/blob/main/cookbooks/README.md) — Build real app backends with MCP

## Reference Standards

* [MCP Specification 2025-03-26](https://spec.modelcontextprotocol.io/2025-03-26)
* [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)