multi-service mcp tool registry with dynamic tier-based loading
Exposes 90+ tools across 12 Google Workspace services (Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Chat, Custom Search, Contacts, Apps Script) through a unified MCP protocol interface. Uses a ToolTierLoader system (core/tool_tier_loader.py) that dynamically imports tool modules based on CLI-specified tiers (core/extended/complete), allowing selective API exposure to manage quota consumption and complexity. Tools are registered in a dictionary mapping (main.py 176-187) and loaded at server startup, with each service module implementing standardized tool patterns for consistent MCP schema generation.
Unique: Implements a three-tier tool loading system (core/extended/complete) via ToolTierLoader that allows fine-grained control over API surface exposure at server startup, preventing quota exhaustion in multi-user deployments. Most MCP servers expose all tools statically; this design enables quota-aware selective loading without code changes.
vs alternatives: Provides more granular quota control than generic MCP servers like Anthropic's MCP implementations, which typically expose all available tools without tier-based filtering.
oauth 2.0/2.1 session-based authentication with credential persistence
Implements dual OAuth authentication modes (OAuth 2.0 legacy flow and OAuth 2.1 with session management) via service authentication decorators that inject credentials into tool execution contexts. Credentials are stored persistently (location configurable via storage backend) and session context is maintained across tool calls, eliminating per-call re-authentication. The authentication system (core/auth.py) handles token refresh, expiration, and multi-user credential isolation in cloud deployments. Single-user mode (--single-user flag) uses local credential storage; multi-user mode requires external session storage (Redis, database) for credential isolation.
Unique: Supports both OAuth 2.0 legacy and OAuth 2.1 flows with automatic session context injection via service authentication decorators, enabling credential reuse across tool calls without explicit token passing. Includes configurable storage backends for multi-user credential isolation, distinguishing it from single-user-only MCP implementations.
vs alternatives: Provides multi-user credential isolation that generic MCP servers lack, and supports OAuth 2.1 (modern standard) alongside legacy OAuth 2.0, making it suitable for both legacy and modern Google Workspace deployments.
google chat message sending and conversation management
Provides 6+ Chat tools for sending messages to spaces and direct messages, retrieving conversation history, and managing chat spaces. Tools support message formatting (bold, italic, links) and file attachments. Chat operations include creating spaces, adding members, and retrieving message threads. The Chat module (tools/chat.py) handles message threading and implements pagination for conversation history. Supports both direct messages (DM) and space-based conversations.
Unique: Implements message threading and space-based conversation management with support for both direct messages and group spaces. Includes message formatting and attachment support with pagination for conversation history.
vs alternatives: Supports both direct messages and space-based conversations that many chat tools limit to one or the other; integrates with Google Workspace for unified team communication.
http server deployment with stdio and streamable-http transport modes
Implements dual transport modes for MCP server deployment: stdio (for local/desktop use) and streamable-http (for cloud/multi-user deployments). The SecureFastMCP class (core/server.py) extends FastMCP and configures transport based on CLI flag (--transport). Stdio mode pipes JSON-RPC requests/responses through standard input/output for Claude Desktop integration. Streamable-http mode exposes an HTTP server (configurable port) for remote client connections. Both modes support the same MCP protocol and tool registry. The server initialization (main.py) handles transport selection and startup.
Unique: Supports dual transport modes (stdio and streamable-http) from a single codebase, enabling both local desktop and cloud deployments without code changes. Uses FastMCP's transport abstraction to handle protocol differences transparently.
vs alternatives: More flexible than single-transport MCP servers; supports both local (Claude Desktop) and cloud (HTTP) deployments, making it suitable for diverse deployment scenarios.
error handling and retry logic with exponential backoff for api quota limits
Implements automatic retry logic with exponential backoff for transient API failures (rate limits, quota exhaustion, temporary service unavailability). The error handling system (core/error_handling.py or integrated in tool modules) detects quota-related errors from Google APIs and automatically retries with increasing delays (1s, 2s, 4s, 8s, etc.). Maximum retry attempts are configurable (default 3). Non-transient errors (authentication failures, invalid parameters) fail immediately without retry. Retry metadata is included in error responses to inform clients of retry attempts.
Unique: Implements exponential backoff retry logic specifically tuned for Google API quota limits (429 status codes), with configurable max attempts and automatic detection of transient vs permanent errors. Includes retry metadata in responses for observability.
vs alternatives: More sophisticated than simple retry loops; uses exponential backoff to reduce load during quota exhaustion and distinguishes transient from permanent errors to avoid wasted retries.
custom search integration for web search and result ranking
Exposes 2+ Custom Search tools that integrate with Google Custom Search Engine (CSE) for web search and result ranking. Tools support search queries with optional filters (site:, filetype:) and return ranked results with metadata (title, URL, snippet, rank). The Custom Search module (tools/custom_search.py) uses the Custom Search API for server-side query execution and result ranking. Results are limited to top 10 by default (configurable). Supports both web search and image search modes.
Unique: Integrates Google Custom Search Engine (CSE) for web search with result ranking and snippet extraction. Supports site: and filetype: filters for targeted searches. Limited to top 10 results but provides high-quality ranked results.
vs alternatives: Uses Google's Custom Search Engine for high-quality ranked results compared to generic web search APIs; supports domain-specific and file-type filtering for targeted searches.
google contacts directory access and contact metadata retrieval
Provides 4+ Contacts tools for retrieving contact information from Google Contacts directory, including name, email, phone, and organization metadata. Tools support contact search by name or email and batch retrieval of contact lists. The Contacts module (tools/contacts.py) uses the People API to access contact data with structured metadata extraction. Supports filtering by contact group (personal, work, etc.). Contact creation and editing are not supported (read-only access).
Unique: Provides read-only access to Google Contacts directory via the People API with structured metadata extraction (name, email, phone, organization, title). Supports contact search by name/email and filtering by contact group.
vs alternatives: Integrates with Google Contacts for unified contact management; provides structured metadata extraction that generic contact tools may not expose.
google apps script execution and deployment management
Exposes 3+ Apps Script tools for executing Apps Script functions and managing script deployments. Tools support function execution with parameters and return value retrieval. The Apps Script module (tools/apps_script.py) uses the Apps Script API to execute scripts and retrieve execution results. Supports both synchronous and asynchronous function execution. Script deployments can be listed and managed. Execution errors are captured and returned with stack traces.
Unique: Integrates Google Apps Script API for executing custom business logic functions, enabling extension of Google Workspace capabilities with custom automation. Supports both synchronous and asynchronous execution with error capture.
vs alternatives: Enables custom business logic integration that generic Google Workspace tools cannot provide; allows reuse of existing Apps Script automation with AI agents.
+8 more capabilities