Private MCP Registry

A comprehensive Model Context Protocol (MCP) Server Registry with a modern TypeScript frontend and Python FastAPI backend. Discover, manage, and interact with MCP servers for various integrations including databases, caching, file systems, APIs, and AI/ML workloads.

� Why a Private MCP Registry?

Benefits of a Private Registry

Enterprise Control & Security 🔒

Full Control: Manage your own MCP servers without relying on external registries
Air-Gapped Deployments: Deploy in offline or restricted network environments
Security Compliance: Meet organizational security and compliance requirements
Proprietary Servers: Register internal/proprietary MCP servers not suitable for public registries
Access Control: Restrict server access to authorized users and teams

Organization & Discovery 📚

Centralized Hub: Single source of truth for all internal MCP servers
Team Collaboration: Enable teams to discover and use standardized integrations
Version Management: Track and manage multiple versions of MCP servers
Documentation: Maintain comprehensive metadata and configuration schemas
Governance: Enforce naming conventions and configuration standards

Performance & Reliability ⚡

Local Caching: Faster server discovery without external network calls
Zero Latency: Deploy registry close to applications
High Availability: Run multiple registry instances for redundancy
Offline Access: Access server metadata even during network outages
Reduced Dependencies: No external service dependencies

Cost Optimization 💰

No Subscription Fees: Own and operate your registry
Scalable Infrastructure: Use existing infrastructure
Bandwidth Savings: Eliminate external API calls
Audit Trail: Complete control over server usage and modifications

Standards Compliance ✅

This Private MCP Registry fully adheres to the Model Context Protocol (MCP) standards established by modelcontextprotocol.io:

📋 MCP Schema Compliance

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
  ...
}

✅ Uses official MCP server schema version 2025-10-17
✅ Validates all server metadata against published schema
✅ Supports all standard MCP properties and extensions

🏗️ Server Architecture Alignment

✅ Standardized Metadata: Every server includes name, title, description, version
✅ Transport Protocols: Supports MCP-standard transport types (streamable-http, stdio, etc.)
✅ Configuration Schema: Follows JSON Schema standards for server configuration
✅ Remote Definitions: Properly defines remote endpoints compatible with MCP clients

🔌 Protocol Interoperability

✅ Universal Format: Servers registered here work with any MCP-compatible client
✅ No Vendor Lock-in: Servers can be used with Claude, VS Code, or any MCP client
✅ Standard Discovery: Uses MCP discovery conventions for server location and metadata
✅ Features Declaration: Follows MCP standards for declaring server capabilities

📦 Feature Support

✅ Resources: Servers can expose files and data as MCP resources
✅ Tools: Servers can declare callable tools/functions
✅ Prompts: Servers can provide prompts for LLM contexts
✅ Sampling: Servers support sampling for LLM interactions
✅ Extensions: Supports custom MCP extensions per specification

🔄 Integration Compatibility

Your registry can be integrated with:

Claude (Anthropic): Connect via MCP client integration
VS Code: Use with MCP extensions
Custom Applications: Build MCP-client applications
Language Models: Any LLM with MCP support
Other Tools: Any tool implementing the MCP specification

Comparison: Public vs Private Registry

Feature	Public Registry	Private Registry (This)
Control	Limited	✅ Complete
Security	Standard	✅ Enhanced
Compliance	Generic	✅ Custom
Latency	Network-dependent	✅ Local
Proprietary Servers	❌ Not allowed	✅ Full support
Version Management	Limited	✅ Full control
Documentation	Generic	✅ Customizable
Offline Access	❌ No	✅ Yes
Cost	Free/Paid	✅ Self-hosted

�🎯 Overview

This project provides a centralized registry for Model Context Protocol servers with:

Backend API: FastAPI-based REST service for server discovery and metadata management
Frontend UI: Modern React TypeScript interface with card-based grid layout
8 Sample MCP Servers: Pre-configured templates for common use cases
Standards-Compliant: 100% compatible with MCP specification

📋 Features

Backend Features

