A comprehensive governance and monitoring solution for Model Context Protocol (MCP) servers that provides centralized management, real-time monitoring, and security enforcement through a unified FastMCP-based architecture.

graph TB subgraph "External Clients" A[MCP Clients] B[AI Assistants] C[Applications] end subgraph "MCP Governance Bridge" D[FastMCP Governance Server] E[Governance Engine] F[Usage Tracker] G[MongoDB Atlas Client] H[Config Loader] I[Streamlit Dashboard] end subgraph "Managed MCP Servers" J[Server 1<br/>stdio] K[Server 2<br/>HTTP] L[Server 3<br/>WebSocket] M[Server N<br/>...] end subgraph "Data Storage" N[(MongoDB Atlas)] end subgraph "Web Interface" O[Dashboard UI<br/>localhost:8501] end A --> D B --> D C --> D D --> E D --> F D --> G D --> H D --> J D --> K D --> L D --> M E --> G F --> G G --> N I --> G I --> O classDef client fill:#e1f5fe classDef governance fill:#f3e5f5 classDef server fill:#e8f5e8 classDef storage fill:#fff3e0 classDef ui fill:#fce4ec class A,B,C client class D,E,F,G,H governance class J,K,L,M server class N storage class I,O ui 

This diagram shows the high-level architecture of the MCP Governance Bridge:

• External Clients: Various MCP clients (AI assistants, applications) that need to interact with MCP servers
• Governance Bridge: The core system that acts as a proxy, providing governance, monitoring, and security
• Managed MCP Servers: The actual MCP servers being governed, supporting different transport protocols
• Data Storage: MongoDB Atlas for persistent storage of logs, metrics, and configuration
• Web Interface: Streamlit dashboard for monitoring and management

The bridge acts as a centralized governance layer that all clients must go through to access the underlying MCP servers.

flowchart TD subgraph "Tool Call Flow" A[Client Tool Request] --> B[Governance Middleware] B --> C{Governance Check} C -->|PASS| D[Execute Tool] C -->|FAIL| E[Deny Request] D --> F[Log Success] E --> G[Log Denial] F --> H[Return Result] G --> I[Return Error] end subgraph "Governance Policy Engine" J[Load Server Config] --> K[Time Restrictions] K --> L[Rate Limiting] L --> M[Security Patterns] M --> N[High Security Mode] N --> O[Policy Decision] end subgraph "Data Flow" P[Tool Invocation] --> Q[Store in MongoDB] Q --> R[Usage Analytics] R --> S[Dashboard Display] T[Governance Decision] --> U[Store Policy Log] U --> V[Compliance Reporting] end B --> J O --> C F --> P G --> T classDef request fill:#ffebee classDef process fill:#e8f5e8 classDef storage fill:#fff3e0 classDef decision fill:#f3e5f5 class A,P,T request class B,D,J,K,L,M,N,R process class Q,U,S,V storage class C,O decision 

This diagram illustrates the request processing flow:

1. Tool Call Flow: Shows how client requests are processed through the governance middleware
2. Governance Policy Engine: Details the multi-stage policy evaluation process
3. Data Flow: Demonstrates how data flows from execution to storage to dashboard visualization

The governance engine evaluates requests through multiple layers of security checks before allowing or denying access.

sequenceDiagram participant Client as MCP Client participant Middleware as Governance Middleware participant Engine as Governance Engine participant MongoDB as MongoDB Atlas participant Server as MCP Server participant Dashboard as Dashboard Note over Client,Dashboard: Tool Execution Flow Client->>Middleware: call_tool(name, args) Note over Middleware: Generate Session ID Middleware->>MongoDB: store_tool_log(invocation) Middleware->>Engine: check_governance(server, tool, args) Note over Engine: Policy Evaluation Engine->>Engine: check_time_restrictions() Engine->>Engine: check_rate_limit() Engine->>Engine: check_security_patterns() Engine->>Engine: check_high_security_mode() Engine->>MongoDB: store_governance_log(decision) alt Governance Check PASSES Engine-->>Middleware: {allowed: true} Middleware->>Server: execute_tool(name, args) Server-->>Middleware: tool_result Middleware->>MongoDB: store_tool_log(success) Middleware-->>Client: tool_result else Governance Check FAILS Engine-->>Middleware: {allowed: false, reason} Middleware->>MongoDB: store_tool_log(denied) Middleware-->>Client: GovernanceError(reason) end Note over Dashboard: Real-time Updates Dashboard->>MongoDB: get_usage_metrics() Dashboard->>MongoDB: get_governance_violations() Dashboard->>MongoDB: get_tool_logs() MongoDB-->>Dashboard: aggregated_data Note over Dashboard: Display Updates Dashboard->>Dashboard: update_charts() Dashboard->>Dashboard: refresh_metrics() 

