sagemcp/sagemcp

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

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 

# Interactive REPL
sagemcp mcp interactive my-tenant 

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

---