Epyatis MCP Central

Enterprise-Grade Model Context Protocol (MCP) Gateway, Reverse Proxy, and Multi-Tenant Tool Aggregation Hub.

Epyatis MCP Central provides a robust orchestration layer that bridges autonomous AI agent platforms (such as Paperclip, Claude Desktop, Cursor, Codex, and custom LLM agents) with heterogeneous enterprise data sources and execution environments.

Instead of configuring dozens of individual MCP servers on each agent workstation or container, MCP Central aggregates multiple upstream servers (local stdio subprocesses, remote SSE microservices, and dynamic OpenAPI/REST specifications) into logical, scoped, and token-authenticated endpoints.

Table of Contents

• Key Problem Solved

• System Architecture

• Core Capabilities

• Directory Structure

• Getting Started

  • Prerequisites

  • Installation & Local Setup

  • Environment Configuration

  • Running the Gateway

• Connecting AI Agents

  • Paperclip Connection

  • Claude Desktop / Cursor Configuration

• Upstream Integrations Guide

  • Google Drive Workspace

  • Periskope WhatsApp

  • Dynamic OpenAPI / Swagger Translation

  • Secure Local Filesystem

• Multi-User Governance & RBAC Scoping

• Security & Hardening Architecture

• API Reference Summary

• Testing & Quality Assurance

• Contributing

• License

Related MCP server: mcp-gw

Key Problem Solved

Modern AI agent deployments face severe operational hurdles:

1. Tool Sprawl & Context Overload: Exposing hundreds of raw tools directly to LLMs degrades reasoning performance and balloons token overhead.

2. Scattered Authentication & Secret Leakage: Managing OAuth credentials, database passwords, and API keys across disparate agent configurations introduces critical security vulnerabilities.

3. Lack of Governance & Observability: Enterprises lack centralized audit trails detailing which agent invoked which tool, with what arguments, and what the execution latency was.

4. Heterogeneous Protocols: AI agents must interface with stdio subprocesses, remote HTTP/SSE streaming servers, and legacy REST APIs simultaneously.

Epyatis MCP Central solves these challenges by establishing a single point of control, telemetry, sandboxing, and policy enforcement.

System Architecture

flowchart TD
    subgraph Clients["AI Agent Ecosystem"]
        A1["Paperclip Agent Runtime"]
        A2["Claude Desktop / Cursor"]
        A3["Custom LangChain / AutoGen Agents"]
    end

    subgraph Central["Epyatis MCP Central (Port 8000)"]
        subgraph Ingress["Ingress & Security Perimeter"]
            EP["/mcp/{instance_slug}/sse"]
            AUTH["Token Auth & Active User Scoping"]
            SSRF["Anti-SSRF & Network Boundary Filter"]
        end

        subgraph Core["Gateway Kernel"]
            GW["Instance Gateway Manager"]
            MAP["Operational Data-Sources Map Engine"]
            TOGGLE["Granular Tool Allowlist / Runtime Toggles"]
            AUDIT["Structured Audit Logger & Millisecond Telemetry"]
        end

        subgraph Storage["Persistent State Layer (central.db)"]
            SQLITE[("SQLite 3 (WAL Mode)")]
            FERNET["AES-128-CBC / SHA-256 Fernet Encryption"]
        end

        subgraph UI["Management Plane"]
            DASH["Tailwind + Alpine.js Web Console (Port 8000)"]
            REST["Admin REST API (/api/v1/*)"]
        end
    end

    subgraph Upstreams["Upstream Tool Execution Providers"]
        U1["Stdio Subprocesses (e.g., Google Drive MCP)"]
        U2["Remote SSE Microservices (e.g., Periskope WhatsApp)"]
        U3["Dynamic OpenAPI Engine (REST-to-MCP Synthesis)"]
        U4["Internal System Tools (central__ping, data_sources_map)"]
    end

    Clients -->|Server-Sent Events + JSON-RPC 2.0| Ingress
    Ingress --> Core
    Core --> Storage
    Core --> Upstreams
    REST --> Core
    DASH --> REST

