Sage MCP

About The Project

Sage MCP is a production-ready platform that enables you to run multiple isolated MCP servers with built-in OAuth/API key authentication for 23+ services. It provides a web interface and CLI for managing tenants and connectors, making it easy to integrate Claude Desktop with various external services.

Key Features:

• Multi-tenant architecture with path-based isolation

• Full MCP protocol support (Streamable HTTP, WebSocket, SSE) with protocol version negotiation

• Server pooling with LRU eviction (5,000 max instances, 30-min TTL)

• Session management via Mcp-Session-Id with resumable SSE streams

• Token-bucket rate limiting (configurable RPM per tenant)

• External MCP server hosting via stdio subprocess (GenericMCPConnector)

• OAuth 2.0 integration with tenant-level and user-level tokens

• Field-level encryption at rest (Fernet/AES) and API key authentication

• Prometheus metrics, structured JSON logging, and Kubernetes health probes

• Progressive rollout via feature flags (SAGEMCP_ENABLE_*)

Screenshots

Supported Connectors

340 tools across 23 native connectors, plus unlimited external MCP server support.

Architecture

High-Level System Architecture

graph TB
    subgraph Client["Client Layer"]
        CD[Claude Desktop]
        WEB[Web Browser]
    end

    subgraph Platform["SageMCP Platform"]
        subgraph Frontend["Frontend :3001"]
            UI[React UI]
        end

        subgraph Backend["Backend :8000"]
            subgraph Middleware["Middleware"]
                RL["Rate Limiter
                Token Bucket"]
                CORS_MW["CORS / Origin
                Validation"]
                CT["Content-Type
                Validation"]
            end

            API[FastAPI Admin API]

            subgraph MCPCore["MCP Core"]
                POOL["ServerPool
                LRU · 5000 max"]
                SESS["SessionManager
                Mcp-Session-Id"]
                TRANSPORT["Transport
                HTTP POST · WS · SSE"]
                EBUF["EventBuffer
                Resumable Streams"]
            end

            subgraph Connectors["Connectors"]
                NATIVE["Native Plugins
                GitHub · GitLab · Bitbucket
                Jira · Linear · Confluence
                Slack · Discord · Teams
                Gmail · Outlook
                Google Docs · Sheets · Slides
                Notion · Zoom
                Excel · PowerPoint"]
                EXT_MCP["External MCP Servers
                via ProcessManager + stdio"]
            end

            subgraph Observability["Observability"]
                PROM["Prometheus /metrics"]
                LOGS["Structured JSON Logs"]
                HEALTH["Health Probes
                /health/live · ready · startup"]
            end
        end

        subgraph Database["Database"]
            DB[("PostgreSQL /
            Supabase")]
        end
    end

    subgraph External["External Services"]
        EXT["GitHub · GitLab · Bitbucket
        Jira · Linear · Confluence
        Slack · Discord · Teams
        Gmail · Outlook · Google
        Notion · Zoom · Microsoft APIs"]
    end

    CD -->|"HTTP POST / WebSocket"| TRANSPORT
    WEB -->|HTTPS| UI
    UI -->|REST API| API
    TRANSPORT --> POOL
    POOL --> SESS
    SESS --> Connectors
    NATIVE -->|OAuth| EXT
    EXT_MCP -->|stdio| EXT
    API -->|ORM| DB

    style CD fill:#e1f5ff
    style WEB fill:#e1f5ff
    style UI fill:#fff3e0
    style API fill:#f3e5f5
    style POOL fill:#e8f5e9
    style SESS fill:#e8f5e9
    style TRANSPORT fill:#e8f5e9
    style EBUF fill:#e8f5e9
    style NATIVE fill:#e8f5e9
    style EXT_MCP fill:#e8f5e9
    style DB fill:#fce4ec
    style EXT fill:#e0f2f1
    style RL fill:#fff9c4
    style CORS_MW fill:#fff9c4
    style CT fill:#fff9c4
    style PROM fill:#f3e5f5

View Full Architecture Documentation | Includes 10+ detailed diagrams covering OAuth flows, multi-tenancy, database schema, deployment, and more.

Built With

Security

• Encryption at rest -- All OAuth tokens, API keys, and connector credentials encrypted via Fernet (AES-128-CBC + HMAC), key derived from SECRET_KEY via PBKDF2-SHA256 (480K iterations).

• API key authentication -- Three scope tiers (platform_admin, tenant_admin, tenant_user) with bcrypt-hashed storage and SHA-256 LRU cache. Feature-flagged via SAGEMCP_ENABLE_AUTH.

• Transport security -- CORS origin validation, Content-Type enforcement, per-tenant token-bucket rate limiting.

Getting Started

Prerequisites

• Docker and Docker Compose

• Python 3.11+ (for local development)

• PostgreSQL or Supabase account

Installation

1. Clone the repository

   git clone https://github.com/mvmcode/SageMCP.git
   cd SageMCP

2. Setup environment

   cp .env.example .env
   # Edit .env with your OAuth credentials (optional for testing)

3. Start the platform

   make setup
   make up

4. Access the application

   • Frontend: http://localhost:3001

   • API: http://localhost:8000

   • API Docs: http://localhost:8000/docs

   • Metrics: http://localhost:8000/metrics (when SAGEMCP_ENABLE_METRICS=true)

   • Health: http://localhost:8000/health/live | /health/ready | /health/startup

Usage

Management Options

SageMCP provides two ways to manage your platform:

1. Web Interface - Visual interface at http://localhost:3001

2. Command-Line Interface (CLI) - Powerful CLI for automation and DevOps

Quick Start (Web Interface)

1. Open the web interface at http://localhost:3001

2. Create a new tenant

3. Add a connector (e.g., GitHub) and configure OAuth

4. Copy the MCP server URL for Claude Desktop

Quick Start (CLI)

# Install CLI
pip install -e ".[cli]"

# Initialize configuration
sagemcp init

# Create a tenant
sagemcp tenant create --slug my-tenant --name "My Tenant"

# Add a connector
sagemcp connector create my-tenant --type github --name "GitHub"

# Configure OAuth (opens browser)
sagemcp oauth authorize my-tenant github

# Test MCP tools
sagemcp mcp tools my-tenant <connector-id>

# Interactive REPL
sagemcp mcp interactive my-tenant <connector-id>

Full CLI Documentation | CLI Design Document

Claude Desktop Configuration

Add to your Claude Desktop config:

{
  "mcpServers": {
    "sage-mcp": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {
        "MCP_SERVER_URL": "ws://localhost:8000/api/v1/{tenant-slug}/mcp"
      }
    }
  }
}

User-Level OAuth Tokens

SageMCP supports per-user OAuth tokens in addition to tenant-level credentials. See User-Level OAuth Tokens for HTTP and WebSocket examples.

Feature Flags & Configuration

SageMCP uses feature flags for progressive rollout of v2 capabilities. All flags default to false and can be enabled via environment variables.

Additional configuration settings:

Development

Running Tests

# Backend tests
make test-backend

# Frontend tests
make test-frontend

# All tests with coverage
make test-coverage

Available Commands

make help            # Show all available commands
make build           # Build Docker images
make up              # Start all services
make down            # Stop all services
make logs            # View logs
make shell           # Open shell in app container
make clean           # Clean up containers and volumes

Adding New Connectors

1. Create a new connector class in src/sage_mcp/connectors/

2. Implement the BaseConnector interface

3. Register with @register_connector decorator

4. Add to the connector enum

See existing connectors in src/sage_mcp/connectors/ for examples.

Deployment

Docker Compose (Development)

make up

Kubernetes (Production)

Deploy with PostgreSQL:

helm install sage-mcp ./helm

Deploy with Supabase:

helm install sage-mcp ./helm \
  --set database.provider=supabase \
  --set postgresql.enabled=false \
  --set supabase.url=https://your-project.supabase.co \
  --set supabase.serviceRoleKey=your-service-role-key

Roadmap

• Tool policy language (per-connector tool enable/disable rules)

• OpenTelemetry tracing

• Redis-backed session persistence

See the open issues for a full list of proposed features and known issues.

Contributing

Contributions are what make the open source community amazing! Any contributions you make are greatly appreciated.

1. Fork the Project

2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

3. Commit your Changes (git commit -m 'Add some AmazingFeature')

4. Push to the Branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

Contact

• Project Link: https://github.com/mvmcode/SageMCP

• Discord Community: https://discord.gg/f5RrQ6aGCS

Acknowledgments

• Model Context Protocol

• FastAPI

• Claude Desktop

• Best-README-Template