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_*)

Manage 19+ native connectors with OAuth integration

Fine-grained tool enable/disable per connector

Built-in MCP protocol testing with WebSocket and HTTP support

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

Code & Version Control
Project Management
Communication
Email
Documents & Productivity
AI Coding Tool Intelligence

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

• 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.

• Docker and Docker Compose
• Python 3.11+ (for local development)
• PostgreSQL or Supabase account

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

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

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

# 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

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"
      }
    }
  }
}

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

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:

# Backend tests
make test-backend

# Frontend tests
make test-frontend

# All tests with coverage
make test-coverage

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

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.

make up

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

• 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.

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

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

• Project Link: https://github.com/mvmcode/SageMCP
• Discord Community: https://discord.gg/f5RrQ6aGCS

• Model Context Protocol
• FastAPI
• Claude Desktop
• Best-README-Template