MCP Server Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Arclio MCP Tooling project implements a standardized Model Context Protocol (MCP) server architecture designed to expose external services—such as Google Workspace, AWS S3, and Weaviate—to AI assistants. Each package within the monorepo functions as a discrete MCP server that provides a secure bridge between AI models and enterprise systems, ensuring that sensitive credentials remain isolated on the server side while providing a uniform interface for tool discovery and execution.
Sources: README.md, packages/google-workspace-mcp/README.md:88-94, packages/aws-s3-mcp/README.md:43-50
Core System Components
The architecture follows a modular pattern where individual packages implement specific service integrations. Each server is built using the FastMCP framework, which handles the protocol layer, while the business logic is distributed across service-specific modules.
Component Breakdown
| Component | Description |
|---|---|
| MCP Hub/Inspector | The client-side interface (e.g., MCP Inspector) that connects to and interacts with the server. |
| FastMCP Application | The central application instance (e.g., app.py) that registers and manages tools, resources, and prompts. |
| Service Layer | Modules that interact directly with external APIs (Google, AWS, Weaviate) and handle authentication. |
| Tool Definitions | Discrete functions decorated with @mcp.tool that define the AI-callable interface and schema. |
| Resource Definitions | Data access points decorated with @mcp.resource providing read-only access to system data. |
Sources: packages/google-workspace-mcp/README.md:281-300, packages/aws-s3-mcp/README.md:58-60
Request Execution Flow
The execution flow within an MCP server involves the discovery of capabilities followed by the execution of specific handlers. When a tool is called, the FastMCP server routes the request through a validation layer before invoking the underlying service logic.
Server Lifecycle and Call Sequence
This diagram illustrates how an MCP Hub interacts with the server to discover and execute tools.
Implementation Patterns
Package Structure
Each MCP package in the monorepo adheres to a standardized internal layout to ensure consistency and maintainability across different integrations.
In the aws-s3-mcp package, the __main__.py file serves as the entry point, initializing logging and running the mcp.run() loop which listens for commands over standard input/output (stdio).
Sources: packages/google-workspace-mcp/README.md:281-300, packages/aws-s3-mcp/src/aws_s3_mcp/main.py:1-41
Tool Registration
Tools are registered using decorators that define the metadata required for AI models to understand how to use them. For example, in the Weaviate integration, a complete workflow involves creating a collection, inserting data, and performing a vector search, all coordinated through these tool handlers.
# Conceptual example of tool registration based on project patterns
@mcp.tool(
name="service_action",
description="Action description for the AI model"
)
async def tool_handler(param1: str) -> dict:
service = ServiceClass()
return await service.perform_action(param1)
Sources: packages/google-workspace-mcp/README.md:354-380, tests/weaviate-mcp/integration/test_mcp_tools_integration.py:48-95
Service Integrations
The architecture currently supports three primary types of integrations, each managed as an independent MCP server within the packages/ directory.
Integration Summary
| Integration | Core Functionality | Primary Technologies |
|---|---|---|
| Google Workspace | Drive, Docs, Gmail, Calendar, Sheets, Slides | google-api-python-client, markdowndeck |
| AWS S3 | Object listing, content retrieval, text/binary detection | aioboto3 |
| Weaviate | Vector search, hybrid search, collection CRUD | weaviate-client, OpenAI Embeddings |
Sources: packages/google-workspace-mcp/README.md:144-279, packages/aws-s3-mcp/README.md:148-154, packages/weaviate-mcp/README.md:152-168
Conclusion
The MCP Server Architecture in this project provides a scalable and secure framework for extending AI assistant capabilities. By decoupling the protocol management (FastMCP) from the service-specific logic and utilizing a standardized monorepo structure, the system allows for the rapid development of new integrations while maintaining high security and performance standards across diverse cloud and database services.