MCP Server Integration

Relevant source files

The following files were used as context for generating this wiki page:

• mcp_server/server.py
• mcp_server/app.py
• services/config_inspector_service.py
• GUIDES/ARCHITECTURE.md
• GUIDES/MERMAID_IN_MARKDOWN.md

The Model Context Protocol (MCP) Server Integration in CodeBot facilitates seamless communication between AI models (such as Claude) and the CodeKeeper ecosystem. It enables external AI agents to search, read, edit, and manage user code snippets, collections, and documentation through a standardized interface. The integration is built using the FastMCP framework and exposes tools via a Streamable-HTTP ASGI application.

Sources: mcp_server/server.py:1-25, mcp_server/app.py:1-15

System Architecture

The MCP server acts as a gateway, exposing a set of tools to AI clients while delegating data persistence and retrieval to a shared MongoDB backend. The server supports two primary authentication modes: full OAuth 2.1 for integration with Claude.ai and a Personal Access Token (PAT) fallback for Claude Desktop or Claude Code.

The diagram shows the flow from an external AI client through the authentication and tool layers to the core data stores of the project.
Sources: mcp_server/server.py:461-496, mcp_server/app.py:90-112, GUIDES/ARCHITECTURE.md:14-41

Authentication and Security

Security is enforced through multiple layers, including DNS-rebinding protection and granular access control for different tool categories.

Authentication Modes

The server determines its authentication strategy based on environment variables:

• OAuth 2.1 Mode: Activated when MCP_SERVER_URL and WEBAPP_URL are both configured. This uses a CodeKeeperOAuthProvider to handle identity assertions and consent.
• PAT Fallback: A PATAuthMiddleware is used when OAuth is not configured, allowing simpler token-based access.

Sources: mcp_server/app.py:10-18, mcp_server/app.py:90-112

Tool-Level Permissions

Permissions are categorized into three levels to prevent unauthorized operations:

1. Read-Only: Standard operations like codekeeper_list_files.
2. Write: Operations that modify user data, requiring explicit write scope via require_write(ctx).
3. Admin: Repository browser tools available only to administrators, enforced by require_admin(ctx) and visibility filtering in AdminAwareFastMCP.

Sources: mcp_server/server.py:48-89, mcp_server/server.py:165-170

MCP Tools and Functionality

The integration exposes specialized tools for interacting with files, collections, notes, and documentation.

Core File Operations

Tool Name	Type	Description
codekeeper_list_files	Read	Lists user's saved code metadata (paginated).
codekeeper_search_code	Read	Text-based search across user snippets.
codekeeper_get_file	Read	Retrieves full content and metadata for a specific file.
codekeeper_save_file	Write	Creates or updates a file (non-destructive versioning).
codekeeper_edit_file	Write	Performs targeted find-and-replace edits.

Sources: mcp_server/server.py:126-192

Specialized Tools

• Documentation Tools: The codekeeper_docs_get_section tool allows reading specific sections of RST documentation files, providing navigation metadata and breadcrumbs instead of full-file content.
• Admin Repo Tools: Includes codekeeper_list_repos and codekeeper_search_repo for browsing mirrored repositories directly on the server.
• Sticky Notes: Tools like codekeeper_create_note and codekeeper_update_note synchronize with the CodeKeeper web UI.

Sources: mcp_server/server.py:270-323, mcp_server/server.py:421-458

Configuration Parameters

The MCP integration is governed by specific environment variables defined in the system's configuration service.

Variable	Default	Category	Description
MCP_SERVER_URL	None	mcp	Public URL of the MCP service (OAuth Issuer).
MCP_SERVER_NAME	"CodeKeeper"	mcp	Display name for the connector.
MCP_ALLOWED_HOSTS	None	mcp	CSV of hosts allowed (DNS-rebinding protection).
MCP_REPO_AUTOSYNC	"1"	mcp	Enables background mirroring of repositories.
MCP_DOCS_REPO	"CodeBot"	mcp	Allowlist for repositories accessible via docs tools.

Sources: services/config_inspector_service.py:537-584

Data Flow for Tool Execution

The server uses synchronous functions for tools to ensure compatibility with FastMCP worker threads, preventing the event loop from stalling during blocking MongoDB calls.

Summary

The MCP Server Integration provides a robust, authenticated bridge between CodeBot and AI agents. By utilizing a versioned, non-destructive approach to file edits and a layered security model (OAuth/PAT + Admin/Write/Read scopes), it ensures that AI models can safely interact with user data while maintaining full traceability and access control through the core project's MongoDB and Git mirror infrastructure.