✅ CORS enabled for cross-origin requests
✅ Dynamic server discovery from directory structure
✅ Support for server names with special characters (e.g., com.example/server-name)
✅ RESTful API endpoints for server listing and metadata retrieval
✅ Flexible server configuration schema support

Frontend Features

✅ Responsive grid layout for server cards
✅ Beautiful gradient design with smooth animations
✅ Server detail view with JSON metadata display
✅ Mobile-friendly interface
✅ Loading states and error handling

🚀 Quick Start

Prerequisites

Python 3.8+ with pip
Node.js 14+ with npm
Docker (optional, for containerization)

1. Backend Setup

# Navigate to project root
cd d:\github\pvt-mcp-registry

# Create and activate Python virtual environment
python -m venv env
.\env\Scripts\Activate.ps1

# Install Python dependencies
pip install fastapi uvicorn python-multipart pyyaml

# Start the backend server
uvicorn registry_api:app --reload --port 9000

The backend API will be available at http://localhost:9000

2. Frontend Setup

# Navigate to frontend directory
cd frontend/mcp-registry-ui-ts

# Install dependencies
npm install

# Start the development server
npm start

The frontend will be available at http://localhost:3000

📁 Project Structure

pvt-mcp-registry/
├── registry_api.py                 # FastAPI backend application
├── README.md                       # This file
├── env/                            # Python virtual environment
│
├── servers/                        # MCP Server configurations
│   ├── fastmcp-calculator/
│   │   ├── server.json            # Server metadata
│   │   ├── server.py              # Server implementation (optional)
│   │   └── dockerfile             # Docker configuration (optional)
│   │
│   ├── postgres-db-connector/     # PostgreSQL integration
│   ├── redis-cache-connector/     # Redis caching
│   ├── mongodb-connector/         # MongoDB database
│   ├── file-system-manager/       # File operations
│   ├── http-client-service/       # HTTP/REST client
│   ├── vector-database-connector/ # Vector DB (Pinecone, Weaviate, etc.)
│   └── search-engine-connector/   # Search engines (Elasticsearch, etc.)
│
└── frontend/
    └── mcp-registry-ui-ts/        # React TypeScript UI
        ├── src/
        │   ├── App.tsx            # Main application component
        │   ├── App.css            # Styling
        │   ├── types.ts           # TypeScript types
        │   └── index.tsx          # React entry point
        ├── package.json           # Dependencies
        └── tsconfig.json          # TypeScript configuration

🔗 API Endpoints

List All Servers

GET /v0/servers

Returns all registered MCP servers with their metadata.

Response:

{
  "servers": [
    {
      "name": "com.example/fastmcp-calculator",
      "title": "Calculator MCP (FastMCP)",
      "description": "A demo MCP-compatible calculator server",
      "version": "1.0.0",
      "remotes": [
        {
          "type": "streamable-http",
          "url": "http://localhost:7782"
        }
      ]
    }
  ]
}

Get Server Metadata

GET /v0/servers/{server_name}

Returns metadata for a specific server by name.

Example:

GET /v0/servers/com.example/postgres-db-connector

Response:

{
  "name": "com.example/postgres-db-connector",
  "title": "PostgreSQL Database Connector",
  "description": "MCP server for executing queries and managing PostgreSQL",
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "http://localhost:7783"
    }
  ],
  "features": ["SQL Query Execution", "Transaction Management", ...],
  "configurationSchema": { ... }
}

📦 Available MCP Servers

1. FastMCP Calculator 🧮

Purpose: Demo calculator server
Port: 7782
Features: Basic arithmetic operations

2. PostgreSQL Database Connector 🐘

Purpose: SQL database operations
Port: 7783
Features: Query execution, transactions, connection pooling

3. Redis Cache Connector ⚡

Purpose: In-memory caching and data structures
Port: 7784
Features: Key-value ops, pub/sub, transactions, Lua scripting

4. MongoDB Connector 🍃

Purpose: NoSQL document database
Port: 7787
Features: CRUD, aggregations, indexing, transactions

5. File System Manager 📁