This sequence diagram shows the complete lifecycle of a tool execution request:

1. Initial Request: Client sends a tool call to the governance middleware
2. Logging Start: Middleware logs the invocation attempt to MongoDB
3. Governance Check: Engine evaluates the request against multiple policy layers:
   • Time restrictions (allowed hours)
   • Rate limiting (requests per minute)
   • Security patterns (dangerous operations)
   • High security mode (additional restrictions)
4. Decision Storage: The governance decision is logged for audit purposes
5. Execution Path: Based on the decision:
   • Allowed: Tool is executed on the target server, result is returned and logged
   • Denied: Request is blocked, error is returned and logged
6. Dashboard Updates: The dashboard continuously queries MongoDB for real-time metrics and updates

graph LR subgraph "Data Sources" A[Tool Invocations] B[Governance Decisions] C[Server Status] D[Configuration Changes] end subgraph "Data Processing" E[MongoDB Collections] F[Aggregation Pipeline] G[Analytics Engine] end subgraph "Data Consumers" H[Dashboard Charts] I[Compliance Reports] J[Alert System] K[Export Functions] end A --> E B --> E C --> E D --> E E --> F F --> G G --> H G --> I G --> J G --> K subgraph "MongoDB Collections Detail" E1[tool_logs] E2[governance_logs] E3[servers] E4[server_tools] E5[governance_configs] end E --> E1 E --> E2 E --> E3 E --> E4 E --> E5 classDef source fill:#e3f2fd classDef process fill:#f3e5f5 classDef consumer fill:#e8f5e8 classDef collection fill:#fff3e0 class A,B,C,D source class E,F,G process class H,I,J,K consumer class E1,E2,E3,E4,E5 collection 

This diagram illustrates how data flows through the system:

• Data Sources: Various events and state changes that generate data
• Data Processing: MongoDB storage and aggregation pipeline for analytics
• Data Consumers: Different ways the processed data is consumed and presented
• MongoDB Collections: Specific database collections that store different types of data

The system maintains a comprehensive audit trail while providing real-time analytics and reporting capabilities.

• Multi-Mode Architecture: Unified, multi-port, and hybrid deployment modes
• Real-time Tool Monitoring: Comprehensive logging and analytics
• Security Enforcement: Pattern blocking, rate limiting, time restrictions
• Policy Management: Configurable governance policies per server
• Compliance Tracking: Detailed audit logs and violation reports

• Interactive Dashboard: Real-time Streamlit-based web interface
• Usage Analytics: Tool performance metrics and usage patterns
• Server Health: Status monitoring and uptime tracking
• Violation Alerts: Governance policy violation detection

• MongoDB Atlas Integration: Scalable cloud database storage
• Structured Logging: Comprehensive tool execution logs
• Data Export: JSON export functionality for compliance
• Real-time Metrics: Live dashboard updates

• Python 3.11+
• MongoDB Atlas account and connection string
• UV package manager (recommended) or pip
• Git for cloning the repository

1. Clone the repository

git clone https://github.com/mongodb-partners/mcp-governance-bridge cd mcp-governance-bridge

2. Install dependencies

uv sync # or with pip pip install -r requirements.txt

3. Configure MongoDB

# Set environment variable export MONGODB_URI="mongodb+srv://<username>:<password>@cluster.mongodb.net/mcp_governance" # or create .env file echo "MONGODB_URI=mongodb+srv://<username>:<password>@cluster.mongodb.net/mcp_governance" > .env

4. Create configuration file

cp config.example.json mcp_governance_config.json # Edit with your MCP server configurations

{ "governance": { "deployment_mode": "unified", "base_port": 8173, "enable_tracking": true, "enable_dashboard": true, "mongodb_uri": "mongodb+srv://...", "auth_disabled": true, "transformation_strategy": "fastmcp_native" }, "mcpServers": { "weather-server": { "transport": "stdio", "command": "python", "args": ["-m", "weather_server"], "env": { "WEATHER_API_KEY": "your-api-key" }, "governance": { "mode": "unified", "rate_limit": 100, "high_security": false, "allowed_hours": [9, 10, 11, 12, 13, 14, 15, 16, 17], "governance_prefix": "governed_", "detailed_tracking": true } } } }

