Skip to content

MCP Server Overview

The CyberEco MCP (Model Context Protocol) server exposes the CyberEco Hub data layer to AI assistants. It enables tools like Claude, ChatGPT, and other MCP-compatible clients to query Firestore collections, check permissions, explore schemas, and access architecture documentation -- all through a standardized protocol.

What It Is

A Python MCP server built with the FastMCP framework and the uv toolchain. It wraps the CyberEco Hub's Firebase/Firestore backend and exposes it as structured tools, resources, and prompts that AI assistants can call directly.

AI Assistant  <-->  MCP Protocol  <-->  CyberEco MCP Server  <-->  Firestore
                                              |
                                              +--> Architecture docs (docs/*.md)
                                              +--> Collection schemas (12 collections)
                                              +--> Integration prompts (4 workflows)

Features

Category Count Description
Tools 7 CRUD operations, permission checks, schema exploration
Resources 22+ Architecture docs, collection schemas, collection list
Prompts 4 Integration guides, data model exploration, debugging workflows

Running the Server

cd mcp-server && uv run cybereco-mcp

uvx --from ./mcp-server cybereco-mcp

Directly with Python

python -m cybereco_mcp.server

Installation

Prerequisites

Tool Version Install
Python >= 3.12 python.org
uv Latest curl -LsSf https://astral.sh/uv/install.sh \| sh

Setup

cd mcp-server
uv sync          # Install dependencies into .venv
uv run cybereco-mcp   # Start the server

Configuration

Environment Variables

Variable Required Description
GOOGLE_APPLICATION_CREDENTIALS Yes* Path to Firebase service account JSON file
FIREBASE_SERVICE_ACCOUNT_KEY Yes* Inline JSON string of the service account key
MCP_ENABLE_WRITES No Set to true to enable write operations (default: disabled)

Authentication

At least one of GOOGLE_APPLICATION_CREDENTIALS or FIREBASE_SERVICE_ACCOUNT_KEY must be set to connect to Firestore. Without either, data layer tools will fail with an EnvironmentError.

Example: Claude Desktop Configuration

claude_desktop_config.json
{
  "mcpServers": {
    "cybereco": {
      "command": "uvx",
      "args": ["--from", "/path/to/cybereco-hub/mcp-server", "cybereco-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

Security

The MCP server implements multiple layers of security to protect data:

Write Protection

Write operations are disabled by default. To enable them, you must explicitly set the MCP_ENABLE_WRITES=true environment variable. This prevents accidental data modification when the server is used for read-only exploration.

Collection Whitelist

Only known collections can be queried. The server maintains a frozenset of allowed collection names (currently 12 collections). Any request targeting an unlisted collection is rejected with an error message listing the valid options.

Query Operator Validation

Filter operators are validated against a strict allowlist:

==  !=  <  <=  >  >=  in  array-contains

Any other operator is rejected before the query reaches Firestore.

Input Sanitization

All prompt parameters are sanitized through a shared sanitize() function that:

  • Strips leading/trailing whitespace
  • Caps string length (64-512 characters depending on the parameter)
  • Handles None values gracefully (returns empty string)

Thread-Safe Firestore Initialization

The Firestore client uses double-checked locking with threading.Lock to ensure thread-safe lazy initialization. This prevents race conditions when multiple tool calls arrive simultaneously during server startup.

Architecture

The server is organized into three module groups:

mcp-server/src/cybereco_mcp/
  server.py              # Entry point, creates FastMCP instance
  tools/
    data_layer.py        # get_document, query_collection, create_document
    permissions.py       # check_permission, list_user_permissions
    schema.py            # list_collections, describe_collection + COLLECTIONS dict
  resources/
    docs.py              # cybereco://docs/* resources (11 docs + CLAUDE.md)
    collections.py       # cybereco://schema/* + cybereco://collections
  prompts/
    onboarding.py        # integrate_new_app, explore_data_model
    debugging.py         # debug_data_issue, debug_permission_denied
    _sanitize.py         # Shared input sanitization

Next Steps