mcp-registry

Executive Summary

The mcp-registry repository provides a production-grade, centralized catalog and discovery registry for the Model Context Protocol (MCP). It indexes enterprise MCP tools, resources, and prompt templates with strict JSON schema validation and Role-Based Access Control (RBAC) filtering.

Related MCP server: agent-discover

Business Problem

As autonomous AI agents expand across an enterprise, discovering and governing available MCP tools faces operational challenges:

• Shadow Tool Sprawl: Unmonitored MCP tool servers registered directly by developers introduce unvetted execution endpoints.

• Malformed Input Payloads: Invalid tool argument schemas lead to runtime agent crashes and unhandled exceptions.

• Unrestricted Access: Lack of role-based tool discovery allows low-privilege agents to invoke sensitive administrative operations.

Business Value

• Centralized Governance Catalog: Single source of truth for all approved MCP tools, resource URIs, and prompt templates across the organization.

• Strict Schema Enforcement: Validates JSON schema definitions during tool registration to prevent invalid parameter calls.

• Role-Based Access Control (RBAC): Dynamically filters tool discovery queries based on the calling user or agent's authorized roles.

Architecture

High-Level Execution Sequence

graph TD
    Client["AI Agent / Assistant Client"] --> RegistryAPI["MCP Registry REST API"]
    RegistryAPI --> CatalogService["Central Tool Catalog Service"]
    RegistryAPI --> SchemaValidator["JSON Schema Validator"]
    RegistryAPI --> PromptStore["Prompt Template Store"]
    CatalogService --> RBACFilter["Role-Based Access Control Filter"]
    RBACFilter --> FilteredTools["Accessible MCP Tools & Resources"]

Core Components

• Central Tool Catalog Service (src/mcp_registry/core/catalog.py): Core indexer storing tool definitions, server mappings, and role permissions.

• JSON Schema Validator (src/mcp_registry/validators/schema_validator.py): Validates input schema definitions during tool registration.

• Prompt Template Store (src/mcp_registry/services/prompt_store.py): Stores and serves standardized enterprise prompt templates.

• FastAPI Async API Layer (src/mcp_registry/api/routes.py): REST endpoints for tool registration, RBAC filtering, and prompt listing.

Repository Structure

mcp-registry/
├── .github/              # CI/CD workflows, issue & PR templates, CODEOWNERS
├── architecture/         # Mermaid sequence flow diagrams
├── deployment/           # Kubernetes manifests & Kustomize environment overlays
├── docs/                 # Enterprise architectural, deployment, & operational guides
├── examples/             # Real-world request/response JSON payloads
├── images/               # High-resolution architecture & workflow diagrams
├── src/mcp_registry/     # Python Registry source (api, core, services, validators)
├── terraform/            # Multi-cloud OpenTofu / Terraform IaC modules
├── tests/                # Unit, integration, and API test suites
├── Dockerfile            # Container build specification
├── docker-compose.yml    # Multi-container local orchestration
├── pyproject.toml        # PEP 621 package configuration
└── README.md             # Accelerator documentation manual

Capabilities

• Tool Registration & Discovery: Endpoint for registering new MCP tools and discovering available schemas.

• RBAC Tool Filtering: Dynamic filtering based on caller role declarations.

• Prompt Template Management: Centralized repository for versioned prompt templates.

• Multi-Cloud IaC Automation: OpenTofu and Terraform modules for AWS VPC, IAM, ECS, and CloudWatch metrics.

Technology Stack

• Core Registry: Python 3.11+, FastAPI 0.110+, Pydantic v2

• Infrastructure as Code: OpenTofu 1.8.5 / Terraform 1.6+

• Containerization: Docker, Docker Compose, Kubernetes 1.28+

• Quality Assurance: Pytest 8.0+, GitHub Actions CI

Implementation

# Clone repository
git clone https://github.com/Devopstrio/mcp-registry.git
cd mcp-registry

# Install in editable mode
pip install -e .[dev]

# Run automated unit and integration tests
pytest -v tests/

Deployment

OpenTofu / Terraform Provisioning

cd terraform
tofu init
tofu plan
tofu apply -auto-approve

Kubernetes Kustomize Deployment

kubectl apply -k deployment/kubernetes/overlays/prod/

API Reference

• GET /health — Returns registry health status and version.

• POST /api/v1/tools/register — Registers an MCP tool with schema validation.

• POST /api/v1/tools/filter — Returns accessible tools based on RBAC user roles.

• GET /api/v1/prompts — Lists registered prompt templates.

Examples

• examples/tool-registration/ — MCP tool registration payload

• examples/prompt-template-store/ — Prompt template listing payload

• examples/rbac-tool-filtering/ — RBAC tool filtering payload

Security

Refer to SECURITY.md for reporting security vulnerabilities. The registry enforces schema validation and role-based access filtering.

Observability

The platform exports structured CloudWatch log groups (/aws/mcp-registry/mcp-registry) and metric alarms for invalid schema registration attempts.

Scalability

Horizontal pod autoscaling (HPA) overlays scale registry replicas dynamically based on query volume.

Multi-cloud Strategy

Infrastructure blueprints support AWS ECS/VPC deployment with modular extensions for multi-cluster registry synchronization.

Roadmap

See docs/Roadmap.md for upcoming milestones including active MCP server health probing and semantic versioning support.

Contribution

See CONTRIBUTING.md and CODE_OF_CONDUCT.md for community standards and contribution workflows.