Core Capabilities

Directory Structure

.
├── config/
│   └── bootstrap_instances.yaml    # Declarative startup configuration for instances & connections
├── scripts/
│   └── get_gdrive_refresh_token.py # Standalone OAuth2 helper for full Google Drive scopes
├── src/
│   └── central/
│       ├── api/
│       │   ├── __init__.py
│       │   └── routes.py           # REST endpoints for UI, connections, templates, and kits
│       ├── db/
│       │   ├── __init__.py
│       │   ├── entities.py         # SQLAlchemy 2.0 models (User, Connection, Instance, AuditLog)
│       │   ├── repository.py       # Query abstractions and visibility-filtered CRUD
│       │   ├── seeder.py           # Database bootstrap migrations and seed data
│       │   └── session.py          # SQLite engine configuration (WAL mode & thread isolation)
│       ├── gateway/
│       │   ├── __init__.py
│       │   ├── instance_gateway.py # Low-level JSON-RPC routing & tool execution dispatcher
│       │   └── manager.py          # Lifecycle manager for active MCP instances
│       ├── security/
│       │   ├── __init__.py
│       │   ├── auth.py             # RBAC authentication and visibility validation
│       │   ├── crypto.py           # Fernet encryption / decryption helpers
│       │   ├── ssrf.py             # Anti-SSRF URL and network address validation
│       │   └── validation.py       # Shell command injection and path containment validators
│       ├── templates_catalog/
│       │   ├── __init__.py
│       │   └── registry.py         # Built-in template definitions
│       ├── ui/
│       │   ├── __init__.py
│       │   └── dashboard.py        # Single-page Alpine.js + Tailwind administrative interface
│       ├── upstreams/
│       │   ├── __init__.py
│       │   ├── base.py             # Upstream driver interface
│       │   ├── internal.py         # Gateway-level built-in MCP tools
│       │   ├── openapi_upstream.py # Dynamic REST-to-MCP translation driver
│       │   ├── remote_sse_upstream.py # Remote SSE MCP client driver
│       │   └── stdio_upstream.py   # Subprocess stdio MCP client driver
│       ├── config.py               # Pydantic Settings application configuration
│       ├── main.py                 # CLI entry point
│       ├── models.py               # API request and response validation schemas
│       └── server.py               # FastAPI application setup and middleware
├── tests/
│   ├── test_bootstrap.py
│   ├── test_phase1.py
│   ├── test_phase2.py
│   ├── test_phase3_multiuser_visibility.py
│   ├── test_qa_e2e_buttons.py
│   └── test_security_hardening.py
├── .env.example
├── .gitignore
├── CONTRIBUTING.md
├── pyproject.toml
└── requirements.txt

Getting Started

Prerequisites

• Python 3.11+ installed.

• Node.js 18+ (recommended for npx-based Stdio connectors).

• Git.

Installation & Local Setup

1. Clone the repository:

   git clone https://github.com/Scheuer12/epyatis-mcp-central.git
   cd epyatis-mcp-central

2. Create and activate a virtual environment:

   # Linux / macOS
   python3 -m venv .venv
   source .venv/bin/activate
   
   # Windows PowerShell
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1

3. Install dependencies:

   pip install -e .

Environment Configuration

Copy the example environment configuration:

cp .env.example .env

Edit .env to configure your master keys and upstream credentials:

# Core Gateway Settings
CENTRAL_HOST=127.0.0.1
CENTRAL_PORT=8000
CENTRAL_SECRET_KEY=generate-a-32-byte-base64-key-here
CENTRAL_ADMIN_KEY=your-secure-admin-api-key

# Upstream Integrations (Optional)
PERISKOPE_API_KEY=your_periskope_api_token
PERISKOPE_MCP_URL=https://api.periskope.app/mcp

Security Note: You can generate a strong encryption key using Python:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Running the Gateway

Start the production-ready ASGI server:

python -m central.main

Or run with automatic reload during development:

uvicorn central.server:app --reload --host 127.0.0.1 --port 8000

Once running, access the web dashboard: 👉 http://127.0.0.1:8000/

