MCP Server - Knowledge Base Tools

MCP (Model Context Protocol) server exposing knowledge base operations as tools for AI agents.

Overview

This MCP server provides tools for interacting with the Django backend API to manage and query the knowledge base. All tools require JWT authentication and automatically handle tenant-aware routing.

Features

• JWT Authentication: Token verification using shared secret with Django backend
• Tenant-aware: Automatically extracts tenant from JWT and routes to correct backend instance
• 8 Knowledge Base Tools: Complete set of operations for navigating and managing the knowledge graph

Installation

1. Create and activate virtual environment (recommended):

   python3 -m venv venv
   
   # On macOS/Linux:
   source venv/bin/activate
   
   # On Windows:
   # venv\Scripts\activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment variables:

   cp .env.example .env
   # Edit .env with your configuration
   

Configuration

Environment Variables

• MCP_JWT_SECRET_KEY: Secret key for JWT token verification (can use CHAINLIT_JWT_SECRET_KEY as fallback)
• MCP_BACKEND_URL: Backend URL with tenant placeholder, e.g., http://tenant.localhost:8000 (can use BACKEND_URL as fallback)

Example .env file:

MCP_JWT_SECRET_KEY=your-secret-key-here
MCP_BACKEND_URL=http://tenant.localhost:8000

Available Tools

1. get_root_themes_tool

Get all root theme nodes (top-level folders without parents). Entry point for navigating the knowledge base.

2. get_folder_tree_tool

Get complete folder tree under a theme node. Returns only themes recursively, excluding skills and knowledge nodes.

3. semantic_search_tool

Perform semantic search across themes, skills, and knowledge nodes using vector similarity.

4. get_node_children_tool

Get direct children of a node for downward navigation in the hierarchy.

5. get_node_parents_tool

Get direct parent nodes for upward navigation in the hierarchy.

6. create_folder_tool

Create a new theme (folder) node at root or under a parent theme.

7. create_skill_tool

Create a new skill node under a parent theme.

8. generate_learning_tools_tool

Generate learning tools (knowledge nodes with questions) for a skill using AI.

Running the Server

Make sure your virtual environment is activated before running the server.

Start the HTTP/SSE server:

# Activate venv first
source venv/bin/activate  # On macOS/Linux
# venv\Scripts\activate   # On Windows

python server.py

The server will start on http://0.0.0.0:8100 by default (configurable via environment variables).

Configuration options:

• MCP_HOST: Host to bind (default: 0.0.0.0)
• MCP_PORT: Port number (default: 8100 - port 8000 is used by the Django backend)
• MCP_TRANSPORT: Transport type - sse (Server-Sent Events) or streamable-http (default: sse)

With MCP Inspector (for testing):

1. Start the server:

   python server.py
   

2. In MCP Inspector, configure the connection:

   • Type: sse
   • URL: http://localhost:8100/sse (use localhost not 0.0.0.0 in browser)

   Example configuration:

   {
     "mcpServers": {
       "knowledge-base": {
         "type": "sse",
         "url": "http://localhost:8100/sse"
       }
     }
   }
   

   Note: The server binds to 0.0.0.0 but you must use localhost or 127.0.0.1 in browser-based clients.

Usage

All tools require a jwt_token parameter containing the user's JWT authentication token. The token should:

• Be a valid JWT signed with the same secret as configured in MCP_JWT_SECRET_KEY
• Contain a tenant claim for tenant-aware routing
• Be passed as a Bearer token or raw token string

Example tool call:

result = get_root_themes_tool(
    jwt_token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
)

Architecture

• auth.py: JWT token verification and tenant extraction
• tools.py: Core tool functions that interact with Django backend
• server.py: FastMCP server setup and tool registration

Security

• All tools verify JWT tokens before processing requests
• Tenant is extracted from token payload (never from user input)
• Backend URL is constructed from token, ensuring tenant isolation
• Invalid or expired tokens return error responses

Error Handling

All tools return a dictionary with:

• success: true and data on success
• success: false and error: "message" on failure

Development

The server uses FastMCP, which automatically handles:

• Tool registration
• Request/response serialization
• Error handling
• Logging

Related Files

• shad/agents/tools.py: Original LangChain tools (reference implementation)
• backend/learn/: Django backend API endpoints