MCP (Model Context Protocol)
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) Unified stack is the production-ready implementation within the tldw_server project designed to provide a secure, standardized interface for AI agents to interact with server-side tools and data. It consolidates previous protocol versions into a single, high-performance surface that supports both HTTP and WebSocket transports, enabling real-time bidirectional communication between the server and agentic clients like IDEs or standalone LLM applications.
Sources: Docs/MCP/Unified/README.md, tldw_Server_API/app/core/MCP_unified/README.md:1-10, Docs/MCP/Unified/User_Guide.md:7-15
Within the tldw_server architecture, MCP serves as the primary bridge for "agentic" interaction, mapping core domain modules (such as Media, Knowledge, and Notes) into executable tools. It incorporates enterprise-grade security features including JWT/RBAC, rate limiting, and circuit breakers to ensure that autonomous agents operate within governed boundaries.
Sources: Docs/Architecture.md:200-205, AGENTS.md:50-55, tldw_Server_API/app/core/MCP_unified/README.md:50-60
System Architecture
The MCP Unified module follows a modular architecture where a central server facade manages the protocol handshake, session state, and security gating, while specific functionalities are delegated to pluggable modules.
High-Level Architecture Diagram
The following diagram illustrates the relationship between clients, the MCP Unified server, and the underlying module system.
Core Components
| Component | Description | Source |
|---|---|---|
| MCPServer | The server facade handling WebSocket and HTTP connections and session management. | tldw_Server_API/app/core/MCP_unified/README.md:30 |
| Protocol Handler | Implements the JSON-RPC 2.0 protocol for MCP v1 and v2 messages. | tldw_Server_API/app/core/MCP_unified/README.md:31 |
| Module Registry | Manages the lifecycle and discovery of pluggable MCP modules. | tldw_Server_API/app/core/MCP_unified/README.md:130 |
| Auth/RBAC | Enforces fine-grained permissions for tool execution (e.g., tools.execute:name). | tldw_Server_API/app/core/MCP_unified/README.md:255 |
| Circuit Breakers | Prevents system cascades by monitoring module health and opening during failures. | tldw_Server_API/app/core/MCP_unified/README.md:330 |
Protocol & API Endpoints
MCP Unified supports two primary communication patterns: a REST-like HTTP facade for discovery and stateless execution, and a stateful WebSocket connection for persistent agent interaction.
API Endpoint Reference
| Endpoint | Method | Purpose | Source |
|---|---|---|---|
/api/v1/mcp/ws | WS | Stateful JSON-RPC session over WebSocket. | Docs/MCP/Unified/User_Guide.md:55 |
/api/v1/mcp/request | POST | Single JSON-RPC 2.0 request (stateless). | Docs/MCP/Unified/User_Guide.md:60 |
/api/v1/mcp/tools | GET | List available tools (RBAC-filtered). | tldw_Server_API/app/core/MCP_unified/README.md:195 |
/api/v1/mcp/tools/execute | POST | Convenience endpoint for direct tool execution. | tldw_Server_API/app/core/MCP_unified/README.md:20 |
/api/v1/mcp/status | GET | Returns server status and initialization state. | Docs/MCP/Unified/User_Guide.md:25 |
/api/v1/mcp/metrics/prometheus | GET | Prometheus-compatible metrics endpoint. | tldw_Server_API/app/core/MCP_unified/README.md:310 |
Sequence: Tool Execution Flow
The following diagram demonstrates the sequence of events when an agent calls a tool via the MCP Unified server.
Module System
The module system allows developers to extend MCP capabilities by creating subclasses of BaseModule. These modules are typically located in tldw_Server_API/app/core/MCP_unified/modules/implementations/.
Module Lifecycle
Modules follow a strict lifecycle managed by the ModuleRegistry:
- Discovery: Modules are identified via YAML config (
mcp_modules.yaml) or environment variables. - Initialization:
on_initialize()is called to set up resources (e.g., database handles). - Execution: The module handles
get_tools()andexecute_tool()requests. - Health Monitoring:
check_health()is polled periodically to update circuit breaker state. - Shutdown:
on_shutdown()ensures resources are released.
Sources: Docs/MCP/Unified/Modules.md:15-30, tldw_Server_API/app/core/MCP_unified/README.md:330
Security Constraints for Modules
- Autoload Safety: Modules must reside under the
tldw_Server_API.app.core.MCP_unified.modules.implementationsnamespace to be autoloaded. - Input Sanitization: Modules have access to
sanitize_input()helpers to prevent injection attacks. - SSRF Protection: Media modules implement host and port allowlists to prevent Server-Side Request Forgery.
Sources: Docs/MCP/Unified/Modules.md:65-75, tldw_Server_API/app/core/MCP_unified/README.md:165-175
Security and Governance
MCP Unified incorporates several layers of protection to ensure safe autonomous operation.
Security Configuration
| Option | Default | Description | Source |
|---|---|---|---|
MCP_WS_AUTH_REQUIRED | true | Enforces authentication for all WebSocket connections. | tldw_Server_API/app/core/MCP_unified/README.md:265 |
MCP_DISABLE_WRITE_TOOLS | false | Global switch to block all tools categorized as ingestion or management. | tldw_Server_API/app/core/MCP_unified/README.md:275 |
MCP_VALIDATE_INPUT_SCHEMA | true | Validates tool arguments against their JSON schema before execution. | tldw_Server_API/app/core/MCP_unified/README.md:276 |
MCP_WS_ALLOWED_ORIGINS | (empty) | Comma-separated allowlist for Cross-Origin Resource Sharing (CORS). | tldw_Server_API/app/core/MCP_unified/README.md:266 |
Idempotency and Write Safety
For operations that modify state (e.g., in the Kanban or Media modules), MCP Unified implements a protocol-level idempotency cache.
- Clients can provide an
idempotencyKeyin the tool call parameters. - The server caches results for a configurable TTL (default 300s).
- Subsequent requests with the same key and identical arguments return the cached result instead of re-executing.
Sources: tldw_Server_API/app/core/MCP_unified/README.md:277-280, Docs/MCP/Unified/User_Guide.md:225-235
Summary
The Model Context Protocol (MCP) Unified stack provides the critical infrastructure for turning the tldw_server into an agent-compatible platform. By centralizing tool discovery, execution logic, and security governance, it allows AI agents to safely interact with complex media processing and knowledge management workflows. Its support for standardized JSON-RPC communication ensures compatibility with a growing ecosystem of MCP-aware tools while maintaining robust production guards against unauthorized access and system instability.
Sources: tldw_Server_API/app/core/MCP_unified/README.md:10-20, Docs/MCP/Unified/README.md:25-30