Connecting AI Agents

Paperclip Connection

In the Paperclip agent administration console:

1. Navigate to Connectors -> Add New Connector.

2. Connector Type: MCP Server (SSE).

3. Endpoint URL:

   http://127.0.0.1:8000/mcp/horst-suite/sse?token=epy_dev_token_123

4. Save the connector. Paperclip will immediately discover all allowed tools aggregated by that instance.

Claude Desktop / Cursor Configuration

Add the SSE endpoint to your claude_desktop_config.json:

{
  "mcpServers": {
    "epyatis-central": {
      "url": "http://127.0.0.1:8000/mcp/horst-suite/sse?token=epy_dev_token_123"
    }
  }
}

Upstream Integrations Guide

1. Google Drive Workspace

MCP Central integrates with Google Drive using the @us-all/google-drive-mcp or @modelcontextprotocol/server-gdrive servers.

To authorize full read and write access:

1. Obtain OAuth 2.0 Client credentials from the Google Cloud Console (Application type: Desktop App).

2. Save the downloaded JSON as gdrive-oauth.keys.json in the project root.

3. Run the automated OAuth helper:

   python scripts/get_gdrive_refresh_token.py

4. Complete the browser authentication prompt. The script automatically updates .env with the necessary tokens and full read/write scopes.

2. Periskope WhatsApp

Configure your Periskope API token in .env. When active, Periskope tools will be exposed under the periskope__ namespace (e.g., periskope__list_chats, periskope__send_message).

3. Dynamic OpenAPI / Swagger Translation

Connect any REST API with an OpenAPI 3.0+ specification:

1. Open the Central dashboard and navigate to Connection Templates -> REST API (OpenAPI / Swagger).

2. Provide the OpenAPI specification URL (or paste raw JSON/YAML) and your authentication header.

3. MCP Central validates the schema and synthesizes distinct MCP tools for each endpoint and HTTP method with full type validation.

4. Secure Local Filesystem

Create sandboxed filesystem connections with strict directory containment:

1. Select the Filesystem Local Seguro template in the dashboard.

2. Specify the allowed_dir path. MCP Central enforces path boundary checks to prevent directory traversal attacks outside the designated root.

Multi-User Governance & RBAC Scoping

Epyatis MCP Central provides comprehensive user isolation and session management:

• User Roles:

  • epy_root: Master Administrator. Holds elevated privileges to configure global settings, inspect audit logs across all instances, and publish shared assets to public visibility.

  • Standard User: Can create private connections, custom templates, and instances.

• Visibility Levels:

  • private: Accessible only to the creator user.

  • shared: Accessible to all authenticated users in the organization.

  • public: Accessible publicly across instances. Strict Enforcement: Only a Master Admin (epy_root) can set any asset to public. Any attempt by standard users to publish an asset as public returns 403 Forbidden.

Security & Hardening Architecture

1. Anti-SSRF Protection: External URL targets are verified against non-routable, link-local, loopback, and private IPv4/IPv6 ranges before any HTTP client initiates requests.

2. Encrypted Persistence: All sensitive credentials stored in SQLite are encrypted at rest using AES-128-CBC with SHA-256 HMAC authentication via the Fernet standard.

3. Execution Sandboxing: Subprocess commands for stdio upstreams pass through command-injection validation routines that disallow shell metacharacters and unvalidated piping.

4. Token Isolation: Each instance issues independent bearer tokens. Compromising one agent token does not provide access to other configured instances.

API Reference Summary

Testing & Quality Assurance

The codebase includes an extensive suite of automated tests covering unit logic, integration flows, security boundaries, and regression verification:

# Run all tests with verbose output
pytest -v

# Run security hardening tests specifically
pytest -v tests/test_security_hardening.py

# Run multi-user visibility and RBAC governance tests
pytest -v tests/test_phase3_multiuser_visibility.py

Contributing

We welcome community contributions, bug reports, and enhancements. Please review CONTRIBUTING.md for coding conventions, security guidelines, and the pull request submission process.

License

This project is licensed under the MIT License.