• Unified Mode: All servers behind single governance proxy
• Multi-Port Mode: Each server on separate governed port
• Hybrid Mode: Mix of unified and separate deployments

• Rate Limiting: Requests per minute per server
• Time Restrictions: Allowed hours of operation
• Security Patterns: Block dangerous operations
• High Security Mode: Enhanced security checks
• Detailed Tracking: Comprehensive usage logging

# Using the provided launcher chmod +x run.sh ./run.sh

# Start main governance server uv run app/main.py # Start dashboard (in another terminal) uv run streamlit run dashboard/streamlit_dashboard.py --server.port=8501

• Dashboard: http://localhost:8501
• Main Server: http://localhost:8173 (unified mode)
• API Documentation: http://localhost:8173/docs

• System status and health metrics
• Tool usage statistics
• Success rate analytics
• Server activity monitoring

• Server configuration management
• Health status monitoring
• Individual server metrics
• Tool inventory per server

• Performance metrics
• Usage patterns
• Success/failure rates
• Duration analytics

• Policy compliance monitoring
• Violation tracking
• Decision audit logs
• Policy effectiveness analysis

• Detailed execution logs
• Input/output tracking
• Error analysis
• Session monitoring

• Database connection status
• Collection statistics
• Configuration export
• System maintenance

# Example governance policy { "max_requests_per_minute": 100, "allowed_hours": [9, 10, 11, 12, 13, 14, 15, 16, 17], "blocked_patterns": [ r"(password|secret|token|key)\s*[:=]\s*\w+", r"(rm|del|delete)\s+-rf", r"drop\s+table", r"eval\s*\(", r"exec\s*\(" ], "high_security_mode": false }

• Real-time violation detection
• Policy breach notifications
• Usage anomaly detection
• Compliance reporting

{ "session_id": "uuid", "server_name": "weather-server", "tool_name": "get_weather", "event_type": "tool_completion", "start_time": "2024-01-01T10:00:00Z", "end_time": "2024-01-01T10:00:01Z", "duration_ms": 1000, "status": "success", "inputs": {...}, "outputs": {...}, "error_message": null }

{ "server_name": "weather-server", "tool_name": "get_weather", "decision": "allowed", "policy_applied": {...}, "timestamp": "2024-01-01T10:00:00Z", "governance_version": "1.0" }

# Get tool logs GET /governance/tool-logs?server_name=weather-server&hours=24 # Get server status GET /governance/servers # Get governance metrics GET /governance/metrics?hours=24 # Get violations GET /governance/violations?hours=24

# System status GET / # Dashboard redirect GET /dashboard

• Tool execution counts
• Success/failure rates
• Average execution time
• Server utilization
• User session tracking

• Policy compliance rates
• Violation frequency
• Security pattern matches
• Rate limit breaches
• Time restriction violations

• Response times
• Throughput analysis
• Error rates
• Resource utilization
• Database performance

# Run unit tests uv run pytest tests/ # Test with coverage uv run pytest tests/ --cov=app --cov=core --cov=database # Integration tests uv run pytest tests/integration/ # Load testing uv run pytest tests/load/

1. MongoDB Connection Failed

# Check connection string echo $MONGODB_URI # Verify network access ping cluster.mongodb.net

2. Server Not Starting

# Check logs tail -f logs/mcp_governance.log # Verify port availability lsof -i :8173

3. Dashboard Loading Issues

# Clear Streamlit cache rm -rf ~/.streamlit/ # Restart dashboard uv run streamlit run dashboard/streamlit_dashboard.py --server.port=8501

# Enable debug logging export LOG_LEVEL=DEBUG uv run app/main.py

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

# Install development dependencies uv sync --dev # Run code formatting uv run black . # Run linting uv run flake8 . # Run type checking uv run mypy .

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

• Built with FastMCP
• Dashboard powered by Streamlit
• Data storage with MongoDB Atlas
• Visualization with Plotly

For support, please:

1. Check the troubleshooting guide
2. Search existing issues
3. Create a new issue with detailed information
4. Contact the development team

MCP Governance Bridge - Secure, scalable, and comprehensive MCP server management solution.

Note: This repository contains a reference implementation intended for educational and exploratory purposes only. It is not production-ready in its current form.

While the architecture and design patterns demonstrated here reflect best practices for building governance layers for MCP systems, the implementation may lack:

• Comprehensive test coverage
• Robust error handling and validation
• Security hardening and access controls
• Performance optimizations for scale
• Long-term support or upgrade guarantees

Use this as a foundation to guide your own production implementations, but ensure thorough validation and customization before deploying in real-world environments.