Understanding the MCP Protocol
💡 Learn the core concepts of MCP (Model Context Protocol) and how the bkend MCP server works.
Overview
MCP (Model Context Protocol) is a standard protocol for AI tools to communicate with external services. bkend uses the Streamable HTTP transport defined in the MCP 2025-03-26 specification.
Supported Specifications
Protocol Version
2025-03-26
Transport
Streamable HTTP
Message Format
JSON-RPC 2.0
Authentication
OAuth 2.1 + PKCE
Endpoint
https://api.bkend.ai/mcp
Streamable HTTP
bkend uses Streamable HTTP instead of SSE.
Transport Method
Simple POST request/response
Server-to-client stream
Connection Behavior
Connects only per request
Always open
Server Resources
Released after request
Memory held per connection
Scalability
Easy to auto-scale
Hard to scale by connection
Core Components
Tools
Functions that AI tools can invoke. bkend provides two types.
Fixed Tools — Context retrieval and documentation search:
get_context
Must be called at session start — provides Organization ID and resource hierarchy
search_docs
Search bkend documentation
API Tools — Invoke management functions on the bkend backend.
For the full list of tools, see the MCP Tools Overview.
Resources
Data resources provided by the MCP server.
For resource details, see MCP Resources.
Permission Scopes
Permissions granted to the MCP token.
organization:read
View Organization information
project:read / project:create / project:update / project:delete
Manage Projects
environment:read / environment:create / environment:delete
Manage Environments
table:read / table:create / table:update / table:delete
Manage table schemas
table:data:read / table:data:create / table:data:update / table:data:delete
Table data CRUD
access-token:read
View Access Tokens
Wildcard Scopes
*:*
Full access
project:*
All actions on Projects
*:read
Read access to all resources
⚠️ You must call get_context at the start of each session before invoking other MCP tools. Subsequent tool calls will fail without the Organization ID and resource hierarchy.
Error Codes
-32700
Parse Error
JSON parsing failed
-32600
Invalid Request
Malformed request
-32601
Method Not Found
Non-existent method
-32602
Invalid Params
Invalid parameters
-32603
Internal Error
Server internal error
-32001
Unauthorized
Authentication failed
-32002
Not Found
Resource not found / Session expired
Next Steps
OAuth 2.1 Authentication — Detailed authentication flow
Setup — Install and authenticate your AI tool
API Reference — Full MCP tool schema
Reference Standards
Last updated