System Overview

The SigilAI MCP server is architected as a robust, scalable, and secure platform for delivering security scanning capabilities to AI systems and developers. This document provides a high-level overview of the system architecture, its key components, and the design principles that guide its development.

Architectural Goals

The SigilAI architecture is designed to achieve the following key goals:

• Modularity: Components are designed to be independent and interchangeable.

• Scalability: The system can handle increasing loads and data volumes.

• Reliability: High availability and fault tolerance are prioritized.

• Security: Secure by design, protecting data and system integrity.

• Extensibility: New scanning capabilities and tools can be easily added.

• Interoperability: Seamless integration with AI platforms via MCP.

• Maintainability: Clear separation of concerns for ease of updates.

High-Level Architecture

Key Architectural Layers

1. Client Layer: Consists of applications that consume SigilAI's services, such as Large Language Models (LLMs), AI assistants, or developer tools. These clients interact with the SigilAI MCP Server via the Model Context Protocol.

2. MCP Server Layer: This is the core of the SigilAI platform.

   • MCP Interface: Handles incoming MCP requests (e.g., over Server-Sent Events - SSE), validates them, and manages communication with clients.

   • Tool Dispatcher: Routes validated requests to the appropriate scanning service based on the tool name.

   • Session Management: Manages client sessions, including connection and disconnection events.

   • Configuration Service: Provides configuration parameters to various components.

   • Logging & Monitoring: Captures system logs and metrics for operational insights and troubleshooting.

3. Security Scanning Core: Contains the specialized services that perform the actual security analysis.

   • URL Scanning Service: Analyzes URLs for threats.

   • File Scanning Service: Scans source code files for vulnerabilities.

   • Test Tool Service: Provides a simple echo-like service for testing MCP connectivity.

   • Future Scanning Services: Placeholder for new scanning capabilities.

4. External Dependencies & Integrations: Represents external systems and data sources that the scanning core relies on.

   • Security Databases: Such as URL blacklists or vulnerability databases.

   • Third-Party Scanning Engines: External tools like Semgrep or Snyk that are invoked by the File Scanning Service.

   • Data Storage: For persisting scan results, user data, or configuration.

Design Principles & Best Practices

SigilAI's architecture adheres to industry best practices and design principles:

Separation of Concerns

Each component has a well-defined responsibility. For example, the MCP Interface handles protocol-level communication, while the Scanning Services focus solely on analysis. This promotes modularity and maintainability.

Microservices-Oriented (Conceptual)

While not necessarily deployed as separate microservices, the components are designed with clear boundaries, allowing for potential future decomposition into independent services if scalability demands it. This aligns with principles like Domain-Driven Design (DDD).

API-First Design

The interaction between layers, particularly between the MCP Server and the Scanning Core, is defined by clear APIs. This allows for independent development and testing of components.

Asynchronous Processing

For potentially long-running scanning tasks, asynchronous processing patterns are employed to prevent blocking the MCP server and ensure responsiveness to clients. This is crucial for handling multiple concurrent requests efficiently.

Stateless Services (Where Possible)

Scanning services are designed to be stateless where feasible, meaning they don't retain session information between requests. This simplifies scaling and improves fault tolerance. Any required state is managed by the Session Management component or persisted in external data stores.

Security by Design

Security considerations are integrated throughout the architecture:

• Input Validation: Rigorous validation of all incoming data at the MCP Interface (using Zod schemas) and at each service boundary.

• Least Privilege: Components operate with the minimum necessary permissions.

• Secure Communication: Use of HTTPS/TLS for external communication and secure internal channels where appropriate.

• Data Protection: Measures to protect sensitive data, such as scan results or user information, both in transit and at rest.

Observability

The system incorporates comprehensive logging, metrics collection, and tracing capabilities (via the Logging & Monitoring component) to ensure operational visibility and facilitate troubleshooting. This aligns with the principles of observability in modern distributed systems.

Extensibility

The architecture is designed to easily accommodate new scanning tools or services. The Tool Dispatcher can be updated to route requests to new services, and new services can be added to the Scanning Core without impacting existing functionality.

Technology Stack (Illustrative)

While the specific technology choices can evolve, a typical stack might include:

• Programming Language: TypeScript/Node.js for the MCP server and scanning services, leveraging its asynchronous capabilities and rich ecosystem.

• MCP Library: fastmcp for implementing the MCP server.

• Web Framework: Express.js or Fastify for handling HTTP-based communication (e.g., SSE).

• Data Validation: Zod for schema definition and validation.

• Containerization: Docker for packaging and deploying components.

• Orchestration: Kubernetes (if deployed as microservices).

• Logging: Winston or Pino.

• Monitoring: Prometheus, Grafana.

Data Flow Example: URL Scan

1. An LLM client sends an MCP tool_call request for scan_url to the SigilAI MCP Server's MCP Interface.

2. The MCP Interface validates the request and passes it to the Tool Dispatcher.

3. The Tool Dispatcher identifies the scan_url tool and routes the request to the URL Scanning Service.

4. The URL Scanning Service performs its analysis, potentially querying external Security Databases.

5. The URL Scanning Service returns the structured result to the Tool Dispatcher.

6. The Tool Dispatcher forwards the result to the MCP Interface.

7. The MCP Interface sends the MCP tool_result back to the LLM client.

Scalability and Reliability Considerations

• Horizontal Scaling: The MCP Server and Scanning Services can be scaled horizontally by running multiple instances behind a load balancer.

• Fault Tolerance: Redundancy can be built in at various levels. If one instance of a scanning service fails, requests can be routed to healthy instances.

• Resilience: Use of patterns like circuit breakers when interacting with external dependencies to prevent cascading failures.

• Database Scalability: Choice of scalable database solutions for persisting data.

This system overview provides a foundational understanding of the SigilAI MCP server's architecture. Subsequent documents in this section will delve deeper into specific architectural aspects.

---

Next: MCP Integration