MCP Protocol Implementation
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) implementation within the SecondLayer project provides a standardized interface for AI models to interact with specialized legal tech tools and data. It acts as a bridge between LLM clients (such as Claude Desktop or ChatGPT) and the platform's backend services, including court case databases, legislation retrieval systems, and business registries. Sources: CLAUDE.md, README.md
The implementation follows a "Triple Transport System," allowing the protocol to be consumed through three distinct methods: standard input/output (stdio) for local integration, a RESTful HTTP API for web applications, and Remote MCP over Server-Sent Events (SSE) for distributed clients over HTTPS. Sources: CLAUDE.md, mcp_backend/src/http-server.ts:805-900
Architecture and Transport Layers
The system utilizes a modular architecture where a central ToolRegistry maps tool definitions to specific handler classes. This allows the same logic to be exposed across different transport layers. Sources: CLAUDE.md, mcp_backend/src/http-server.ts:133-165
Triple Transport Overview
| Transport | Use Case | Implementation Details |
|---|---|---|
| MCP stdio | Local desktop integration | Standard MCP protocol for Claude Desktop. |
| HTTP API | Web applications | REST endpoints (/api/tools/:toolName) with optional SSE streaming. |
| Remote SSE | Remote HTTPS clients | JSON-RPC 2.0 over Server-Sent Events for distributed integration. |
Sources: CLAUDE.md, README.md, mcp_backend/src/http-server.ts:1145-1155
Data Flow Diagram
The following diagram illustrates how different clients interact with the unified MCP backend through various transport layers.
SSE Implementation and JSON-RPC 2.0
The SSE implementation enables real-time, asynchronous communication required for long-running legal analysis tasks. It supports the JSON-RPC 2.0 protocol as specified by the MCP standard. Sources: mcp_backend/CHANGELOG_CHATGPT.md, mcp_backend/src/http-server.ts:805-850
Connection Lifecycle
When a client connects via SSE, the server establishes a persistent connection. For tool execution, the sequence generally follows a connected -> progress -> complete -> end pattern. Sources: mcp_backend/src/api/tests/sse/README.md, mcp_backend/src/http-server.ts:1340-1380
Key Components
MCPSSEServer
The MCPSSEServer class manages tool discovery and execution specifically for the SSE transport. It handles session management and maps MCP protocol methods (like tools/list and tools/call) to the internal registry. Sources: mcp_backend/src/api/mcp-sse-server.ts, mcp_backend/src/api/tests/sse/README.md
Tool Registry
The ToolRegistry serves as the central hub for all 44+ available tools. It categorizes tools into backend core tools, RADA parliament tools, and OpenReyestr registry tools. Sources: CLAUDE.md, mcp_backend/src/http-server.ts:133-165
| Tool Category | Example Tools | Purpose |
|---|---|---|
| Legal Research | search_legal_precedents, get_court_decision | Court case search and retrieval. |
| Legislation | search_legislation, get_legislation_article | Ukrainian law text and structure. |
| Analysis | get_legal_advice, analyze_case_pattern | Complex AI-driven reasoning. |
| Registry | search_business_entities, lookup_by_edrpou | Business and beneficiary data. |
Sources: mcp_backend/CHANGELOG_CHATGPT.md, mcp_backend/src/http-server.ts:1230-1280
Authentication and Security
Authentication for the MCP endpoints is mandatory to track usage and costs. The system supports multiple authentication schemes. Sources: mcp_backend/src/http-server.ts:805-840, mcp_backend/JWT_AUTH_SETUP.md
- API Keys: Provided via
Authorization: Bearer <KEY>. Keys are validated against theApiKeyService. - JWT Tokens: Used for authenticated web sessions and specific client integrations like Claude Desktop.
- OAuth 2.0: Implemented specifically for ChatGPT Custom Connectors, supporting the standard authorization and token exchange flow.
Sources: mcp_backend/src/http-server.ts:810-860, mcp_backend/CHANGELOG_CHATGPT.md, mcp_backend/JWT_AUTH_SETUP.md
Cost Tracking Integration
A critical feature of the MCP implementation is the integrated CostTracker. Every tool execution tracks OpenAI/Anthropic token usage, execution time, and external API calls (e.g., ZakonOnline). Sources: CLAUDE.md, mcp_backend/REMOTE_MCP_DEPLOYMENT.md
Before executing a tool via the HTTP API, the balanceCheckMiddleware verifies if the user has sufficient credits. After execution, the actual cost is calculated and deducted from the user's balance. Sources: mcp_backend/src/http-server.ts:1200-1230, mcp_backend/src/api/mcp-sse-server.ts
Conclusion
The SecondLayer MCP Protocol implementation provides a high-performance, secure, and transparent way to access legal data and AI tools. By supporting multiple transport layers (stdio, HTTP, SSE) and strictly adhering to the MCP JSON-RPC 2.0 specification, it ensures broad compatibility with modern LLM clients while maintaining strict control over resource usage and costs. Sources: CLAUDE.md, mcp_backend/CHANGELOG_CHATGPT.md, mcp_backend/src/http-server.ts