KI
Developer Tools

Kibela MCP Server API Integration Guide

Integrate your MCP server with the Kibela API using step-by-step setup, authentication, and examples to automate content, sync users, and manage workflows.

View on GitHub
Quick Install
npx -y @kiwamizamurai/mcp-kibela-server

Overview

The Kibela MCP Server is a lightweight bridge that connects an MCP (Model Context Protocol) compatible LLM or agent runtime to the Kibela API. It exposes a small set of HTTP endpoints that accept MCP-style tool invocation requests and translate them into authenticated Kibela API calls, enabling automation of content creation, user synchronization, and workflow orchestration inside Kibela from model-driven applications.

This server is useful when you want your language model or automation pipeline to create or update Kibela notes, manage users and permissions, or coordinate review/publish workflows without embedding Kibela credentials in the model client. It centralizes Kibela integration logic (authentication, rate control, retry and mapping of model tool calls to Kibela endpoints) so downstream agents call a single, predictable API.

Features

  • Translates MCP tool calls into Kibela API requests
  • Centralized Kibela authentication via API token
  • Endpoints for content operations (create/update notes), user sync, and health checks
  • Configurable via environment variables or Docker
  • Example payloads and mappings to speed integration with LLM agents
  • Lightweight and easy to run alongside existing model runtimes

Installation / Configuration

Prerequisites:

  • Node.js (>= 14) or Docker
  • A Kibela workspace and personal API token (create one in Kibela settings)

Quick start (local):

git clone https://github.com/kiwamizamurai/mcp-kibela-server.git
cd mcp-kibela-server
npm install

Create a .env file (example):

# .env
MCP_SERVER_PORT=3000
MCP_SECRET=super-secret-token
KIBELA_BASE_URL=https://your-team.kibe.la
KIBELA_API_TOKEN=<your_kibela_api_token>
LOG_LEVEL=info

Start locally:

npm start
# or
node src/index.js

Docker usage (example):

# docker-compose.yml
version: "3.8"
services:
  mcp-kibela:
    image: your-registry/mcp-kibela-server:latest
    ports:
      - "3000:3000"
    environment:
      - MCP_SERVER_PORT=3000
      - MCP_SECRET=${MCP_SECRET}
      - KIBELA_BASE_URL=${KIBELA_BASE_URL}
      - KIBELA_API_TOKEN=${KIBELA_API_TOKEN}

Then:

docker compose up -d

Environment variables reference:

VariableDescription
MCP_SERVER_PORTPort the MCP server listens on (default: 3000)
MCP_SECRETShared secret for authenticating incoming MCP requests
KIBELA_BASE_URLBase URL of your Kibela workspace (e.g. https://your-team.kibe.la)
KIBELA_API_TOKENPersonal access token for Kibela API calls
LOG_LEVELLogging verbosity (info, debug, error)

Authentication

The server uses your Kibela personal access token to call the Kibela API. Tokens are provided via KIBELA_API_TOKEN in env. Kibela API calls require the Authorization header:

Example curl (create note):

curl -X POST "${KIBELA_BASE_URL}/api/v1/notes" \
  -H "Authorization: Bearer ${KIBELA_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"title":"Automated Note","body":"This note was created via MCP server."}'

Incoming MCP requests to this server should be protected by MCP_SECRET. Include it as a header (e.g., X-MCP-Secret) on calls from your agent runtime.

Available Resources

Common endpoints exposed by the server (HTTP):

  • GET /health
    • Returns 200 if server and Kibela auth are healthy.
  • POST /mcp
    • Accepts MCP-compatible tool invocation requests (JSON). The server maps declared tool names to Kibela operations (create_note, update_note, comment, etc.).
  • POST /sync/users
    • Trigger user synchronization. Accepts a JSON array of users or runs a sync from a configured identity provider.
  • POST /callbacks/:id
Tags:developer-tools