Open Source MCP Gateway for Organizations

Register, govern, and expose your MCP services to your teams — with full control over who sees what.

Quick Start • Why BigMCP • Features • API Docs • Contributing

---

Quick Start

git clone https://github.com/bigfatdot/bigmcp.git
cd bigmcp
cp .env.example .env
# Edit .env with your secrets (SECRET_KEY, ENCRYPTION_KEY)
docker compose up -d
docker compose exec backend alembic upgrade head

Open http://localhost:3000 — the first user to register becomes instance admin.

Want to try it first? bigmcp.cloud is a free demo platform.

Connect Claude Desktop

{
  "mcpServers": {
    "bigmcp": {
      "url": "https://your-domain.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

---

Why BigMCP

BigMCP is the control plane for all your MCP servers — the 180+ from the marketplace AND your own custom servers.

Without BigMCP	With BigMCP
Install MCP servers on each device	One endpoint — access all tools
Configure credentials separately	Centralized credentials — User + Org + Server
No access control	RBAC — Owner, Admin, Member, Viewer
No visibility into usage	Audit logs — who used what, when
Manual setup per team	Tool Groups + API Keys — selective service exposure

For Organizations

The core use case: register your internal MCP servers, create Tool Groups per team, generate scoped API Keys, and let each team member connect their AI client with a single URL.

1. Register your servers — npm, pip, Docker, HTTP, or local binary
2. Auto-discover tools — BigMCP calls tools/list and indexes everything
3. Create Tool Groups — "Dev Team" gets GitHub + CI/CD, "Finance" gets Grist + DB queries
4. Generate API Keys — scoped per Tool Group, with granular permissions
5. Connect — each user pastes one URL in Claude/Cursor and sees only their tools

---

Features

Custom MCP Server Management

• Register servers from any source: npm, pip, GitHub, Docker, HTTP URL, local binary
• Auto-discovery via tools/list — tools are indexed automatically
• Mode closed available: disable marketplace entirely, use only your own servers
• Team vs Personal servers with granular visibility

Selective Service Exposure

• Tool Groups — curated sets of tools with PRIVATE / ORGANIZATION / PUBLIC visibility
• Scoped API Keys — 7 granular scopes (tools:read, tools:execute, credentials:read/write, servers:read/write, admin)
• Per-Tool Group API Keys — each key only exposes the tools you choose
• Usage tracking — per tool, per server, per key

Authentication & Security

• OAuth 2.0 + PKCE (RFC 7636) with Dynamic Client Registration
• JWT tokens with configurable expiration
• API Keys for programmatic access (bcrypt hashed, bigmcp_sk_* format)
• MFA / TOTP two-factor authentication
• Credentials encrypted at rest (Fernet)
• Immutable audit logs with HMAC-SHA256 signatures

Multi-Tenant Architecture

• Organization-based isolation with RBAC
• 4-tier roles: Owner, Admin, Member, Viewer
• Hierarchical credentials: User > Organization > Server
• Unlimited users and organizations

Dynamic Marketplace

• 180+ MCP servers from npm, GitHub, Glama.ai, Smithery.ai
• Semantic search with vector embeddings
• One-click installation with credential detection
• Marketplace can be fully disabled for closed environments

AI Orchestration

• Intent analysis — Natural language to workflow
• Auto-workflow generation — "Sync Grist to Sheets daily"
• Composition store with lifecycle (temporary to production)

MCP Protocol Compliance

• MCP 2025-03-26 — Streamable HTTP + SSE
• OAuth 2.0 authorization for MCP clients
• Works with Claude Desktop, Cursor, Continue.dev, Cline, and any MCP-compatible client

---

Architecture

+-----------------------------------------------------------------+
|                      CLIENT INTERFACES                           |
+------------------+-----------------+-----------------------------+
|  MCP Protocol    |   REST API v1   |    OAuth 2.0 Clients        |
|  (SSE/JSON-RPC)  |     (JSON)      |  (Claude Desktop, etc.)     |
+--------+---------+--------+--------+--------------+--------------+
         |                  |                       |
         +------------------+-----------------------+
                            v
+-----------------------------------------------------------------+
|                   GATEWAY LAYER (FastAPI)                         |
|  Authentication - Authorization - Rate Limiting - Routing        |
+-----------------------------------------------------------------+
                            |
                            v
+-----------------------------------------------------------------+
|                  ORCHESTRATION LAYER                              |
|  Semantic Search - Intent Analysis - Workflow Composition         |
|  Credential Resolution - Permission Checks                       |
+-----------------------------------------------------------------+
                            |
                            v
+-----------------------------------------------------------------+
|                 REGISTRY & MARKETPLACE                            |
|  Tool Catalog - User Server Pools - Health Monitoring             |
+-----------------------------------------------------------------+
                            |
                            v
+-----------------------------------------------------------------+
|                    MCP SERVERS                                    |
|  your-custom-api | github-mcp | notion-mcp | [marketplace]       |
+-----------------------------------------------------------------+
                            |
                            v
+-----------------------------------------------------------------+
|                    DATABASE LAYER                                 |
|  PostgreSQL 16 - Redis 7 - Qdrant                                |
+-----------------------------------------------------------------+

---

Self-Hosted Deployment

Requirements

• Docker & Docker Compose
• 2GB RAM minimum
• PostgreSQL 16 (included in compose)

Production Deploy

# 1. Clone
git clone https://github.com/bigfatdot/bigmcp.git
cd bigmcp

# 2. Configure
cp .env.example .env
# Generate secrets:
python3 -c "import secrets; print(secrets.token_urlsafe(32))"       # SECRET_KEY
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"  # ENCRYPTION_KEY

# 3. Start
docker compose up -d

# 4. Initialize database
docker compose exec backend alembic upgrade head

# 5. Access at http://localhost:3000

Environment Variables

# Required
SECRET_KEY=your-secret-key-min-32-chars
ENCRYPTION_KEY=your-fernet-key
DATABASE_URL=postgresql+asyncpg://mcphub:mcphub@postgres:5432/mcphub

# Optional — LLM for AI orchestration
LLM_API_URL=https://api.mistral.ai/v1
LLM_API_KEY=your-api-key
LLM_MODEL=mistral-small-latest

# Optional — SMTP for email invitations
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email
SMTP_PASSWORD=your-password

Monitoring

• GET /health — Liveness probe
• GET /ready — Readiness probe (DB + registry + cache)
• GET /metrics — Prometheus endpoint

---

Technology Stack

Layer	Technologies
Backend	FastAPI, Python 3.11+, SQLAlchemy 2.0, Alembic
Database	PostgreSQL 16, Redis 7, Qdrant
Security	JWT, bcrypt, Fernet encryption, OAuth 2.0 + PKCE, MFA/TOTP
Frontend	React 18, TypeScript, Tailwind CSS, Vite
Infrastructure	Docker Compose, Uvicorn, Nginx
Monitoring	Prometheus metrics
Protocols	MCP 2025-03-26, SSE, JSON-RPC 2.0

---

Documentation

Resource	Description
API Reference	Swagger/OpenAPI (also at /docs on your instance)
Changelog	Version history
Contributing	How to contribute
Licensing	AGPLv3 license details
Deploy Guide	Production VPS deployment

---

Contributing

We welcome contributions! See CONTRIBUTING.md.

# Development setup
cd mcp-registry
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt

# Run tests
pytest tests/ -v

# Start dev server
uvicorn app.main:app --reload --port 8001

---

License

BigMCP is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

All features are included. No user limits. No license keys.

See LICENSING.md for details.

---

Support

Channel	Description
GitHub Issues	Bug reports & feature requests
Documentation	Guides and API reference
Email	General inquiries

---

BigMCP — Open Source MCP Gateway for Organizations
_{Made with care for the MCP community by BigFatDot}