Purpose: Safe file and directory operations
Port: 7785
Features: Read/write, permissions, metadata, watch changes

6. HTTP Client Service 🌐

Purpose: REST API and HTTP operations
Port: 7786
Features: All HTTP methods, auth, retries, SSL/TLS

7. Vector Database Connector 🔢

Purpose: AI/ML embeddings and similarity search
Port: 7788
Supports: Pinecone, Weaviate, Milvus, Qdrant, Chroma
Features: Embeddings, semantic search, batch ops

8. Search Engine Connector 🔍

Purpose: Full-text search and analytics
Port: 7789
Supports: Elasticsearch, OpenSearch, Solr, Typesense, MeiliSearch
Features: Full-text search, aggregations, indexing

🛠️ Adding New MCP Servers

To add a new MCP server to the registry:

Create a new directory in servers/:

mkdir servers/my-new-server

Create a server.json file with metadata:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
  "name": "com.example/my-new-server",
  "title": "My New Server",
  "description": "Description of what this server does",
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "http://localhost:7790"
    }
  ],
  "features": ["Feature 1", "Feature 2"],
  "configurationSchema": {
    "type": "object",
    "properties": {
      "key": {
        "type": "string",
        "description": "Configuration key"
      }
    }
  }
}

Restart the backend - The new server will automatically appear in the registry!

🎨 Frontend Customization

Styling

Main styles in frontend/mcp-registry-ui-ts/src/App.css
Color scheme: Purple gradient (#667eea to #764ba2)
Responsive design with mobile, tablet, and desktop breakpoints

Adding Features

Edit frontend/mcp-registry-ui-ts/src/App.tsx to:

Add filters or search functionality
Modify the card layout
Add more details to the detail view
Implement server interactions

🐳 Docker Support

Build Docker Image

docker build -t pvt-mcp-registry .

Run Container

docker run -p 9000:9000 -p 3000:3000 pvt-mcp-registry

🔧 Configuration

Backend Configuration

Edit registry_api.py to modify:

CORS settings: Change allow_origins to restrict domains
Server directory: Modify SERVERS_DIR path
Port: Change from 9000 to a different port

Frontend Configuration

Edit frontend/mcp-registry-ui-ts/src/App.tsx to modify:

API Base URL: Change API_BASE to point to your backend
UI Theme: Update color variables in App.css
Grid Layout: Adjust grid-template-columns in CSS

📝 Environment Variables

Backend

# Optional environment variables
SERVERS_DIR=./servers
PORT=9000

Frontend

# In frontend/mcp-registry-ui-ts/.env (create if needed)
REACT_APP_API_BASE=http://localhost:9000/v0/servers

🐛 Troubleshooting

Backend Issues

Port 9000 already in use:

# Use a different port
uvicorn registry_api:app --reload --port 8000

Module not found errors:

# Reinstall dependencies
pip install -r requirements.txt

CORS errors in frontend:

Ensure CORS is enabled in registry_api.py
Check that API_BASE URL matches backend URL

Frontend Issues

Dependencies not found:

# Clear cache and reinstall
rm -r node_modules package-lock.json
npm install

Port 3000 already in use:

# Use a different port
PORT=3001 npm start

📚 API Documentation

Request Headers

Content-Type: application/json
Accept: application/json

Response Codes

200 OK: Successful request
404 Not Found: Server not found
500 Internal Server Error: Server error

Error Response Format

{
  "detail": "Server metadata not found"
}

🚀 Deployment

Production Deployment

Backend:

# Use production ASGI server
pip install gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker registry_api:app

Frontend:

# Build production bundle
npm run build

# Serve with a static server or deploy to Netlify/Vercel
npm install -g serve
serve -s build

🤝 Contributing

To contribute to this project:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

📄 License

This project is provided as-is for educational and commercial use.

📞 Support

For issues, questions, or suggestions:

Check the troubleshooting section
Review the API documentation
Examine the sample servers for reference

🎓 Learning Resources

Built with ❤️ | Last Updated: November 2025

Pvt MCP Registry

快速接入

详细介绍